Reference
URL Encoding Reference
URL encoding rules for query strings, callback URLs and API parameters.
Overview
URL encoding is a common source of API bugs because reserved characters change the meaning of a URL. When query values contain spaces, ampersands, equals signs, slashes or non-English characters, encoding must match the context: full URL, path segment, query key or query value.
Debugging Reference Table
| Character or API | Meaning | API debugging note |
|---|---|---|
| space | Whitespace in a value | Usually encoded as %20; plus signs may represent spaces in form encoding. |
| & | Query parameter separator | Must be encoded inside a value or it creates another parameter. |
| = | Key/value separator | Must be encoded when it belongs inside a value. |
| ? | Query string begins | Encode when it is part of a callback URL value. |
| / | Path separator | Encode when a slash belongs inside a path segment value. |
| % | Escape prefix | Double-encoding creates values like %2520. |
| encodeURI | Encodes a complete URI less aggressively | Does not encode separators such as ?, &, =. |
| encodeURIComponent | Encodes a single component | Preferred for individual query values and path segment values. |
| URLSearchParams | Structured query builder | Safer than manual string concatenation for query strings. |
Reference Table Coverage
- Reserved characters in query strings.
- encodeURI versus encodeURIComponent.
- Double-encoding and percent signs.
- Callback URLs and nested URLs.
API Debugging Examples
- A redirect_uri parameter breaks because the nested URL was not encoded.
- A search term containing & creates an unexpected extra query parameter.
- A value copied from logs is already encoded and gets encoded again.
Common Mistakes
- Using encodeURI for a query value.
- Treating + and %20 as identical in every context.
- Double-encoding percent characters.
- Building query strings with manual concatenation.
FAQ
When should I use encodeURIComponent?
Use it for individual query keys, query values and path segment values.
Why did my query value split into two parameters?
An unencoded ampersand inside the value was interpreted as a parameter separator.
How do I detect double encoding?
Look for sequences such as %2520, which often means an already encoded %20 was encoded again.