Query strings look simple, but a single unencoded ampersand, plus sign, or fragment marker can change what an application receives. This guide explains how to build API links, encode values safely, test repeated and Unicode parameters, and troubleshoot the difference between the URL you intended and the request your server actually parsed.
Overview
A query string is the portion of a URL after ? and before an optional # fragment. It commonly carries filters, search terms, pagination values, feature flags, campaign parameters, or API options.
https://example.com/products?category=books&page=2In this example, category=books and page=2 are query string parameters. The ampersand separates parameters, while the equals sign separates each name from its value. A parameter can also appear without an equals sign, such as ?debug; how that is interpreted depends on the browser, framework, or server parser.
Encoding is needed when a value contains characters that have a structural meaning in a URL. For example, an ampersand inside a search term must be encoded so it is not mistaken for the start of another parameter.
Intended value: red & blue
Encoded value: red%20%26%20blue
https://example.com/search?q=red%20%26%20blueUse a URL encode decode online tool for quick inspection, but treat the result as a debugging aid rather than a substitute for understanding the receiving application. For repeatable work, build URLs with the URL and URLSearchParams APIs or the equivalent library in your server-side language.
URL parameter reference
| Character or pattern | Typical meaning | What to check |
|---|---|---|
? | Starts the query string | Use only one query delimiter; later question marks may be data or may be mishandled. |
& | Separates parameters | Encode it as %26 when it belongs inside a value. |
= | Separates a name and value | Encode it inside a value when the receiving parser treats it structurally. |
# | Starts a browser fragment | Fragments are normally not sent in the HTTP request; encode # as %23 when it is data. |
+ | Literal plus in some contexts; space in form encoding | Confirm whether the parser treats plus as a space before decoding. |
| Space | Not normally written literally | Use percent encoding, commonly %20, or the serializer's documented form. |
% | Introduces a percent-encoded byte | Do not double-encode an already encoded value unless that is intentional. |
Checklist by scenario
Building a URL in JavaScript
Prefer structured APIs over manual string concatenation. They separate parameter names and values and handle percent encoding for you.
const url = new URL('https://api.example.com/items');
url.searchParams.set('q', 'red & blue');
url.searchParams.set('page', '2');
console.log(url.toString());
// https://api.example.com/items?q=red+%26+blue&page=2The exact representation of spaces can vary between serializers. A plus sign in the output can represent a space under form-style query serialization. The important test is whether the server decodes the value as intended.
When a parameter can occur more than once, use append rather than set:
const url = new URL('https://api.example.com/items');
url.searchParams.append('tag', 'books');
url.searchParams.append('tag', 'fiction');
// tag=books&tag=fictionDo not assume that every API understands arrays in the same way. Common conventions include repeated keys, comma-separated values, bracket notation such as tag[]=books, or JSON encoded as one value. Follow the API contract.
Building a link from a form or marketing brief
- List the required functional parameters separately from optional tracking parameters.
- Write down the intended decoded value for each parameter, including spaces, punctuation, and Unicode characters.
- Encode values individually; do not encode the entire URL after assembling it.
- Check that the destination path, query string, and fragment are in the correct order.
- Open the final link and verify both the visible result and the request captured in browser developer tools.
For campaign links, keep naming consistent. Decide whether names are lowercase, whether values use hyphens or underscores, and which parameters are required before a seasonal planning cycle begins. Do not place passwords, private keys, session tokens, or other sensitive data in a URL. URLs can appear in browser history, logs, copied links, referrer data, and analytics systems.
Testing an API request from the command line
Shell characters can be interpreted before the request reaches the HTTP client. Quote a complete URL when testing:
curl 'https://api.example.com/search?q=red%20%26%20blue&page=2'For form-style request data, let the client encode individual fields when supported:
curl --get 'https://api.example.com/search' \
--data-urlencode 'q=red & blue' \
--data-urlencode 'page=2'This approach reduces mistakes caused by spaces, ampersands, question marks, and shell expansion. For a broader request-debugging process, compare the request construction, payload, headers, and response using the REST API testing workflow.
Handling a search term, Unicode, or a literal plus sign
Test values that expose decoding differences:
red & blueone+twoone two100%caféor another non-ASCII valuea=b&c=d- an empty value, such as
q= - a missing value, such as
q
A literal plus sign should be encoded as %2B when the server uses form-style decoding. Otherwise, it may become a space. Similarly, a percent sign should normally become %25 when it is part of the value.
What to double-check
Encoding happens at the value level
A common mistake is to encode a complete URL as though it were one value. That can turn delimiters such as ? and & into data and prevent the server from finding the intended parameters. Construct the URL from a trusted base, parameter names, and individually encoded values.
Decoding is not identical everywhere
Browser APIs, JavaScript serializers, backend frameworks, reverse proxies, command-line clients, and analytics systems may apply slightly different rules. In particular, compare how each layer handles spaces, plus signs, duplicate keys, empty values, malformed percent escapes, and Unicode.
Use a small test matrix rather than relying on one successful example:
| Input value | Expected decoded value | Observed value | Pass? |
|---|---|---|---|
red & blue | red & blue | Record server output | Yes/No |
one+two | one+two | Record server output | Yes/No |
one two | one two | Record server output | Yes/No |
café | café | Record server output | Yes/No |
Fragments are client-side navigation
Everything after # is generally handled by the browser and is not included in the HTTP request sent to the server. Therefore, /page?item=7#details sends item=7, but not details, to the server. If a server-side value contains a hash, encode it as %23.
Parameter order and duplicates may matter
Some applications preserve parameter order; others normalize or ignore it. Duplicate keys can be represented as a list, the first value, the last value, or an error. Test the behavior that your API contract requires. If you control the API, document whether repeated values are supported and how clients should send arrays.
Inspect the actual request
When a link behaves incorrectly, open browser developer tools, select the Network panel, reload the page, and inspect the request URL. Compare it with the value shown in the address bar and the value your code generated. On the server, log parsed parameter names and values carefully while avoiding credentials and personal data. If the request body is also involved, use a structured formatter and validator; the API payload debugging workflow covers related checks.
Common mistakes
- Concatenating untrusted input:
'?q=' + searchTermcan break when the term contains delimiters. Encode the value or use a URL builder. - Encoding twice: Turning
%20into%2520usually means the percent sign was encoded a second time. Identify which layer owns encoding. - Decoding too early: Decoding a complete URL before parsing can turn data characters into delimiters. Parse the URL first and decode parameter values through the intended parser.
- Assuming plus always means space: This depends on the serialization and parsing rules. Test a literal plus as
%2B. - Putting a fragment before the query: In
/page#section?x=1,?x=1is part of the fragment, not a query parameter. Use/page?x=1#section. - Using the wrong array convention: Repeated keys and comma-separated values are not automatically interchangeable.
- Copying sensitive URLs into tickets or chats: Remove credentials, tokens, and private identifiers before sharing a request.
- Checking only the browser display: A link can look correct while a redirect, proxy, router, or backend parser changes the request. Inspect each relevant hop.
For redirects and canonical URLs, also check whether parameters are preserved, removed, reordered, or accidentally appended more than once. Technical SEO teams can include these checks in a broader technical SEO content QA checklist.
When to revisit
Revisit your URL parameter checklist whenever the workflow or its inputs change. Useful checkpoints include:
- before launching a seasonal campaign or changing tracking conventions;
- when an API version, backend framework, router, proxy, or client library changes;
- when adding a new parameter type, array format, redirect, or Unicode input;
- when a bug report says that a search term, filter, or identifier arrived altered;
- when moving requests from browser code to a command-line test, server job, or CI workflow;
- when reviewing links that may expose private data or create duplicate crawlable URLs.
Keep a compact regression set with spaces, plus signs, ampersands, percent signs, Unicode, empty values, repeated keys, and fragments. Run it after relevant code or infrastructure changes, record the expected decoded values, and inspect both the outgoing request and the server-side result. When a tool or framework changes, confirm its current serialization behavior instead of relying on an old example. That small habit makes URL encode decode online tools, browser inspections, API tests, and production debugging much more reliable.