url-encoder.ts × README.md package.json Ln 1, Col 1

URL Encoder / Decoder

Encode or decode URLs and query string parameters.

@ local-runtime @ typescript @ 0 deps
$ ./url-encoder ▶ running
// docs / url-encoder.md

The Broken Link You Cannot Reproduce — Until You Understand Percent-Encoding

Someone reports that a link in your email campaign is broken. You click it yourself and it works. They forward you the exact URL they clicked and you paste it into your browser — it works for you too. Then you look more carefully and notice that their URL has %20 where yours has a space, or & where yours has &. URL encoding is the invisible layer that makes the internet work — and the invisible layer that causes baffling bugs when it goes wrong.

What Percent-Encoding Actually Does

URLs are defined by RFC 3986 to contain only a specific set of characters: letters, digits, hyphens, underscores, tildes, and a handful of reserved characters with special structural meaning (/, ?, #, &, =, etc.). Every other character must be encoded as a percent sign followed by the character's two-digit hexadecimal ASCII code.

Examples of common encodings:

  • Space → %20
  • & (ampersand) → %26 when used as data, not as a query separator
  • = → %3D when used as data inside a query value
  • # → %23 (unencoded, it means "fragment"; encoded, it is a literal hash character)
  • + → %2B (the plus sign has special meaning in query strings)
  • Chinese character 中 → %E4%B8%AD (UTF-8 bytes, percent-encoded)

The %20 vs + Confusion

Spaces have two valid encodings in different URL contexts, and confusing them is a common source of bugs:

  • %20 is the correct encoding for a space in URL paths (/search/new%20york) and in query values that will be handled by a URL parser.
  • + represents a space only in application/x-www-form-urlencoded data — the format used by HTML form submissions. When an HTML form is submitted via GET, spaces in field values become + in the query string.

If your server receives + in a query parameter and interprets it as a literal plus sign instead of a space, form submissions containing spaces will produce wrong results. If you decode a URL-path segment and treat + as a space, you will misinterpret legitimate plus signs in file names or identifiers.

What Not to Encode

Encode the values within URL components — do not encode the structural characters that define the URL itself. Encoding the entire URL including the https:// scheme, domain, and path separators will produce a broken string that no browser or HTTP client will parse correctly. Encode only the values you are inserting into query parameters or path segments.

Using This Tool

  1. Paste your URL or text string into the input field.
  2. Click "Encode" to percent-encode special characters.
  3. Click "Decode" to convert percent-encoded sequences back to readable characters.
  4. Copy the output and use it in your application or API call.

// faq

What is the difference between %20 and + for encoding spaces? +

%20 is the RFC 3986 standard percent-encoding for a space, valid everywhere in a URL. The + sign encodes a space only in application/x-www-form-urlencoded data (HTML form submissions). In URL paths, a + is a literal plus character, not a space. Using + outside of form-encoded query strings will produce a bug — the receiving server will see a literal + rather than a space.

Should I encode my entire URL? +

No. Only encode the data values you are inserting into URL components. The protocol (https://), domain (example.com), path separators (/), query separator (?), and parameter separator (&) must remain unencoded — they are the structural skeleton of the URL. Encoding them will produce a completely broken string.

How are non-ASCII characters like Chinese or Arabic encoded? +

Non-ASCII characters are first encoded as UTF-8 bytes, then each byte is percent-encoded. The Chinese character 中 has the UTF-8 byte sequence E4 B8 AD, which becomes %E4%B8%AD in a URL. Modern browsers handle this automatically and display the readable character in the address bar, but the underlying HTTP request always uses the percent-encoded form.

Why does my URL work in a browser but break in my API call? +

Browsers are lenient URL parsers — they silently fix many encoding errors before making a request. HTTP client libraries used in code (curl, requests, fetch) are stricter and will either reject malformed URLs or send them literally to the server. If your URL works in a browser but not in code, the URL likely contains characters that the browser corrects automatically but your HTTP library does not.

main ⚡ 6 tools Ln 1, Col 1 UTF-8 LF TypeScript