How to Build a Query String Without Breaking Your Link

October 17, 2026 • NOFYI Editorial Team

A query string is the part of a URL that comes after a question mark. It carries extra information, such as a search term, a page number, a filter, or a tracking label. A well-built query string is easy to read, easy to test, and easy for a server to understand. A badly built query string can break a link, lose a filter, or send the wrong data. This guide shows how to build a query string without breaking your link, with a worked example, encoding rules, and a clear warning about secrets in URLs.

The first step is to understand the anatomy of a URL. A URL has a base, a path, and an optional query string. For example, in https://example.com/search?query=hello&page=2, the base and path are https://example.com/search, and the query string is query=hello&page=2. The question mark separates the path from the query string. Everything after the question mark is a set of key-value pairs. If you change the base or the path, you change the page. If you change the query string, you usually change only the data sent with that page.

What a Query String Is

A query string is a list of pairs, each in the form key=value. The key is the name of the piece of data, and the value is the data itself. For example, in query=hello, the key is query and the value is hello. In page=2, the key is page and the value is 2. Keys and values are plain text, and they must follow URL rules. Spaces, ampersands, question marks, and other special characters cannot appear raw in a value, because they have a special meaning in a URL. They must be encoded, which is covered later in this guide.

Query strings are used in many places. A search form uses a query string to send the search term to the results page. A shop uses a query string to send a category, a color, a size, and a sort order. A blog uses a query string to send a page number. An email campaign uses a query string to send a source label, so the site can tell which email brought the visitor. In each case, the query string is a simple way to pass small pieces of data without changing the page itself.

How to Build a Query String Step by Step

First, start with the base URL and the path, with no question mark. Write it down exactly, including https:// and any trailing slash the site uses. For example, start with https://example.com/search. Do not add a query string to a URL that already has one without checking. If the URL already contains a question mark, you must add to the existing query string, not start a new one.

Second, add one question mark after the path. The question mark marks the start of the query string. Use exactly one question mark for the whole query string. A second question mark is treated as part of a value, not as a new separator, and it will confuse both readers and servers. If you are copying a URL from another source, check that it has only one question mark before the first key.

Third, add the first key-value pair. Write the key, then an equals sign, then the value. For example, add query=hello to make https://example.com/search?query=hello. The equals sign separates the key from the value. Use a clear, short key name, such as query, page, category, or sort. Avoid spaces in key names. Use lowercase letters and underscores if you need more than one word, such as search_term.

Fourth, add each additional pair with an ampersand. The ampersand separates one pair from the next. For example, add &page=2 to make https://example.com/search?query=hello&page=2. Do not use a comma, a semicolon, or a space as a separator. Do not add an ampersand before the first pair or after the last pair. A trailing ampersand creates an empty pair that some servers treat as an error.

Fifth, encode every value. Encoding replaces characters that have a special meaning with a percent code. A space becomes %20 or a plus sign in a query string. An ampersand becomes %26. A question mark becomes %3F. An equals sign becomes %3D. Use a URL encoder or a built-in encoding function in your programming language, rather than encoding by hand. After encoding, check the full URL by reading it from left to right.

Sixth, test the URL before you share it. Paste it into a browser and check that the page loads and that the filter, search term, or page number works as expected. Check the address bar after the page loads, because some sites rewrite the URL. If the page shows the wrong results, check the query string first: look for a missing ampersand, a missing equals sign, or a value that was not encoded.

Worked Example: A Search Link

Suppose you want a link that searches for red shoes, shows page 2, and sorts by price. Start with the base URL: https://example.com/search. Add a question mark. Add the first pair for the search term. The search term is red shoes, which contains a space, so it must be encoded as red%20shoes or red+shoes. The first pair is query=red%20shoes. The URL is now https://example.com/search?query=red%20shoes.

Next, add the page pair with an ampersand: &page=2. The URL is now https://example.com/search?query=red%20shoes&page=2. Next, add the sort pair with another ampersand: &sort=price. The full URL is https://example.com/search?query=red%20shoes&page=2&sort=price. Read it from left to right: the path is /search, the first key is query with the value red shoes, the second key is page with the value 2, and the third key is sort with the value price. Each pair is separated by one ampersand, and the space in red shoes is encoded.

Now compare this correct link with three broken versions. The link https://example.com/search?query=red shoes&page=2 has a raw space, which can break the link when it is pasted into an email or a document. The link https://example.com/search?query=red%20shoes?page=2 uses a second question mark instead of an ampersand, so the server may treat page=2 as part of the search term. The link https://example.com/search?query=red%20shoes&page2 is missing the equals sign, so the server does not know that 2 is the value for page. Each small mistake changes the meaning.

Encoding Values Correctly

Encoding is the step that most people skip, and it causes the most broken links. A value can contain letters, digits, and a few safe characters without encoding. It cannot safely contain spaces, ampersands, question marks, equals signs, hash signs, slashes, or non-English characters without encoding. When you encode a value, you replace each unsafe character with a percent sign followed by two hexadecimal digits. The server decodes the value back to the original text when it reads the query string.

Common encodings are worth remembering. A space becomes %20. An ampersand becomes %26. A question mark becomes %3F. An equals sign becomes %3D. A hash sign becomes %23. A plus sign becomes %2B. A slash becomes %2F. A percent sign itself becomes %25. If a value contains an ampersand, such as fish & chips, encode it as fish%20%26%20chips. If you leave the ampersand raw, the server will split the value at the ampersand and treat chips as a new key with no value.

Do not encode the whole URL at once. Encode only the values, and sometimes the keys, not the question mark, the equals signs, or the ampersands that separate the pairs. If you encode the separators, the server will not see the structure of the query string. Use a trusted encoder for values, and leave the structure characters alone. If you build query strings in code, use the language built-in function for query strings, which encodes values and joins pairs for you.

Common Mistakes That Break Links

One common mistake is adding a second question mark. A query string has exactly one question mark, at the start. A second question mark belongs inside a value, and it must be encoded. Another common mistake is using an ampersand inside a value without encoding it. That splits the value into two pairs and changes the meaning. A third mistake is forgetting the equals sign, which leaves a key with no value. A fourth mistake is leaving a trailing ampersand, which creates an empty pair.

Another mistake is using spaces or special characters in key names. Keys should be short, lowercase, and free of spaces. Use search_term instead of search term, and use sort_by instead of sort by. If a key has a space, it must be encoded, but a reader will find it hard to read, and a server may not match it. A related mistake is using the same key twice with different values, such as ?color=red&color=blue. Some servers read only the first value, some read only the last, and some read both as a list. If you need more than one value, use a clear format that the server documents, such as a comma-separated value or a repeated key that the server expects.

Long query strings are another risk. A URL with dozens of pairs is hard to read, hard to test, and may exceed limits in browsers, servers, or email clients. If a link needs many parameters, check whether the server has a shorter form, such as a saved filter or a short code. Keep query strings as short as you can, and put only the data the page needs in the URL.

Do Not Put Secrets in URLs

Never put secrets in a query string. A secret includes a password, an API key, a session token, a private link token, a reset code, or any value that gives access to an account. Query strings are not private. They appear in the browser address bar, in browser history, in server logs, in analytics tools, in referrer headers, and in shared screenshots. A person who copies a link to share it may also share the secret without realizing it.

If a link needs to prove that a user is allowed to see a page, use a secure method instead of a secret in the URL. For example, use a signed-in session, a server-side check, or a short-lived token sent in a header, not in the query string. If you must use a token in a link, such as a password reset link, make it single-use, short-lived, and tied to one account, and tell the user not to share the link. Do not put a token in a link that will be shared, bookmarked, or posted publicly.

Also do not put personal data in a query string unless you have a clear reason and the site uses HTTPS. Names, email addresses, phone numbers, and addresses can leak through logs and referrers. Use a form that sends data in the request body, or store the data on the server and pass only a safe identifier. If you see a URL with a password or a token in it, treat that secret as compromised: change it, revoke it, and build a safer link.

Limitations of Query Strings

Query strings are good for small, visible data, but they are not good for large or sensitive data. They have length limits that differ by browser and server, and they are visible to anyone who can see the URL. They are also easy to change: a user can edit a value in the address bar and reload the page. A server must never trust a query string value without checking it. For example, a server should not grant access to a private page just because the URL contains admin=true. It must check the user session on the server.

Query strings also do not preserve order or structure well. A list of pairs is flat, so it cannot easily represent nested data or complex filters. If you need complex data, use a form, a JSON request body, or a saved filter on the server. Query strings are also not a substitute for a clean URL. A URL with many parameters is hard to read and hard to remember. For a page that people will share, use a short, readable path and keep the query string to one or two pairs.

Another limitation is caching. Two URLs that differ only in a query string may be treated as different pages by a cache, even if the content is the same. A tracking parameter that changes on every visit can prevent caching and slow the site. If you add tracking parameters, check how the site handles caching, and use a consistent format so the cache can work.

Frequently Asked Questions

What starts a query string?

A question mark starts a query string. It comes after the path and before the first key-value pair. Use exactly one question mark. For example, in https://example.com/search?query=hello, the question mark separates /search from query=hello.

What separates key-value pairs in a query string?

An ampersand separates pairs. Use one ampersand between each pair, and do not add one before the first pair or after the last pair. For example, use ?query=hello&page=2, not ?query=hello,page=2 or ?query=hello&page=2&.

Do I need to encode values in a query string?

Yes. Encode every value that contains a space, an ampersand, a question mark, an equals sign, a hash sign, or a non-English character. Use a URL encoder or a built-in function. Encode values only, not the question mark, equals signs, or ampersands that separate pairs.

Can I put a password or API key in a URL?

No. Do not put secrets in URLs. Query strings appear in browser history, server logs, analytics, referrers, and shared screenshots. Use a signed-in session, a server-side check, or a secure header instead. If a secret has been in a URL, change or revoke it.

Conclusion

To build a query string without breaking your link, start with the base URL, add one question mark, add the first pair as key=value, join each extra pair with an ampersand, encode every value, and test the full URL. Remember the worked example: https://example.com/search?query=red%20shoes&page=2&sort=price. Keep query strings short, keep them free of secrets, and check them before you share them.