URL Encoding Explained: Percent-Encoding, Reserved Characters & Common Pitfalls

URL parsers accept and serialize different components according to component-specific rules. Percent-encoding represents bytes; Unicode text is commonly encoded as UTF-8 first. Distinguish data within a component from delimiters that structure the URL.

What Is URL Encoding?

Percent-encoding represents each encoded byte as % followed by two hexadecimal digits. A Unicode character can require multiple UTF-8 bytes and therefore multiple percent-encoded sequences. Whether a character needs encoding depends on its position and purpose.

Character   Encoded     Why
---------   --------    ----------------------------------
(space)     %20         Spaces are not valid in URLs
&           %26         & separates query parameters
=           %3D         = separates keys from values
#           %23         # starts a fragment identifier
?           %3F         ? starts the query string
/           %2F         / separates path segments
@           %40         @ is used in userinfo
+           %2B         + has special meaning in forms
%           %25         % is the escape character itself
Key Rule: The % character itself must be encoded as %25. If you see double-encoding issues (like %2520 instead of %20), something is encoding an already-encoded URL.

Anatomy of a URL

Different parts of a URL have different encoding rules:

https://user:[email protected]:8080/path/to/page?key=value&q=hello+world#section
\___/   \_______/ \_________/ \__/ \__________/ \_______________________/ \_____/
scheme  userinfo    host     port     path            query              fragment
  • Path — Encode dynamic segments separately so embedded separators do not become structural slashes. Allowed characters and application routing rules vary.
  • Query — Use URLSearchParams for application/x-www-form-urlencoded key/value serialization, or the encoding rules required by the receiving application.
  • Fragment — Encode according to the fragment and application syntax; query delimiters do not have the same general role here.
  • Host — International domain names use Punycode, not percent-encoding

JavaScript Encoding Functions

JavaScript provides multiple encoding functions — and choosing the wrong one is a common mistake.

encodeURIComponent() — For Values

Use this to encode a single value that will be placed into a URL. It encodes everything except A-Z a-z 0-9 - _ . ~ ! * ' ( ).

// Encoding a search query for a URL parameter
const query = 'price > 100 & category = "electronics"';
const encoded = encodeURIComponent(query);
// "price%20%3E%20100%20%26%20category%20%3D%20%22electronics%22"

const url = `https://api.example.com/search?q=${encoded}`;
// Works correctly — & and = inside the value don't break the URL

encodeURI() — For Full URLs

encodeURI preserves many structural delimiters, but encodes square brackets and percent signs. It is not a component-aware validator and can double-encode existing escapes. Prefer URL construction plus per-component serialization for dynamic data.

// Encoding a full URL with a space in the path
const url = 'https://example.com/my page/résumé.pdf';
const encoded = encodeURI(url);
// "https://example.com/my%20page/r%C3%A9sum%C3%A9.pdf"
// Notice: :// and / are preserved

The Critical Difference

const value = 'a=1&b=2';

encodeURI(value);          // "a=1&b=2"  ? WRONG for a query value!
encodeURIComponent(value); // "a%3D1%26b%3D2"  ✅ Correct

// Rule: Use encodeURIComponent for VALUES
//       Use encodeURI for COMPLETE URLs
Never Use escape(): The escape() function is deprecated and doesn't handle Unicode correctly. It encodes differently from the URL standard. Always use encodeURIComponent() or encodeURI().

URL Encoding in Other Languages

Python

from urllib.parse import quote, quote_plus, urlencode

# Encode a path segment
quote('my page/résumé.pdf')           # 'my%20page/r%C3%A9sum%C3%A9.pdf'
quote('my page/résumé.pdf', safe='')  # 'my%20page%2Fr%C3%A9sum%C3%A9.pdf'

# Encode a query parameter value (spaces become +)
quote_plus('hello world & goodbye')   # 'hello+world+%26+goodbye'

# Encode an entire query string from a dict
urlencode({'q': 'price > 100', 'page': '2'})  # 'q=price+%3E+100&page=2'

PHP

// Encode a URL component
urlencode('hello world');     // "hello+world" (spaces as +)
rawurlencode('hello world');  // "hello%20world" (spaces as %20)

// For query parameters, use http_build_query
$params = ['q' => 'price > 100', 'page' => 2];
http_build_query($params);   // "q=price+%3E+100&page=2"

Java

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

String encoded = URLEncoder.encode("hello world & more", StandardCharsets.UTF_8);
// "hello+world+%26+more"

Spaces: %20 vs + (Plus Sign)

This is the most confusing aspect of URL encoding. Both %20 and + can represent a space, but they're used in different contexts:

Context                    Space Encoding    Standard
-------------------------  ----------------  ---------------------------
URL path segments          %20               RFC 3986
Query string (URL)         %20               RFC 3986
HTML form (GET/POST)       +                 application/x-www-form-urlencoded

In practice: %20 is always safe. + only means "space" in form-encoded data (application/x-www-form-urlencoded). In a URL path, a literal + is a plus sign, not a space.

Safe Default: When in doubt, use %20 for spaces. It works everywhere. The + convention is a legacy from early HTML forms.

Common Pitfalls

1. Double Encoding

// ❌ Double encoding — %20 becomes %2520
const path = '/search?q=hello%20world';
const broken = encodeURI(path);  // '/search?q=hello%2520world'

// ✅ Encode the value, then build the URL
const query = 'hello world';
const url = '/search?q=' + encodeURIComponent(query);

2. Not Encoding User Input in URLs

// ❌ User input breaks the URL structure
const username = 'user&admin=true';
const url = `/api/users?name=${username}`;
// /api/users?name=user&admin=true ← injects a parameter!

// ✅ Encode the value
const url = `/api/users?name=${encodeURIComponent(username)}`;
// /api/users?name=user%26admin%3Dtrue ? safe

3. Encoding the Entire URL Instead of Just Values

// ❌ Breaks the URL structure
const url = encodeURIComponent('https://example.com/path?q=test');
// "https%3A%2F%2Fexample.com%2Fpath%3Fq%3Dtest" ? unusable as a URL

// ✅ Only encode the dynamic parts
const q = encodeURIComponent('test value');
const url = `https://example.com/path?q=${q}`;

4. Forgetting to Decode

// Server receives: ?q=hello%20world
const raw = req.query.q;  // Most frameworks auto-decode

// But if you're parsing manually:
const params = new URLSearchParams(window.location.search);
const q = params.get('q');  // "hello world" — auto-decoded

// Or explicitly:
decodeURIComponent('hello%20world');  // "hello world"

URL Encoding and Security

URL encoding is not a security mechanism — but incorrect encoding creates security vulnerabilities:

  • Open Redirect — Unvalidated redirect URLs can be crafted with encoded characters to bypass naive checks.
  • Path Traversal — Encoded ../ (%2e%2e%2f) can bypass path filters that only check the raw string.
  • Parameter Injection — Unencoded & and = in values can inject additional query parameters.
  • XSS via URL — Malicious JavaScript in URL fragments or query parameters must be properly encoded/escaped when reflected in HTML.

Quick Reference

Task                          Function / Method
----------------------------  ----------------------------------
Encode a query value (JS)     encodeURIComponent(value)
Encode a full URL (JS)        encodeURI(url)
Decode a value (JS)           decodeURIComponent(value)
Build query string (JS)       new URLSearchParams({key: value})
Encode value (Python)         urllib.parse.quote(value, safe='')
Encode form value (Python)    urllib.parse.quote_plus(value)
Build query (Python)          urllib.parse.urlencode(dict)
Encode value (PHP)            rawurlencode($value)
Encode form value (PHP)       urlencode($value)

Need to encode or decode a URL quickly?

Open URL Encoder/Decoder →