How to encode special characters in URLs correctly

Treat the full URL and a value separately

A URL contains parts with different roles, including the scheme, host, path, query, and fragment. Encoding a complete URL as one value also transforms the : and / in https:// and the ? that starts the query. The result can no longer be used directly as the destination URL.

To pass the search term red + blue & 50% as the value of q, encode only the search term:

input value: red + blue & 50%
encoded value: red%20%2B%20blue%20%26%2050%25
complete URL: https://example.com/search?q=red%20%2B%20blue%20%26%2050%25

When an environment can modify an existing URL by component, URL and query-parameter APIs make the encoding boundary clearer than string concatenation. As a rule, enter only the value that will be embedded in the URL into App Museum's URL encoder and decoder.

Why special characters cause problems

A space normally becomes %20 in percent-encoding. In application/x-www-form-urlencoded, however, a space is represented by +, so a literal plus sign needs %2B to remain distinct.

& can separate query fields, = can separate a name from its value, and # can begin a fragment. Encoding them as %26, %3D, and %23 keeps them inside the value. % begins an encoded sequence made of a percent sign and two hexadecimal digits, so a literal percent sign becomes %25.

raw value: plan=a&note=#1
encoded: plan%3Da%26note%3D%231

Common failures include always decoding form-style + as a literal plus, or concatenating an unencoded & and accidentally creating another parameter. Confirm whether the receiving system expects ordinary URL-component encoding or form encoding.

Detect double encoding

Encoding an existing %20 again converts its % to %25, producing %2520. After the receiver decodes once, %20 remains instead of becoming the expected space. This is a typical sign of double encoding.

original: a b
once: a%20b
twice: a%2520b
decode once from twice: a%20b

Define at each processing boundary whether the input is raw or already encoded, and do not encode the same value in multiple layers. Repeated percent signs followed by two hexadecimal digits do not prove double encoding by themselves; compare the result with the original value through a round trip. An incomplete percent sequence or invalid UTF-8 sequence can also produce a decoding error.

Verify an encode-decode round trip

1. Prepare test data with the same kinds of special characters instead of using real data.
2. Encode the value with the URL encoder and decoder.
3. Use the output as a new input and decode it.
4. Confirm that the decoded result matches the original string character for character.
5. In the completed URL, confirm that the value stays in one query field and does not create an unintended fragment or extra field.

For 東京 + café, verify that encoding transforms the non-ASCII characters, spaces, and +, and that decoding restores the original text including the accented character. Visually similar Unicode characters exist, so inspect code points or string length when exact identity matters.

Test without secrets

Signed URLs, password-reset URLs, OAuth authorization URLs, and URLs containing API keys or session tokens can leak through clipboard history, screen sharing, or logs. App Museum processes the value in the browser, but tests should still use https://example.com/ and fictional values. Do not paste real secrets or authentication URLs.

References

• WHATWG URL Standard: Percent-encoded bytes
• WHATWG URL Standard: application/x-www-form-urlencoded
• ECMAScript Language Specification: encodeURIComponent