# Query String Codec

Free online query string codec: parse URL query strings into JSON or build encoded query strings from JSON, with arrays and bracket notation.

## Run it

- **CLI:** `gizza tool query-string-codec 'direction=parse'`
- **Web:** https://gizza.ai/tools/query-string-codec/
- **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/query-string-codec/tool.json

## Inputs

- `direction` — Direction _(field)_
- `input` — Input _(field)_
- `array_style` — Array style (build mode) _(field)_
- `space_as_plus` — Use + for spaces _(field)_
- `sort_keys` — Sort keys when building _(field)_
- `prefix_question_mark` — Prefix built query with ? _(field)_

## Output

- Result (text)

## Query parameters

Open the tool pre-filled and auto-run via URL:

- `direction` — Direction
- `input` — Input
- `array_style` — Array style (build mode)
- `space_as_plus` — Use + for spaces
- `sort_keys` — Sort keys when building
- `prefix_question_mark` — Prefix built query with ?

Example: `https://gizza.ai/tools/query-string-codec/?direction=parse&input=name%3DJohn%2BDoe%26color%3Dred%26color%3Dblue%26user%5Bage%5D%3D30&array_style=brackets&space_as_plus=true&sort_keys=true&prefix_question_mark=true`

---

## About this tool

**Query String Codec** converts between URL query strings and structured JSON in both directions.
Use it to inspect a long URL's parameters, debug form-encoded API calls, or build a query string
from a JSON object without hand-escaping spaces, brackets, or unicode.

In **Query string → JSON** mode, the tool accepts a bare query string or one with a leading `?`.
It splits on `&` and `;`, percent-decodes keys and values, decodes `+` as a space by default, turns
repeated keys into arrays, and expands common bracket notation such as `tags[]`, `tags[0]`, and
`user[name]` into nested arrays and objects.

In **JSON → query string** mode, paste a JSON object and choose how arrays should be serialized:
`tags[]=a&tags[]=b`, `tags[0]=a&tags[1]=b`, `tags=a&tags=b`, or `tags=a,b`. You can also sort keys,
use `%20` instead of `+` for spaces, and add a leading `?`.

### Worked example

Input query string:

```
name=John+Doe&color=red&color=blue&user[age]=30
```

Output JSON:

```json
{
  "name": "John Doe",
  "color": [
    "red",
    "blue"
  ],
  "user": {
    "age": "30"
  }
}
```

Switch to **JSON → query string**, paste `{"tags":["a","b"]}`, and choose **repeat** to get
`tags=a&tags=b` or **indices** to get `tags[0]=a&tags[1]=b`.

## FAQ

<!-- FAQ MUST be <details>/<summary> accordions with a blank line inside each. -->

<details>
<summary>Does parsing a query string infer numbers and booleans?</summary>

No. Query strings carry text, so parsed values stay strings. `age=30` becomes `"30"`, not the number
`30`. When building from JSON, numbers and booleans are serialized to their normal text form.

</details>

<details>
<summary>Which array styles round-trip?</summary>

`brackets`, `indices`, and `repeat` round-trip through parse as arrays. `comma` is compact for APIs
that expect `tags=a,b`, but parse intentionally leaves it as the string `"a,b"` because commas are
valid data too.

</details>

<details>
<summary>What does “Use + for spaces” change?</summary>

With the option on (default), build mode writes spaces as `+` and parse mode decodes `+` back to a
space, matching HTML form encoding. Turn it off for stricter RFC 3986 style: build writes `%20`, and
parse keeps literal plus signs as `+`.

</details>

<details>
<summary>Is the query string uploaded or fetched?</summary>

No. The codec is pure WebAssembly running in your browser. It never fetches URLs; it only parses or
builds the text you paste.

</details>

## Limits & edge cases

- **Top-level build input must be a JSON object.** Arrays or scalars at the root are rejected so every
  value has a query parameter name.
- **Invalid percent escapes are lenient.** A malformed `%` sequence is left literal instead of aborting.
- **Nested arrays/objects are supported for bracket and index styles.** Comma style requires scalar
  array items.
- **Parse output is strings.** Use a downstream JSON tool if you need type inference.
- **Key ordering in build mode follows input JSON order** unless you enable **Sort keys when building**.

## Related tools

- [Query String Parser](https://gizza.ai/tools/parse-query-string/): Parse a URL query string into key/value pairs and structured JSON — repeated keys, PHP/Rails bracket notation, percent and + decoding. Free, in your browser.
- [URI / URL Parser](https://gizza.ai/tools/parse-uri/): Parse a URI or URL into scheme, user info, host, port, path, percent-decoded query parameters, and fragment — free and private, right in your browser.
- [Base32 Encoder / Decoder](https://gizza.ai/tools/base32-codec/): Free Base32 encoder and decoder in your browser — RFC 4648, base32hex, Crockford and z-base-32 variants, hex byte I/O, optional padding. Private, no sign-up.
- [Base58 Encoder / Decoder](https://gizza.ai/tools/base58-codec/): Encode text or bytes to Base58 and decode Base58 back in your browser — Bitcoin/IPFS, Ripple (XRP) and Flickr alphabets, hex I/O. Free, private, no sign-up.
- [Base62 Encoder / Decoder](https://gizza.ai/tools/base62-codec/): Encode text, hex bytes, or numbers to Base62 (0-9A-Za-z) and decode back — URL-safe, no padding, arbitrary-precision numbers. Free, private, in your browser.