In JavaScript, a query string is the text after the question mark in a URL, encoded with the application/x-www-form-urlencoded rules defined by the WHATWG URL Standard and exposed to scripts through the browser's URLSearchParams interface; parsing it means turning that text into a structured object you can read or build back into a new query string. A parser that follows these rules will decode percent escapes, treat plus signs as spaces, preserve empty values, and retain every occurrence of a repeated key as an ordered array rather than silently overwriting earlier values. Because no universal convention exists for nested data inside a query string, the safest parsers reject nested JSON on the rebuild side and accept only flat scalars or flat arrays of scalars. The same source contract powers both directions of conversion, which is why a single-purpose parser can replace hand-written split-and-decode routines that tend to drift from the spec, mishandle Unicode, or break the moment a parameter repeats.
The shape of a JavaScript query string
A query string is everything after the question mark in a URL, made of name=value pairs joined by ampersand. In JavaScript you normally meet it as window.location.search, as the second argument to fetch, or as the body of an application/x-www-form-urlencoded POST. Parsing means converting that flat text into a structured shape you can inspect, log, replay, or feed into another function.
The browser gives you URLSearchParams for this work, and that object is the reference implementation behind any tool that claims to follow the WHATWG URL Standard. Manually splitting on ampersand and equals works for trivial inputs, but it falls over quickly: it ignores percent escapes, mishandles plus signs, drops repeated keys, and silently breaks when a value contains ampersand, equals, or a non-ASCII character. The spec-aware path is what the Query String Parser tool runs, so the result you see in the tab matches what new URLSearchParams(text) would produce in the console. When parsing by hand becomes part of a CI pipeline, the same edge cases show up in fixtures and in production traffic, which is why offloading the work to a deterministic parser is usually a better trade than maintaining a private regex.
The bidirectional workflow the tool follows
The tool accepts work in two directions, both anchored to the WHATWG and MDN rules. The behavior is fixed: there is one spec to follow, not several competing conventions to reconcile.
| Direction | Accepts | Rejects or flags |
|---|---|---|
| Query to JSON | Text with or without a leading question mark, percent escapes, plus signs, repeated names, empty values, missing equals signs, UTF-8 bytes | Full URLs whose path can be mistaken for a parameter name; use the URL Parser first |
| JSON to query | Flat objects whose values are strings, finite numbers, booleans, null, or arrays of those scalars | Nested objects, nested arrays, and empty arrays (omitted on encode because nothing would append) |
That single contract is the reason a parser built around URLSearchParams can replace half a dozen one-off regexes in a typical codebase. When the receiving service disagrees, for example when it splits a single value on commas or always emits an array, that is a server-side convention rather than a parsing bug, and it has to be handled after the converter hands you the structured data.
Parse a query string into JSON, step by step
This is the direction most developers reach for when they want to inspect or log a URL parameter set. The Query String Parser follows the same decoding rules as the browser, so the result you see in the tab matches what your code sees at runtime.
- Copy the query component. If you have a full URL, paste it only when you specifically want the tool to treat the path as data; otherwise extract everything after the first question mark and before any hash yourself. The tool tolerates a leading question mark and strips it, so ?tag=a&tag=b and tag=a&tag=b produce the same JSON.
- Open the Query String Parser and choose the query-to-JSON direction.
- Paste the query text into the input field and run the conversion.
- Inspect the JSON output. Check two things first: any key that appears more than once in the input should now be a JSON array in encounter order, and any value that was key= with nothing after the equals should be an empty string, not null and not missing.
- Copy the JSON and validate it against the receiving system. If your API keeps only the last value of a duplicate key, the array the tool hands you will not match. Switch to the server convention that the API documents, or send two requests.
For a quick sanity check, the WHATWG URL Standard and the MDN URLSearchParams reference document the same behaviors, so anything the tool produces should be reproducible with a one-liner in your console.
Build a query string from a flat JSON object, step by step
The reverse direction is what you reach for when you need to construct an API call, a log fixture, or a test body. The shape is deliberately restricted because the tool refuses to guess how nested data should be flattened.
- Compose a flat JSON object. The keys must be strings; the values must be strings, finite numbers, booleans, null, or arrays of those scalars. The text "2" must stay a string because the tool does not perform type inference; the wire format carries text, not a numeric type declaration.
- Open the Query String Parser and choose the JSON-to-query direction.
- Paste the JSON object and run the conversion.
- Inspect the encoded output. Spaces become plus signs, literal plus signs become %2B, reserved characters such as ampersand and equals are percent-encoded only when they appear inside a value, and Unicode text is round-tripped through UTF-8 percent encoding.
- Copy the result and validate it against the API contract. Null becomes an empty value (key=), empty arrays are dropped because they have nothing to append, and a single-element array is preserved as one occurrence rather than promoted to a duplicate of a string.
Edge cases the spec resolves for you
These behaviors are part of the contract, not nice-to-haves, and they are why hand-written parsers tend to break in production. Knowing them up front is what lets you skip writing a parser at all.
| Aspect | How the tool handles it |
|---|---|
| Leading question mark | Optional in query-to-JSON, stripped before parsing |
| Plus sign in a value | Decoded as a space when reading |
| Literal plus meant as data | Must arrive as %2B in the source text |
| Empty value (key=) | Preserved as an empty string, not dropped |
| Repeated key | Becomes an ordered JSON array |
| Unicode in a value | Round-tripped through UTF-8 percent encoding |
| Ampersand or equals inside a value | Percent-encoded, not treated as separators |
| Number-like text such as 2 | Stays a JSON string, no type inference performed |
The number-like text row is the one that surprises people most. The query format is text, so the integer 2 and the string "2" are indistinguishable on the wire; the tool keeps the safer string form so downstream code can decide whether to coerce it. If your server stores IDs as integers and you need them parsed back that way, do that coercion in the application code that consumes the JSON, not in the parser.
When not to re-encode: signatures and cache keys
If the URL or body you are parsing carries a signature, an OAuth state value, or a cache key that depends on parameter order, do not let the tool round-trip the bytes back into a query string. Reordering, the choice between plus and %20, and the exact percent-escape spelling can all be covered by the signature algorithm. Preserve the original serialized bytes when the signing protocol does not document canonicalization, and use the protocol's own encoder when it does.
The WHATWG and MDN behavior produces a valid, interoperable query string, but "valid" and "canonical for this signed endpoint" are not the same thing. The same caution applies to API gateways that hash the raw query string for caching: a single re-encoded space or reordered parameter can shift the cache key and turn a cached response into a cache miss. Treat the Query String Parser as a debugger and a builder, rather than a canonicalizer, and keep a copy of the original text alongside any round-tripped output until you have confirmed the receiving system accepts it.
Why local processing matters for query data
Query strings are unusually leaky: search history, referrer headers, server logs, analytics pipelines, and corporate proxies all see them. The conversion itself runs in the browser and nothing is uploaded, but the text you paste into a tool still carries identifiers you would not normally share in chat or in a screenshot. Redact session tokens, email addresses, and tracking parameters before pasting, and run the Query String Parser inside the tab where the URL already lives when the value is sensitive.
A 200,000-character limit bounds work in the current tab, which is plenty for typical search, analytics, and form payloads but a real ceiling for someone trying to paste a deeply nested signed request. When the limit matters, split the work into smaller pieces or reach for the protocol's own encoder instead of a general-purpose converter.
For a deeper look, see Regex Cheat Sheet API Alternative for JavaScript Tokens.
For a deeper look, see Parse a URL in Python and Verify It Against the Browser.