URL Encoder & Decoder

What is URL Encoding?

URL encoding, also known as percent-encoding, is a mechanism for converting special characters in a URL into a format that can be safely transmitted over the HTTP protocol. Each unsafe character is replaced by a % sign followed by two hexadecimal digits representing the byte value of that character in UTF-8.

According to RFC 3986, only unreserved characters are allowed to appear unencoded in a URL: letters A-Z a-z, digits 0-9, and four special characters - _ . ~. All other characters — including spaces, ampersands, equals signs, and Unicode characters like Chinese, Arabic, or Vietnamese — must be percent-encoded when used in URL components.

For example, hello world & friends becomes hello%20world%20%26%20friends. Each byte of the UTF-8 representation is written as %XX where XX is the uppercase hexadecimal value.

How Percent-Encoding Works

The percent-encoding process follows these steps:

1. Identify characters to encode: Check whether each character is in the unreserved set. If not, it must be encoded.
2. Convert to UTF-8 bytes: ASCII characters use 1 byte, accented Latin characters use 2 bytes, CJK characters use 3 bytes, and emoji use 4 bytes.
3. Represent each byte: Each byte is written as % followed by two uppercase hex digits. For example, byte 0xC3 becomes %C3.

The space character is a special case: in application/x-www-form-urlencoded content (used by HTML forms), spaces are encoded as +. In all other URL components (path, fragment), spaces must be %20. This is why encodeURIComponent produces %20 while URLSearchParams produces + for spaces.

encodeURI vs encodeURIComponent

JavaScript provides two built-in URL encoding functions, each serving a different purpose:

Rule of thumb: Use encodeURIComponent() for query parameter values, use encodeURI() for entire URLs. The most common mistake is using encodeURI() for parameter values — this fails to encode & and =, causing the query string to be parsed incorrectly. For example, encoding a=1&b=2 as a single parameter value requires encodeURIComponent to produce a%3D1%26b%3D2.

Common Mistakes and Gotchas

• Double encoding: Encoding an already-encoded string produces %2520 instead of %20. Always check whether your data has already been encoded before processing it. A quick test: if the string contains %25, it may have been double-encoded.
• Confusing + and %20: In query strings (application/x-www-form-urlencoded), + represents a space. But in URL paths, + is a literal plus sign. When moving data between path and query components, you must convert between the two representations correctly.
• Forgetting to encode #: The # character begins a URL fragment. If a parameter value contains # without encoding, everything after it is interpreted as an anchor and silently stripped from the request.
• Using the wrong function for path vs query: encodeURIComponent encodes /, which breaks path segments. Use encodeURI for complete URLs or encode each path segment individually.
• Not handling Unicode: Some legacy servers and proxies do not support UTF-8 in URLs. When working with international characters, always verify that the entire request pipeline supports UTF-8. Modern browsers and servers handle this well, but middleware or CDN configurations may still cause issues.
• Encoding the entire URL with encodeURIComponent: This encodes :// and /, turning a valid URL like https://example.com/path into https%3A%2F%2Fexample.com%2Fpath, which is unusable as a URL.

Using URL Encoding in Your Code

In modern web development, URL encoding appears everywhere: building query strings for AJAX requests, constructing redirect URLs, handling form data, generating canonical URLs for SEO, and encoding OAuth callback parameters. The URLSearchParams API in JavaScript handles encoding and decoding automatically, reducing the risk of manual encoding errors.

In Python, the urllib.parse module provides quote(), unquote(), and urlencode(). In PHP, urlencode() uses + for spaces (suitable for query strings), while rawurlencode() uses %20 (suitable for paths). Understanding this difference helps avoid subtle bugs when working with REST APIs or webhook integrations.

For Go developers, the net/url package provides url.QueryEscape() and url.PathEscape(), which mirror the query/path distinction. In Java, use URLEncoder.encode() for query parameters and URI constructors for building full URLs safely.

Check the Code Snippets card above for copy-paste ready examples in JavaScript, Python, PHP, and cURL for both encoding and decoding operations.