URL encoding rarely happens in isolation — it's usually one step in a bigger task: building a curl command, turning a query string into a JSON test fixture, or passing a token through a URL. This guide walks through those combinations with worked, illustrative examples.
Encoding a value before it goes into a curl command
Quick answerA raw space or & inside a curl URL gets interpreted by the shell, not by curl, before the request is even built. Encoding parameter values with encodeURIComponent first — and quoting the whole URL — avoids both the shell splitting the command and the server misreading the query string.
Say you're testing an endpoint that searches by name, and the name has a space in it (example only): name=Jane Doe. Pasted directly into a terminal, curl https://api.example.com/search?name=Jane Doe is read by the shell as two separate words — curl gets ...?name=Jane as the URL and Doe as a stray second argument, which curl usually rejects or misinterprets. The fix is to encode the value first: name=Jane%20Doe, giving a single well-formed URL: curl "https://api.example.com/search?name=Jane%20Doe". The quotes around the URL are still worth keeping as a habit, since a stray & in an un-encoded value would otherwise tell the shell to run the command in the background and silently truncate the request.
This pattern comes up constantly when you're copying a value out of a spreadsheet, a bug report, or a UI field and pasting it straight into a terminal test — the raw text usually needs an encode pass first, exactly the same way it would if that value were going into a browser address bar.
Turning a query string into a JSON test fixture
Quick answerDecode the query string first so each value is plain, readable text, then place those plain values into your JSON payload. JSON has its own escaping rules — it doesn't expect %20 or %C3%A9, so leaving percent-encoding in place just means a second, unnecessary decode step later.
Imagine you've captured a request URL from a browser network tab while reproducing a bug (example only): ?city=S%C3%A3o%20Paulo&plan=pro&seats=12. If you copy those raw values straight into a JSON test fixture, you end up with a fixture like {"city":"S%C3%A3o%20Paulo","plan":"pro"} — which is technically valid JSON, but the next script that reads it has to remember to decode city before using it, while plan and seats need no such step. That inconsistency is exactly the kind of thing that causes an intermittent test failure three months later when someone forgets the extra decode call.
Parsing the query string first — so city comes out as the plain text São Paulo — and then writing that plain value into the JSON fixture keeps every field in the same, predictable state: plain text everywhere, with encoding handled only at the URL boundary where it's actually needed.
| Source | Raw (as seen in URL) | What to store in JSON |
|---|
| city | S%C3%A3o%20Paulo | São Paulo |
| plan | pro | pro |
| seats | 12 | 12 |
When a Base64 string needs URL encoding on top
Quick answerStandard Base64 output can contain +, /, and =. Placed directly inside a URL query value, + can be read as a space and = can be read as the key/value separator — so the Base64 string needs its own encodeURIComponent pass before it's safe to append to a URL.
These two encodings solve completely different problems, but they're often used back-to-back: Base64 turns arbitrary bytes (a small file, a token, a serialized object) into text; URL encoding then makes that text safe to place inside an address. Skipping the second step is an easy mistake, because a short Base64 string without a +, /, or = in it will happen to work by accident, right up until a longer or different input produces one of those characters and the link quietly breaks.
Worked example (illustrative): the text hello> becomes Base64 aGVsbG8+. Placed as-is in ?data=aGVsbG8+, the trailing + risks being read as a space by some URL consumers. Running it through encodeURIComponent first gives aGVsbG8%2B, which is unambiguous no matter where it's decoded.
The safest habit is: Base64-encode the data, then URL-encode the Base64 string, in that order — and reverse it on the way back (URL-decode first, then Base64-decode). Treating them as two separate, ordered steps avoids the guesswork of which characters are "probably fine" to leave un-encoded.
Frequently asked questions
Do I need to encode a URL before pasting it into a curl command?
Yes, if any query parameter value contains spaces, ampersands, or other shell-sensitive or URL-structural characters. A raw space in an unquoted curl URL breaks the command into two arguments, and an un-encoded '&' inside a value is read by the shell as "run this in the background" before curl even sees it. Encoding the value first (with encodeURIComponent) and quoting the whole URL in curl avoids both problems at once.
Should I decode a query string before pasting its values into a JSON payload?
Generally yes. Query string values are percent-encoded for transport inside a URL, but JSON has its own escaping rules and doesn't expect %20 or %C3%A9 sequences. Decode the query string first to get the plain text values, then place those plain values into the JSON body; the JSON serializer will handle any characters that need escaping there (like quotes or backslashes) on its own.
Why does a Base64 string sometimes need URL encoding on top of itself?
Standard Base64 output can contain '+', '/', and '=' characters. If that Base64 string is placed directly into a URL query parameter, '+' can be misread as a space and '=' can be misread as the key/value separator. Running the Base64 output through encodeURIComponent (or using a URL-safe Base64 variant) prevents those characters from corrupting the surrounding URL structure.
How do I turn a query string into a JSON object for a test script?
Parse the query string first so each key and value is decoded and separated correctly, then convert each key/value pair into a JSON field. Doing the parsing and decoding before the JSON conversion avoids accidentally keeping percent-encoded text (like %20) inside a JSON string, which would need a second decode step later in the test script.
What's a quick way to sanity-check an API link before sharing it with a teammate?
Parse the full URL into its parts and decode the query parameters so you can read the actual values in plain text, then check for anything that shouldn't be shared, such as an embedded username/password or a session-like token sitting in a parameter. This two-step read (parse, then decode) catches problems that are easy to miss when scanning a long, percent-encoded string as-is.
Related guides
Methodology note: examples in this guide use illustrative sample values, endpoints, and commands for clarity — they are not real API responses or production data. This article is for general informational purposes and is not a substitute for your own testing or security review; always verify encoding behavior against your specific stack before shipping.