URL space encoding: %20 vs plus

Why spaces have two common forms

A raw space does not belong in a URL. Percent encoding writes it as %20. Form encoding has an extra convention where plus means space inside a value. That small difference breaks search terms, callback URLs, phone numbers, and examples copied between browsers and APIs.

Example

q=dev tools

URL component: q=dev%20tools
Form value: q=dev+tools

How to choose the right encoding

1. Choose %20 for paths, general URL components, and values that should decode the same outside form handling.
2. Choose plus only when the receiving endpoint is reading application/x-www-form-urlencoded data.
3. Decode once and check whether plus signs became spaces or stayed as literal plus signs.
4. For callback or return URLs, encode the nested URL as one value so its own ? and & characters do not split the outer query.

Query values and form data

HTML form submissions often turn spaces into plus signs. That rule belongs to form-encoded data, not to every part of every URL.

When an API behaves oddly, check both the content type and the server framework. Some frameworks turn plus into space only in form bodies or query parsers; others leave it alone unless percent decoding is requested.

Literal plus signs

A real plus sign, such as the plus in C++ or +1 in a phone number, may need to be encoded as %2B. Otherwise a form decoder may quietly turn it into a space.

When decoded text looks wrong, compare the original and decoded value character by character. The bug is often one space, one plus sign, or one percent sequence.

Common mistakes

• Replacing every plus sign with a space even when the plus was literal
• Using plus signs in a URL path where %20 is expected
• Double-encoding a value that already contains %20
• Encoding an entire query string when only one parameter value needed encoding

Related problems