CodeCraft
← Back to Blog
Encoding2026-04-11·9 min read

URL Encoding Explained: Percent-Encoding in Web Development

#url#encoding#percent-encoding#web-security
C
CodeCraft Team· Engineering

Every time you search Google, submit a form, or share a link, URL encoding is silently working behind the scenes. URLs can only contain a limited set of characters defined by RFC 3986 — everything else must be converted into a safe format using percent-encoding. Understanding URL encoding is essential for any web developer working with APIs, forms, query strings, or routing.

This guide explains what URL encoding is, why it exists, how percent-encoding works at the byte level, and common mistakes developers make when handling URLs in JavaScript, Python, and other languages.

What is URL Encoding?

A URL (Uniform Resource Locator) is a text string that identifies a resource on the internet. However, URLs are restricted to a subset of ASCII characters. Characters outside this set — including spaces, non-ASCII characters like Chinese or Arabic text, and special punctuation — must be encoded before being included in a URL.

URL encoding, also called percent-encoding, replaces unsafe characters with a % followed by two hexadecimal digits representing the character's UTF-8 byte value.

For example, a space character (ASCII 32 = 0x20) becomes %20. The Chinese character "你" (UTF-8 bytes: 0xE4 0xBD 0xA0) becomes %E4%BD%A0.

The standard is defined in RFC 3986 (URIs) and RFC 1866 (HTML forms, which use application/x-www-form-urlencoded encoding where spaces become + instead of %20).

Which Characters Need Encoding?

RFC 3986 defines two sets of characters:

Reserved characters — have special meaning in URLs and must be encoded when used as data (not as delimiters):

! * ' ( ) ; : @ & = + $ , / ? # [ ] %

Unreserved characters — always safe and never encoded:

Letters (A-Z, a-z), digits (0-9), and four symbols: - _ . ~

Everything else — including spaces, non-ASCII characters, and most punctuation — must be percent-encoded.

Practical examples:

- Space → %20 (or + in form data)

- & in a parameter value → %26

- = in a parameter value → %3D

- / in a parameter value → %2F

- ? in a parameter value → %3F

- @ in a username → %40

- # in a fragment → %23

JavaScript URL Encoding Functions

JavaScript provides four built-in functions for URL encoding and decoding. Choosing the wrong one is a common source of bugs.

`encodeURIComponent(str)` — Encodes everything except unreserved characters. Use this for encoding individual query parameter keys and values:

encodeURIComponent("hello world & 明")
// → "hello%20world%20%26%20%E6%98%8E"

`decodeURIComponent(str)` — Decodes a percent-encoded string. Throws a URIError if the encoding is malformed:

decodeURIComponent("hello%20world%20%26%20%E6%98%8E")
// → "hello world & 明"

`encodeURI(str)` — Encodes a full URL but preserves reserved characters (/, ?, #, &, =, etc.). Use this only for a complete URL, not individual parameters:

encodeURI("https://example.com/search?q=hello world")
// → "https://example.com/search?q=hello%20world"

`decodeURI(str)` — Decodes a URL but leaves reserved characters encoded.

The golden rule: Always use encodeURIComponent for query parameter values. Never use encodeURI for individual parameters, as it will leave & and = unencoded, breaking query string parsing.

Form Encoding vs. URL Encoding

When HTML forms submit data with method="GET" or Content-Type: application/x-www-form-urlencoded, a slightly different encoding applies:

- Spaces become + instead of %20

- All other characters follow the same percent-encoding rules

This distinction matters when manually constructing form submissions or when parsing query strings from form posts:

// Query string from HTML form: name=John+Doe&age=30
// Using URLSearchParams correctly handles both + and %20:
const params = new URLSearchParams("name=John+Doe&age=30");
params.get("name"); // → "John Doe" ✓

// Manually decoding with decodeURIComponent won't handle +:
decodeURIComponent("John+Doe"); // → "John+Doe" ✗ (wrong!)

The modern browser API URLSearchParams handles both forms of encoding automatically, making it the preferred approach.

Building URLs Safely in JavaScript

One of the most common security vulnerabilities in web applications comes from improperly concatenating URL components. Never build URLs by hand-concatenating strings:

// DANGEROUS — user input can inject extra parameters or path segments:
const url = "https://api.example.com/users?name=" + userInput;

// SAFE — use URLSearchParams to build query strings:
const params = new URLSearchParams({ name: userInput, page: "1" });
const url = "https://api.example.com/users?" + params.toString();

// Even safer — use the URL constructor:
const url = new URL("https://api.example.com/users");
url.searchParams.set("name", userInput);
url.searchParams.set("page", "1");
const finalUrl = url.toString();

The URL constructor and URLSearchParams are available in all modern browsers and Node.js 10+. They handle encoding automatically and make your URLs immune to injection attacks.

URL Encoding in Python, Go, and Other Languages

Every language has its own URL encoding utilities:

Python:

from urllib.parse import quote, unquote, urlencode, quote_plus

# Encode a single value (safe='/' means / is not encoded):
quote("hello world & 你好", safe='')  # → "hello%20world%20%26%20%E4%BD%A0%E5%A5%BD"

# Encode form data (uses + for spaces):
urlencode({"q": "hello world", "lang": "zh"})  # → "q=hello+world&lang=zh"

# Decode:
unquote("hello%20world")  # → "hello world"

Go:

import "net/url"

encoded := url.QueryEscape("hello world & 你好")
// → "hello+world+%26+%E4%BD%A0%E5%A5%BD"

decoded, _ := url.QueryUnescape(encoded)
// → "hello world & 你好"

Java:

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

String encoded = URLEncoder.encode("hello world", "UTF-8");  // → "hello+world"
String decoded = URLDecoder.decode("hello+world", "UTF-8");  // → "hello world"

Common URL Encoding Mistakes

Double-encoding: Encoding an already-encoded string results in % being encoded as %25:

encodeURIComponent(encodeURIComponent("hello world"))
// → "hello%2520world" (wrong — %20 became %2520)

Always check if a string is already encoded before encoding it again. You can use decodeURIComponent + try/catch to test.

Forgetting to encode path segments: If a user ID or resource name contains /, it will be interpreted as a path separator:

// Wrong: "user/name" → treated as two path segments
const url = `/api/users/${userId}/profile`;

// Correct: encode the path segment
const url = `/api/users/${encodeURIComponent(userId)}/profile`;

Using the wrong decoder for form data: As shown earlier, decodeURIComponent doesn't handle + as a space. Use URLSearchParams for form data.

Ignoring charset: Percent-encoding is only meaningful when combined with a known charset. Modern web development standardizes on UTF-8, but legacy systems may use Latin-1 or other encodings, causing garbled text when decoded with the wrong charset.

URL Encoding and SEO

Search engines can read percent-encoded URLs, but clean URLs are still preferred for user experience and SEO:

- https://shop.com/products/t-shirt-red-large is better than https://shop.com/products/t-shirt%20red%20large

- Use hyphens, not encoded spaces, in URL paths

- For non-ASCII languages (Chinese, Arabic, Korean), modern browsers display the decoded form in the address bar, but the actual HTTP request uses encoded bytes

- Canonical URLs should use consistently encoded (or decoded) forms to avoid duplicate content issues

International Domain Names (IDN): Domains with non-ASCII characters use Punycode encoding, not percent-encoding. For example, 中文.com becomes xn--fiq228c.com. This is handled transparently by browsers and DNS resolvers.

URL encoding is one of those foundational web technologies that works invisibly until something breaks. By understanding the difference between `encodeURIComponent` and `encodeURI`, when to use `URLSearchParams`, and how different languages handle encoding, you'll avoid an entire class of subtle bugs in your applications. Use our free URL Encoder / Decoder tool to encode or decode any URL string instantly — with support for both percent-encoding (`%20`) and form encoding (`+`), right in your browser with no data sent to any server.