URL Encoder

What percent-encoding is for

A URL is a structured string, and several characters carry meaning as delimiters. The colon separates scheme from authority, the slash separates path segments, the question mark starts the query string, the ampersand separates parameters, and the equals sign separates each key from its value.

That structure breaks the moment a value contains one of those characters. If a search term is bed & breakfast, putting it raw into a query string produces ?q=bed & breakfast, which any parser will read as a parameter named q with value bed, plus an empty parameter named breakfast. The data is not corrupted in a way that throws an error — it is silently reinterpreted, which is worse.

Percent-encoding solves this by replacing each reserved character with a percent sign followed by two hexadecimal digits representing its byte value. A space becomes %20, an ampersand becomes %26, a question mark becomes %3F. A parser reading the encoded form sees a value with no structural characters in it and treats the whole thing as data.

The same rule applies outside URLs. Form bodies, cookies and some HTTP header values all use the same mechanism, and all have the same failure mode when a reserved character slips through unencoded.

The four encodings, and exactly what each preserves

The difference between them is which characters are treated as structure and therefore left alone. Everything else gets escaped.

Query value escapes everything except unreserved characters — letters, digits, and - _ . ! ~ * plus the apostrophe and both parentheses. Crucially it escapes &, =, ?, + and #, so a value containing any of them cannot break out of its parameter. This is the mode to use for essentially every value you put in a query string.

Whole URL keeps the structural characters intact — :, /, ?, &, =, # — because the input is already a complete URL and you want to escape only the unsafe parts within it, such as spaces and non-ASCII characters. Using this mode on a bare value is the mistake described next.

Path segment escapes slashes as well as query delimiters, so a value being placed as one segment of a path cannot add extra path levels. This is what you want for a filename or a slug built from user input.

Everything applies the strictest RFC 3986 rule and escapes every character outside the unreserved set, delimiters included. Use it when the output is an opaque token rather than a URL, or when a specification demands it.

The ampersand bug: why picking the wrong mode is not harmless

This deserves spelling out because the failure is silent and the mode choice looks cosmetic.

Suppose a user searches for salt & pepper. You build a URL by interpolating the raw term: ?q=salt & pepper. The server receives two parameters: q=salt and pepper with no value. The search returns results for salt, the user does not notice the missing half, and you get a bug report three weeks later that cannot be reproduced.

Now suppose you encode it with the Whole URL mode by mistake. That mode leaves & alone, so the result is salt%20%26%20pepper — actually correct here, because the ampersand was escaped by the mode that escapes everything except structure. The inverse mistake is more dangerous: encoding a whole URL with the Query value mode escapes its delimiters, so ?q=1&lang=en becomes a single parameter whose name contains the rest of the URL.

The rule that avoids both: decide what the string is before encoding it. If it is a value that will sit inside a query string, use Query value. If it is a complete URL being placed somewhere that needs one, use Whole URL. The two are not interchangeable, and the symptom of getting it wrong is a parameter count that is quietly off by one.

Plus signs, spaces and the two different standards

A space can be encoded two ways, and which one is correct depends on position — a distinction that causes a great deal of confusion.

In a URL path, a space must be %20. There is no alternative; a literal + in a path is a plus sign.

In a query string, %20 is always correct, and + is also accepted by the form-encoding convention application/x-www-form-urlencoded, which is what HTML forms submit by default. That convention is why you sometimes see ?q=hello+world and sometimes ?q=hello%20world. Both decode to the same string under that convention.

The ambiguity bites in the other direction. If a query value genuinely contains a plus sign — a phone number, a base64 fragment, a mathematical expression — and it is decoded with the form convention, the plus is read as a space and the value is silently altered. This is exactly why Base64 has a URL-safe variant: the standard alphabet uses +, which would be destroyed by a form decoder.

This encoder emits %20 for spaces, which is correct in both positions and unambiguous. That is the safer default, even though + would be marginally shorter. When decoding, the URL Decoder leaves plus handling as an explicit option rather than guessing, because guessing is what causes the corruption.

Non-Latin text, and how it reaches the wire

Percent-encoding operates on bytes, not characters. This matters for any text outside ASCII, because those characters occupy more than one byte in UTF-8.

A single Chinese character is three bytes in UTF-8, so encoding it produces three percent-escapes. The pair of characters for the word meaning tools encodes as %E5%B7%A5%E5%85%B7 — nine percent-escapes for two characters. Emoji are four bytes each, so one emoji becomes four escapes.

This is correct and expected, but it makes URLs containing non-Latin text visibly long. The important part is that the byte sequence is UTF-8 and not some legacy encoding, because a decoder assuming a different encoding will produce mojibake rather than an error. Modern practice is unambiguous here: everything is UTF-8, and this tool treats input as UTF-8 without offering an alternative.

Browsers do a certain amount of this automatically. Type Chinese characters into an address bar and the browser encodes them before sending. But nothing does it for you when you are constructing a URL in code, in a template, or by hand in a spreadsheet — which is where this tool earns its place.