URL Encoding Explained: Understanding Percent Encoding [Developer Guide]

The Problem: URLs can only contain certain characters. Spaces, special symbols, and non-ASCII characters break URLs.

Example invalid URL:

https://example.com/search?q=hello world&user=john@doe

Problems:

• Space breaks the URL
• @ has special meaning
• & separates query parameters

The Solution: Encode special characters as %XX where XX is the hexadecimal ASCII code.

Fixed URL:

https://example.com/search?q=hello%20world&user=john%40doe

Characters with Special Meaning in URLs:

The Process:

1. Take the character's ASCII or UTF-8 code
2. Convert to hexadecimal
3. Prefix with %

Example: Space character

• ASCII code: 32 (decimal)
• Hexadecimal: 20
• Encoded: %20

Example: @ symbol

• ASCII code: 64
• Hexadecimal: 40
• Encoded: %40

UTF-8 Characters (multiple bytes):

€ symbol → UTF-8: 0xE2 0x82 0xAC → Encoded: %E2%82%AC

Two Ways to Encode Spaces:

• %20 — Proper percent encoding
• + — Application/x-www-form-urlencoded (query strings)

When to Use Each:

• Path: Always use %20 (/my%20file.pdf)
• Query string: Either works, but %20 is safer (?name=John%20Doe)

Example:

// Both are valid in query strings
?search=hello+world
?search=hello%20world

// Only %20 works in paths
/files/my%20document.pdf  ✅
/files/my+document.pdf    ❌

❌ Mistake #1: Double Encoding

// Wrong: encoding twice
encodeURIComponent(encodeURIComponent("hello world"))
// Result: hello%2520world (broken!)

❌ Mistake #2: Not Encoding Query Params

// Wrong
const url = `?email=${email}`;  // Breaks if email has @ or &

// Correct
const url = `?email=${encodeURIComponent(email)}`;

❌ Mistake #3: Encoding the Entire URL

// Wrong: breaks the URL structure
encodeURIComponent("https://example.com/path")
// Result: https%3A%2F%2Fexample.com%2Fpath (broken!)

// Correct: only encode the dynamic parts
`https://example.com/path?q=${encodeURIComponent(query)}`

JavaScript:

// Encode a query parameter
const encoded = encodeURIComponent("hello world");
// "hello%20world"

// Decode
const decoded = decodeURIComponent("hello%20world");
// "hello world"

// Full URL encoding
const params = new URLSearchParams({
  search: "hello world",
  email: "user@example.com"
});
console.log(params.toString());
// "search=hello+world&email=user%40example.com"

Python:

from urllib.parse import quote, unquote

# Encode
encoded = quote("hello world")
# 'hello%20world'

# Decode
decoded = unquote("hello%20world")
# 'hello world'

PHP:

# Encode
$encoded = urlencode("hello world");
// "hello+world"

$encoded = rawurlencode("hello world");
// "hello%20world" (RFC 3986 compliant)

// Decode
$decoded = urldecode("hello%20world");