URL Encode / Decode

A URL may contain only a limited set of characters: the unaccented letters A to Z and a to z, the digits, and a few punctuation marks. Some of those punctuation marks have special jobs. The slash separates path segments, the question mark starts the query string, the ampersand separates parameters, the equals sign joins a name to its value and the hash marks a fragment. Any other character, or a reserved character used as ordinary data, has to be escaped.

URL encoding, formally called percent-encoding and defined in RFC 3986, does this by writing each byte as a percent sign followed by two hexadecimal digits. A space becomes %20, an ampersand %26 and a slash %2F. Characters outside ASCII are first converted to UTF-8 bytes, and each byte is encoded separately, so é (two bytes, C3 A9) becomes %C3%A9 and a single emoji can become four escapes.

Decoding reverses the process, turning each %XX back into its byte and then reading the bytes as UTF-8 text. Browsers do this automatically when they display addresses, which is why you can see readable accented words in the address bar even though the underlying request is percent-encoded.

It matters what you encode. If you are inserting a search term, file name or other value into a URL, encode only that value, so that any &, = or / it contains cannot be mistaken for structure. This is what JavaScript's encodeURIComponent does, and it is the default here. Encoding the term cats & dogs gives cats%20%26%20dogs, which can be placed safely after q= in a query string.

If you already have a complete URL that merely contains spaces or non-ASCII characters, encode it as a whole URL instead. That mode, like encodeURI, leaves the reserved characters that give the URL its structure untouched and escapes everything else. Running a full URL through component encoding would turn https:// into https%3A%2F%2F and break it.

Never encode text twice. If a value is already encoded, encoding it again turns every % into %25, so %20 becomes %2520 and the server receives the wrong text. When in doubt, decode first and look at the result.

HTML forms submitted with the default application/x-www-form-urlencoded type use a slightly different convention in which a space becomes a plus sign rather than %20. That is why decoding treats + as a space by default; switch it off if your text contains literal plus signs that were not escaped, such as some phone numbers or Base64 strings.

Frequently asked questions