A URL that works perfectly in a browser can fail completely when pasted into a curl command, embedded in a JSON field, or sent as a query parameter — because each of these contexts has different rules about which characters are safe and which must be encoded
The previous articles on this site covered percent-encoding basics, edge cases that break real applications, URL structure ambiguities, and URL design as API design. This article addresses URL encoding in different contexts — why the same URL may need to be encoded differently depending on where it appears, and why "just URL-encode it" is underspecified advice without knowing the context.
The fundamental rule: different characters are safe in different URL components
A URL has distinct components, and the characters that must be encoded differ between them:
Scheme: https:// — no encoding needed here; the scheme is fixed syntax.
Host: example.com — only ASCII labels are valid; non-ASCII hostnames use Punycode encoding (covered in the previous URL structure article), not percent-encoding.
Path: /path/to/resource — forward slashes (/) are structural separators and must not be encoded if they're path separators. If a path segment contains a literal slash as part of its value, that slash must be encoded as %2F — but then some servers interpret %2F in paths as a security risk and block it.
Query string: ?key=value&other=thing — = and & are structural separators and must not be encoded (as delimiters); but if a value contains a literal & or =, it must be encoded. Spaces encode as %20 or + (the + for space convention is specific to application/x-www-form-urlencoded — not the general URL spec, a nuance that causes bugs).
Fragment: #section-name — everything after # is never sent to the server; encoding requirements here apply to the browser's own processing.
The encoding-within-encoding problem
The most common URL encoding bug: a URL used as a value inside another URL.
Scenario: you have a redirect system where the destination URL is passed as a query parameter:
https://mysite.com/redirect?to=https://destination.com/page?foo=bar
The inner URL's ? and & and = collide with the outer URL's query string syntax. A naive parser, encountering the first ? after the to=, stops parsing the to value and treats foo=bar as a separate parameter on the outer URL.
Correct encoding: the inner URL must be fully percent-encoded as the value of to=:
https://mysite.com/redirect?to=https%3A%2F%2Fdestination.com%2Fpage%3Ffoo%3Dbar
Now the inner URL's structural characters (://, /, ?, =) are encoded and won't interfere with the outer URL's parsing.
Double encoding trap: if this encoded URL is then embedded again as a value somewhere (in a JSON field, in a data attribute, in another URL parameter), you need to encode it for that context — but only the characters that are special in the new context, not re-encoding the % signs already there (which would turn %3A into %253A — triple-encoding the colon).
URL encoding in JSON and HTML contexts
In a JSON field, URLs generally don't need percent-encoding — JSON uses backslash escaping for its special characters (", \, control characters). A URL value in JSON just needs its double-quotes escaped if it somehow contained them (unusual for URLs). The & in a URL doesn't need encoding in JSON because & is not special in JSON.
In HTML attributes (href, src, action), & is special — it begins an HTML entity reference. A URL like https://example.com/?a=1&b=2 in an HTML href attribute should be written as https://example.com/?a=1&b=2 — the & encoded as the HTML entity &. This is HTML entity encoding, not percent-encoding — a different encoding layer for a different context.
Confusing these two encoding systems is a common source of bugs: percent-encoding the & as %26 in an HTML attribute (incorrect — the browser will interpret %26 as a literal %26 and the URL will break), vs HTML-entity-encoding it as & (correct — the browser will interpret & as & and pass it correctly to the URL).
The + vs %20 space ambiguity
Spaces in URLs are one of the most inconsistently handled cases:
- In the general URL percent-encoding scheme: space =
%20 - In
application/x-www-form-urlencoded(HTML form submissions): space =+
Both representations are in common use. Many servers handle both; some handle only one. + in a URL path is a literal + character (not a space); + in a query string is conventionally a space in form-encoded parameters.
The practical consequence: https://example.com/search?q=hello+world and https://example.com/search?q=hello%20world should produce the same search for most servers — but if a server decodes + as a literal + rather than a space, the first URL would search for hello+world (with a literal plus sign), not hello world.
When in doubt, use %20 — it's unambiguous across all contexts; + is only "safe" in application/x-www-form-urlencoded query strings.
Encoding for shell/command-line contexts
When using a URL in a shell command (curl, wget, scripting), shell metacharacters (&, |, >, <, $, backticks, spaces, quotes) must be handled — either by quoting the URL or by encoding the problematic characters.
Common approach: wrap the URL in single quotes in the shell command:
curl 'https://api.example.com/search?q=hello world&limit=10'
Single quotes prevent the shell from interpreting & (which would send the limit=10 part to the background as a separate command) and spaces (which would break the argument parsing). The URL still needs percent-encoding of the space for the HTTP request itself, but curl handles this in some modes.
Double quoting doesn't protect against $ expansion — use single quotes for URLs containing literal $ characters.
How to use the URL Encoder/Decoder on sadiqbd.com
- For encoding a URL that will be used as a value inside another URL (the redirect-destination scenario): encode the full inner URL, so its structural characters don't interfere with the outer URL's parsing
- For decoding a percent-encoded URL to see its original form: paste the encoded URL and decode — useful for reading API responses, debugging redirect chains, and understanding obfuscated URLs
- Know your context: if the URL is going into HTML, you also need HTML entity encoding for
&; if it's going into JSON, you generally don't need additional encoding; if it's going into a shell command, quoting is usually simpler than manual encoding
Frequently Asked Questions
Should I always encode all non-ASCII characters in URLs?
Yes, for portability. While modern browsers handle non-ASCII characters in URLs by percent-encoding them before sending the HTTP request (so https://example.com/café works in a browser's address bar), systems that process URLs programmatically may not. For URLs used in APIs, configuration files, databases, or anywhere that's not a direct browser address bar input, percent-encoding all non-ASCII characters (and all special characters not reserved for their structural purpose) ensures the URL is interpreted correctly everywhere.
Is the URL Encoder/Decoder free? Yes — completely free, no sign-up required.
Try the URL Encoder/Decoder free at sadiqbd.com — percent-encode or decode any URL instantly.
