URL Encoding Guide: What, Why, and How

Introduction

URL encoding (also called percent encoding) is essential for web development. Every time you submit a form, send API parameters, or include special characters in a URL, encoding ensures your data arrives correctly. Without proper encoding, URLs break, forms fail, and API calls return errors. This guide explains everything you need to know about URL encoding.

URL encoding converts special characters into a format that can be safely transmitted over the internet. URLs can only contain certain characters from the ASCII character set. Any character outside this set must be encoded as %XX where XX is the hexadecimal ASCII value.

URLs have a specific structure defined by RFC 3986. Certain characters serve as delimiters that separate different parts of a URL:

• ? separates the path from query parameters
• & separates multiple parameters
• = separates parameter names from values
• / separates path segments
• # marks the fragment identifier

If you use these characters as data rather than delimiters, they must be encoded. Otherwise, browsers and servers misinterpret the URL structure, causing broken links and failed requests.

Every language provides built-in functions for URL encoding and decoding. Here are the most common ones:

// Encode a full URL component (recommended for query values)
encodeURIComponent("hello world!")  // "hello%20world%21"

// Decode a URL component
decodeURIComponent("hello%20world%21")  // "hello world!"

// Encode a full URL (preserves / ? & etc.)
encodeURI("https://example.com/path?q=hello world")
// "https://example.com/path?q=hello%20world"

from urllib.parse import quote, unquote, urlencode

# Encode a single value
quote("hello world!")       # "hello%20world%21"

# Decode a value
unquote("hello%20world%21") # "hello world!"

# Encode query parameters
urlencode({"q": "hello world", "page": 2})
# "q=hello+world&page=2"

import java.net.URLEncoder;
import java.net.URLDecoder;

// Encode (specify UTF-8)
String encoded = URLEncoder.encode("hello world!", "UTF-8");
// "hello+world%21"

// Decode
String decoded = URLDecoder.decode("hello+world%21", "UTF-8");
// "hello world!"

Not all URL parts are encoded the same way. Different sections of a URL have different reserved characters, so you must choose the right encoding function:

The key rule: use encodeURIComponent() for individual parameter values, and encodeURI() only when you need to encode a complete URL while preserving its structure.

Real-world Example: Building a Search URL

Imagine you are building a search feature that takes user input and constructs a URL for an API call. Here is how to do it correctly:

// User searches for: "price > $100 & in stock"
const query = "price > $100 & in stock";
const category = "electronics";

// WRONG: String concatenation (breaks on special chars)
const badUrl = `/api/search?q=${query}&cat=${category}`;
// /api/search?q=price > $100 & in stock&cat=electronics
// Server sees: q="price > $100", cat=" in stock", unknown="electronics"

// CORRECT: Encode each parameter value
const goodUrl = `/api/search?q=${encodeURIComponent(query)}&cat=${encodeURIComponent(category)}`;
// /api/search?q=price%20%3E%20%24100%20%26%20in%20stock&cat=electronics

Most programming languages provide built-in functions: JavaScript has encodeURIComponent()and decodeURIComponent(), Python has urllib.parse.quote()and unquote().

Quick Tips

• Always encode query parameter values, even if they look safe
• Spaces can be encoded as %20 or + - %20 is more universal
• Double-encoding causes bugs: %20 becomes %2520
• URLs have a max length (2083 chars in some browsers) - encoding increases length
• Reserved characters: ! * ' ( ) ; : @ & = + $ , / ? % # [ ]

Related Tools