JSON URL Encode

Putting JSON in a URL

You have a filter object, a config blob, or a bit of state that needs to ride along in a link. The API takes it as a query parameter, so the JSON has to become something a URL can carry — and JSON is made almost entirely of characters that a query string treats as punctuation. Braces, quotes, colons and commas all have to be escaped, which is why an encoded payload comes back looking like nothing you wrote.

The plain URL encoder will do the escaping. What it will not do is tell you the JSON was broken before you started. Percent-encoding does not care what it is escaping — feed it a document with a trailing comma and it hands back a perfectly well-formed encoded string that fails at the far end, where the error message will be about the request rather than about your JSON. This page parses the document first and stops if it will not parse.

The other thing it does is get the payload smaller. Indentation costs nothing in a file and a great deal in a URL, because every space becomes %20 — three characters instead of one. The sample on this page is 141 characters as pasted and 109 minified, which turns into 273 encoded characters against 177. That is a third of the length gone before you have changed anything that matters.

Minifying goes through the same lossless parser the rest of this site uses, so a long integer is not quietly rounded on the way through. That is not a theoretical concern: JSON.stringify(JSON.parse(…)) turns an ICCID of 8901240544102066246 into 8901240544102066000, because JavaScript numbers are doubles and run out of precision around sixteen digits. Minify here and every digit is still there.

How to use it

1. Paste the JSON – Type it, paste it, or upload a .json file. If it will not parse you get told where, and nothing is encoded — an encoded broken document is the failure that is hardest to debug later.
2. Leave "Minify first" on – It strips indentation and nothing else. The chip shows how many characters it saved so you can see the trade rather than take it on trust.
3. Keep the style on "One value" – That is encodeURIComponent, and it is what you want when the JSON is going into a single parameter. "Whole URL" is the wrong answer here and the example below shows exactly how it fails.
4. Watch the length chip – Past about 2000 characters you are in territory where some proxies and older servers will truncate or refuse the request. There is no limit in RFC 3986 itself — the ceiling is infrastructure, not spec, which is why it varies and why it bites in production rather than on your machine.
5. Copy it into the parameter – The output is the parameter value. Do not escape it a second time on the way in — see the double-encoding question in the FAQ, because doing it twice is the most common way this goes wrong.

If the payload is heading for a link people will paste into chat or a ticket, encode it and then check the length before you commit to the design. A 3KB filter object works perfectly in testing and gets silently cut in half by a corporate proxy, and the symptom at the far end is a JSON parse error that points at the middle of a word.

Why "Whole URL" is the wrong style here

This is the mistake worth showing, because the reasoning behind it sounds right. Your payload is going into a URL, so "Whole URL" seems like the honest choice. It is not — that style deliberately leaves &, = and # alone, because in a whole URL those characters are structure. Inside a parameter value they are still structure, just not yours. Here is a payload with all three, encoded both ways and then read back with URLSearchParams:

{"note":"SIM swap & re-test",
 "q":"a=b",
 "tag":"#urgent"}

# three characters a query
# string treats as structure

# One value — escapes all three
{"note":"SIM swap & re-test",
 "q":"a=b","tag":"#urgent"}
# identical to what went in ✓

# Whole URL — leaves them bare,
# so the value ends at the &
{"note":"SIM swap 
# everything after it is gone,
# and nothing raised an error

When this comes up

A shareable filter or search link

Dashboards and admin tools often keep their whole filter state in the URL so a link reproduces exactly what someone was looking at. The state is JSON, the URL is a string, and this is the join between them. Keep the object as small as you can — short keys and no indentation — because the link is going to end up in a chat message where length is visible.

An API that takes a JSON query parameter

Plenty of read APIs accept a filter document on a GET rather than a POST, so the request stays cacheable and idempotent. That design is fine right up until the payload grows past what the infrastructure in front of the service will carry, which is the point at which the length chip on this page starts earning its keep.

Reproducing a bug from a URL someone sent you

A colleague pastes a link that misbehaves and you want the payload out of it. Run it through JSON URL Decode to get the document back and pretty-printed, change one field, and re-encode it here. That loop is much faster than editing percent-escapes by hand, and it is a lot harder to get wrong.

OAuth state and redirect parameters

The state parameter in an OAuth flow is a natural place for a small JSON object, and it is nested inside a redirect_uri that is itself a parameter. That is where double-encoding creeps in, because one layer is often applied for you and the second one by hand.

What this page does

• Parses the JSON before encoding anything, and refuses rather than handing back a well-formed encoding of a broken document.
• Minifies losslessly — a 19-digit identifier keeps all 19 digits and stays an integer rather than becoming a quoted string.
• Reports how many characters the minify saved, so the trade is visible rather than assumed.
• Warns once the encoded length passes 2000 characters, which is where infrastructure limits start to matter.
• Offers all three encoding styles, with the one you actually want as the default.
• Runs entirely in your browser. The payload is not uploaded anywhere, which matters given how often a filter object holds identifiers.

Questions people actually ask

Why is my encoded JSON so much longer than the original?

Because almost every structural character in JSON has to be escaped, and each one becomes three characters. A brace is %7B, a quote is %22, a colon is %3A. The sample here goes from 109 characters to 177 — and that is after minifying. Roughly a 60% increase is normal for a compact document, and much worse for an indented one.

What is double encoding, and how do I know it happened?

It is what you get when a value is escaped twice: %20 becomes %2520, because the % itself gets escaped on the second pass. The giveaway is a string full of %25. It usually happens when a library escapes the parameter for you and you also escape it by hand. JSON URL Decode flags it when it sees it, because one decode leaves you holding %20 as literal text rather than a space.

Does minifying change my data?

It removes whitespace between tokens and nothing else. Keys, values, ordering and types all survive, including numbers too long for a JavaScript double — that is the whole point of the lossless parser behind it. If you would rather send exactly the bytes you pasted, turn the toggle off; the document is still validated either way.

Should I use Base64 instead?

Sometimes, and it is a real alternative rather than a worse one. Base64 is a fixed 33% overhead where percent-encoding is variable and often worse for JSON, and the result carries no characters a URL cares about. The cost is that the payload stops being readable in the link and stops being greppable in your logs. JSON to Base64 does that side if you want to compare the two lengths on your own document.

Is there a real maximum URL length?

Not in the standard. RFC 3986 sets no limit at all. What exists instead is a pile of implementation limits — browsers, proxies, load balancers, server request-line buffers — and the practical answer people converged on is to stay under about 2000 characters. Above that you are relying on every hop being generous.

Why does the form field style use + for spaces?

Because application/x-www-form-urlencoded predates the current URL rules and defines its own escaping, where a space is + rather than %20. The WHATWG URL Standard still specifies it that way because too much of the web depends on it. It matters on decode more than encode: reading + as a literal plus when it meant a space is a silent corruption, not an error.

Related tools

References

• RFC 3986 §2.1 — Percent-Encoding – The rule itself, and the reserved set it protects
• RFC 8259 — The JSON Data Interchange Format – Including the note on numbers that lose precision
• MDN — URL.searchParams – How a browser reads a query string back