URL Encoder and Decoder Guide: Fix Percent-Encoding, Query Strings, and Redirect Parameters

Overview

A URL is made from several parts: a scheme such as https, a host, an optional path, a query string, and a fragment. These parts use punctuation as structure. For example:

https://example.test/search?q=red%20shoes&page=2

Here, ? starts the query string, & separates parameters, and = separates each parameter name from its value. The search value contains a space represented as %20.

Percent-encoding replaces a byte with a percent sign followed by two hexadecimal digits. The unreserved characters—letters, digits, hyphen (-), period (.), underscore (_), and tilde (~)—normally do not need encoding. Characters such as spaces, ampersands, question marks, hash signs, and slashes can be meaningful URL delimiters, so they may need encoding when they are data rather than structure.

The most important rule is to encode a component, not an already assembled URL. If a user searches for red&blue, the ampersand belongs inside the value and should become %26. Encoding the complete URL after adding its separators can turn ?, &, and : into data, producing a link that no longer has the intended structure.

A browser-based URL encoder can be useful for inspecting a value quickly, but do not paste credentials, access tokens, session identifiers, or other private data into an online developer tool unless its handling is appropriate for your environment. For repeatable application behavior, use the standard URL utilities provided by your language or framework and test their output.

Checklist by scenario

When adding a query parameter

1. Start with the base URL and keep its scheme, host, and path separate from user input.
2. Encode the parameter name and value as individual components.
3. Join parameters with the query-string separator rather than placing raw user input into the URL.
4. Inspect the final URL to confirm that its separators remain visible and its data values are encoded.

In JavaScript, URLSearchParams is a practical choice:

const params = new URLSearchParams({ q: 'red&blue', page: '2' });
const url = `https://example.test/search?${params}`;

This produces a query string in which the ampersand inside the search value is escaped. For a single component, encodeURIComponent(value) is also appropriate:

const next = encodeURIComponent('/account/settings?tab=security');

Do not confuse this with encoding the entire destination URL. If the value is intended to be a nested URL, encode that nested URL as the value of a parameter.

When creating a redirect parameter

Redirects often contain a destination inside another URL, such as /login?next=%2Fcheckout. Treat the destination as one value. Encode it before placing it in the outer query string, then decode it exactly once when reading it.

Before redirecting, validate the decoded destination against the destinations your application permits. A redirect parameter should not automatically send a user to any arbitrary external host. Prefer relative paths or an explicit allowlist when the workflow permits it. Encoding prevents delimiter confusion; it does not decide whether a destination is trustworthy.

When calling an API

Check the API contract before choosing an encoder. Query parameters, path segments, form bodies, and JSON bodies use different representations. A value containing a slash may be valid data in a query parameter but may need encoding in a path segment. Conversely, encoding a complete path can hide its intended separators.

Keep the raw value and the serialized request available while debugging. Compare the request shown by your HTTP client with the server's parsed parameter value. This distinguishes an encoding problem from a server-side parsing, validation, or routing problem.

When decoding a captured URL

1. Copy the exact URL or parameter value, including percent signs and hexadecimal digits.
2. Identify whether you are decoding a whole URL, a path segment, a query value, or a nested URL.
3. Decode only the relevant component.
4. Check whether the result contains delimiters that should be treated as data rather than parsed again.

A URL decoder is useful for making an encoded value readable, but decoding is not a repair step by itself. Preserve the original value for comparison, especially when investigating signatures, webhooks, or authentication redirects.

What to double-check

Spaces and plus signs

A space may appear as %20. In form-style query serialization, it may also appear as +. Those representations are not interchangeable in every context: a literal plus sign can be data and may appear as %2B. Check whether the producer and consumer use standard URL component encoding or form encoding before changing a space or plus sign manually.

Reserved characters

The correct choice depends on context. A slash should remain a path separator in a normal path, but a slash inside a path-segment identifier may need encoding. Always identify the component before deciding.

Unicode and character encoding

Non-ASCII text is typically converted to UTF-8 bytes and then percent-encoded. Test values such as accented characters, non-Latin scripts, emoji, and combining characters if your application accepts international input. Also confirm that the server, database, logs, and application framework interpret the decoded text consistently.

Double encoding

Double encoding happens when an already encoded value is encoded again. For example, %2F can become %252F, because the percent sign itself has been encoded. It can be intentional when one encoded value is nested inside another, but accidental double encoding commonly causes failed lookups, broken redirects, and mismatched signatures. Compare each processing boundary and document where encoding occurs.

Common mistakes

• Encoding the full URL: This can encode the separators that browsers and servers need to parse the address. Encode query values, path segments, or nested URLs instead.
• Concatenating raw input: A value containing &, #, or ? can change the meaning of the URL. Use a URL builder or component encoder.
• Decoding too early: Decoding before parsing can turn an encoded ampersand into a parameter separator. Parse the outer structure first, then decode the selected value.
• Replacing every plus with a space: That rule belongs to particular form-encoding conventions, not every URL component.
• Using one function for every context: A query value, path segment, fragment, and full URL have different requirements. Choose an API that names the intended operation.
• Trusting a decoded redirect: Readability does not make a destination safe. Validate the destination before redirecting.
• Comparing normalized and raw URLs as strings: Equivalent URLs can have different textual forms. When debugging, compare parsed components as well as the serialized output.

If a link is broken, use this short sequence: preserve the original input, inspect the final URL, split it into components, identify the first unexpected delimiter, decode only the affected value, and reproduce the same case in a small test. Then check whether encoding happened once at the boundary where data became a URL component.

For related debugging work, a JSON formatter and validator can help inspect API payloads, while a regex tester is useful when checking input-validation patterns. Authentication flows may also benefit from the JWT decoder and debugging guide, but decoding a token does not verify its signature.

When to revisit

Return to this checklist whenever you change a router, framework, HTTP client, reverse proxy, authentication flow, or API contract. These changes can alter how spaces, plus signs, Unicode, slashes, and repeated parameters are serialized or parsed. Revisit it before a seasonal planning cycle if campaign links, tracking parameters, or redirect destinations are being refreshed, and before releasing a migration that changes URL shapes.

Keep a small regression set with ordinary text, spaces, literal plus signs, ampersands, slashes, hash signs, percent signs, Unicode, an empty value, and an already encoded value. For each case, record the intended component value, serialized URL, parsed server value, and redirect result. Run it when workflows or tools change.

Before shipping, use this final action list:

1. Classify every input as a full URL, path segment, query name, query value, fragment, or nested URL.
2. Use the matching standard encoder at the component boundary.
3. Verify spaces, plus signs, reserved characters, and Unicode.
4. Confirm that each layer encodes and decodes exactly as intended.
5. Validate redirect destinations independently of encoding.
6. Test the final request in the same client, browser, or framework used in production.