Understanding URL Encoding

URL encoding looks straightforward until query strings contain spaces, slashes, ampersands, or non-ASCII text and a request starts failing in subtle ways. This guide explains percent-encoding from the perspective of real web applications so you can tell when to encode, what to encode, and what should be left alone.

1. What is URL Encoding?

Also known as Percent-encoding, URL encoding is a mechanism for encoding information in a Uniform Resource Identifier (URI). It replaces unsafe ASCII characters with a % followed by two hexadecimal digits.

2. Why is it necessary?

Certain characters have special meanings in a URL. For example, the ? separates the path from the query string, and the & separates different query parameters. If your data itself contains an &, the server won't know if it's data or a separator. URL encoding safely neutralizes these characters.

3. Implementation: Encode and Decode

Use encodeURIComponent for query parameters (encodes more chars). Use encodeURI for full URLs (preserves :/?#[]@).

JavaScript provides built-in native functions to handle this safely.

encodeURIComponent()

const text = "Hello & World?";
const encoded = encodeURIComponent(text); 
// "Hello%20%26%20World%3F"

decodeURIComponent()

const urlData = "Hello%20%26%20World%3F";
const decoded = decodeURIComponent(urlData); 
// "Hello & World?"

Building Query Strings Safely

// Always encode each param value
const params = { q: "hello & world", page: 1 };
const query = Object.entries(params)
  .map(([k, v]) => encodeURIComponent(k) + '=' + encodeURIComponent(v))
  .join('&');
// "q=hello%20%26%20world&page=1"

const url = `https://api.example.com/search?${query}`;

4. Conclusion

Failing to encode URLs properly is a common cause of broken links and application bugs. Always use robust encoding functions before assembling dynamic URLs.

Use the URL Encoder/Decoder to inspect and convert encoded URL values locally.

5. Characters that break requests most often

In real applications, failures are usually caused by a few recurring characters inside user input. If these values are inserted directly into URLs, query parsing can split or truncate data.

• Space: should be encoded as %20 in URLs.
• Ampersand (&): separates query parameters, so data values must encode it.
• Equals (=): separates key and value in query strings.
• Hash (#): starts a fragment and can cut off server-visible data.
• Non-ASCII text: Unicode characters must be UTF-8 percent-encoded.

6. Avoid double encoding

A common bug is encoding an already encoded value. For example, %20 becomes %2520 after another pass, which changes the final text users see.

const once = encodeURIComponent("hello world");   // hello%20world
const twice = encodeURIComponent(once);            // hello%2520world (wrong for most cases)

// Rule of thumb: encode at the boundary where raw text enters URL construction.

7. Practical checklist

1. Encode each query key and value separately.
2. Do not manually concatenate untrusted text into URL paths.
3. Normalize and decode once when reading server-side values.
4. Add tests with spaces, symbols, and non-English input.