Build URL query strings from key-value pairs with proper encoding for spaces, ampersands and special characters. Ready for APIs and URLs.
Use this free online Query String Builder directly in your browser. No signup required, no data leaves your device. Part of Utilier — a collection of 133+ developer utilities.
What is URL Query String Builder?
A URL query string is the part of a URL after the ? that contains key=value pairs separated by &. This tool builds query strings from a structured list of keys and values, properly encoding special characters so the resulting URL is valid and safe to use in HTTP requests, browser navigation, and APIs.
A query string carries optional URL parameters as encoded key=value pairs after a question mark. Repeated keys, empty values, arrays, and reserved characters all require deliberate representation so a server parses the request as intended. Building parameters as structured fields and encoding each key and value separately avoids malformed URLs and accidental parameter injection.
Proper URL encoding: Spaces become %20, & becomes %26, special characters are percent-encoded. The tool handles encoding automatically so you never create broken URLs.
Key-value pair interface: Enter keys and values in separate fields, one pair per row. Much easier than typing ?key=value&key=value and manually encoding each value.
Base URL support: Optionally specify a base URL (https://api.example.com/search) and the query string is appended with ? to produce the complete URL.
Empty value handling: Empty values are included as key= (no value), or omitted entirely — configurable based on your needs.
Array parameter support: Add multiple rows with the same key to create array-style parameters: ?color=red&color=blue or ?tags[]=a&tags[]=b.
Why use query builder?
Building query strings by hand is error-prone. Forgetting to encode spaces, using the wrong separator, or double-encoding values breaks URLs and causes API errors.
Avoid encoding mistakes: Spaces must be %20 (or +), & must be %26 inside values, = must be %3D. Manual encoding is tedious and error-prone. The tool handles it automatically.
Faster than typing: Building ?utm_source=email&utm_medium=newsletter&utm_campaign=launch by hand takes time and is easy to mistype. Enter key-value pairs in a table and generate instantly.
Test API requests quickly: When debugging API endpoints, adjust query parameters visually and regenerate the URL. Faster than editing a long URL string.
Generate tracking links: UTM parameters for analytics (utm_source, utm_medium, utm_campaign) are verbose. Build them in the tool and copy the final URL.
Avoid double-encoding: If you manually encode a value and then paste it into another encoder, you get double-encoding (%2520 instead of %20). This tool encodes once, correctly.
Runs locally: No upload. API keys, tokens, and parameters stay in the browser.
When to use query builder
Use whenever you need to build or modify URLs with query parameters.
Constructing API request URLs with filters, pagination, or search parameters.
Building tracking links with UTM parameters for email campaigns or ads.
Creating deep links for mobile apps or single-page applications (SPAs).
Generating OAuth callback URLs with state and redirect_uri parameters.
Testing API endpoints by adjusting query parameters and regenerating the URL.
Building URLs for redirects, iframes, or embeds with dynamic parameters.
Documenting API examples with proper query string formatting in tutorials or docs.
How to use query builder
Enter key-value pairs, optionally set a base URL, and generate the query string.
Enter the base URL (optional): If you want a complete URL, enter the base (e.g., https://api.example.com/search). If you only need the query string, leave it blank.
Add key-value pairs: Enter one parameter per row: key in the left column, value in the right. For example, 'q' = 'hello world', 'page' = '2'. Use the + button to add more rows.
Generate the query string: The query string appears in the output pane, starting with ? if a base URL is provided. Special characters are automatically encoded (%20, %26, etc.).
Handle special cases: For array parameters, add multiple rows with the same key (color=red, color=blue). For boolean flags, use empty values (debug=). For nested objects, use bracket notation (user[name]=John).
Copy or download: Use the Copy button to copy the full URL or query string. If the base URL is set, you get the complete URL; otherwise, just the query string (?key=value&...).
Test the URL: Paste the URL into a browser, curl, Postman, or your API client to verify it works as expected.
Key features
Automatic URL encoding: Spaces, &, =, %, and other special characters are percent-encoded correctly. No manual encoding needed.
Key-value table interface: Add, edit, and remove parameters visually in a structured table. Easier than editing a URL string.
Base URL concatenation: Enter a base URL and the query string is appended with ?. Produces a complete, ready-to-use URL.
Array parameter support: Add multiple rows with the same key to create array-style parameters (?color=red&color=blue).
Empty value handling: Decide whether empty values appear as key= or are omitted entirely.
Copy and download: Copy the query string to clipboard or download as a .txt file.
Reset button: Clear all fields and start fresh with one click.
Common use cases
API request construction: Build URLs for REST APIs with filters, pagination, sorting, and search parameters.
UTM tracking links: Generate marketing URLs with utm_source, utm_medium, utm_campaign for analytics tracking.
Deep linking: Create deep links for mobile apps or SPAs with route, state, and config parameters.
OAuth callbacks: Build redirect URIs with state, code, and redirect_uri parameters for OAuth flows.
Embed URLs: Generate URLs for iframe embeds, widgets, or third-party integrations with config parameters.
Testing and debugging: Quickly adjust API parameters and regenerate the URL for testing in browser or curl.
Examples
Query strings generated by this tool.
Search API with pagination
Base URL: https://api.example.com/search
q = hello world
page = 2
limit = 20
> is encoded as %3E, & as %26, = as %3D. Without encoding, the & would split the filter value into two separate parameters.
Query string only (no base URL)
name = John Doe
age = 30
?name=John%20Doe&age=30
If no base URL is provided, the output is just the query string starting with ?. Append it to any URL manually.
Technical reference
The URL query string format and encoding rules:
Format
?key1=value1&key2=value2&key3=value3 — starts with ?, pairs separated by &
Encoding standard
Percent-encoding per RFC 3986. Unsafe characters are %XX where XX is the hex byte value
Space encoding
Space can be %20 (percent-encoded) or + (form encoding). This tool uses %20 (standard URL encoding)
Reserved characters
: / ? # [ ] @ ! $ & ' ( ) * + , ; = must be percent-encoded when used in values
Unreserved characters
A-Z a-z 0-9 - _ . ~ do not need encoding
Array notation
Two conventions: ?key=val1&key=val2 (repeated keys) or ?key[]=val1&key[]=val2 (bracket notation). Both are valid
Empty values
?key= (empty value) or ?key (no value). Interpretation depends on the server
Order
Parameter order may matter for caching or signatures (OAuth, AWS), but HTTP spec says order is insignificant
Max length
URLs are limited to ~2000 characters in most browsers. Very long query strings may be truncated or rejected
Comparison to POST body
Query strings are visible in URLs (logs, history, bookmarks). For sensitive data or large payloads, use POST with a request body
Common mistakes to avoid
Manually encoding values before entering them in the tool
Why it happens: If you manually encode 'hello world' as 'hello%20world' and then paste it into the tool, it gets double-encoded: hello%2520world (%25 is the encoded %). The receiving server decodes it once and gets 'hello%20world' (with the literal %20), not 'hello world'. This breaks parsing and causes errors.
How to avoid it: Always enter raw, unencoded values in the tool. Let the tool handle encoding. If you already have a percent-encoded value, decode it first or paste it directly into the final URL instead of using the builder.
Using & or = inside values without encoding
Why it happens: & separates parameters, = separates keys and values. If a value contains & or =, it must be encoded, or the query string structure breaks. For example, ?filter=price>100&discount=yes looks like three parameters (filter=price>100, discount, yes) instead of one (filter='price>100&discount=yes').
How to avoid it: The tool encodes & and = automatically. If you build URLs manually, always encode values with encodeURIComponent() in JavaScript, urllib.parse.quote() in Python, or equivalent in your language.
Putting sensitive data (passwords, tokens) in query strings
Why it happens: Query strings appear in URLs, which are logged by servers, proxies, browser history, and bookmarks. If you pass a password or API token in the URL (?password=secret123), it is visible in logs, browser history, and referrer headers sent to third-party sites. This is a security vulnerability.
How to avoid it: Use POST requests with a request body for sensitive data (passwords, tokens, personal info). Or use Authorization headers for API keys. Only use query strings for non-sensitive parameters (filters, pagination, public IDs).
Assuming parameter order is preserved
Why it happens: The HTTP spec says query parameter order is insignificant, so servers may parse them in any order. If your code expects ?a=1&b=2 to always have 'a' before 'b', it may break when the server or a proxy reorders them. Some APIs (OAuth, AWS signatures) do require parameter order for signature calculation, but that is an exception.
How to avoid it: Do not rely on parameter order unless the API spec explicitly requires it. If order matters (e.g., for signatures), sort parameters alphabetically before signing. For most APIs, order does not matter.
Building very long query strings (>2000 characters)
Why it happens: Browsers and servers have URL length limits (typically ~2000 characters, though some allow more). If a query string is too long, the URL is truncated, rejected, or causes a 414 URI Too Long error. This happens when passing large arrays, long filter expressions, or base64-encoded data in URLs.
How to avoid it: Keep query strings under 2000 characters total. For large payloads (hundreds of array items, complex filters, JSON data), use POST with a request body instead. Or split the request into multiple smaller requests with pagination.
Frequently asked questions
Should I use %20 or + for encoding spaces?
Both are valid. %20 is standard percent-encoding (RFC 3986). + is form-encoding (application/x-www-form-urlencoded), historically used in HTML forms. Modern APIs prefer %20. This tool uses %20 because it is the standard for URLs. Servers decode both correctly in query strings.
How do I pass an array in a query string?
Two common conventions: (1) Repeat the key: ?color=red&color=blue — the server parses this as an array. (2) Use bracket notation: ?color[]=red&color[]=blue. Both work, but support depends on the server framework. Express.js and Rails support both. Check your API documentation.
What is the difference between query parameters and POST body?
Query parameters are in the URL after ?, visible in logs, history, and bookmarks. POST body is in the HTTP request body, not visible in URLs. Use query strings for filters, pagination, and public parameters. Use POST body for sensitive data (passwords, tokens) or large payloads (JSON, files).
Can I use query strings for sensitive data like passwords?
No. Query strings appear in URLs, which are logged by servers, proxies, browser history, and sent as referrer headers to third parties. Always use POST with a request body or Authorization headers for passwords, API keys, and personal data.
Why is my URL broken when it contains # or &?
# starts the URL fragment (anchor), so ?key=value#anchor is parsed as query string 'key=value' and fragment 'anchor'. If # is inside a value, it must be encoded as %23. & separates parameters, so it must be %26 inside values. The tool encodes both automatically.
How long can a query string be?
Most browsers and servers support ~2000 characters (including the entire URL). Some allow up to 8192 or more, but 2000 is the safe limit. If your query string exceeds this, use POST with a request body instead.
Can I use this tool for building URLs for curl or Postman?
Yes. Enter the base URL and parameters, copy the output, and paste it into curl: curl 'https://api.example.com/search?q=test&page=2' or Postman's URL field. The query string is properly encoded and ready to use.