URL Encoder and Decoder Guide: Handle Query Strings, Parameters, and Reserved Characters
URLsweb standardsAPI developmentJavaScriptHTTPdeveloper tools

URL Encoder and Decoder Guide: Handle Query Strings, Parameters, and Reserved Characters

WWebbclass Editorial Team
2026-11-07
7 min read

Learn how to encode URL parameters, path segments, spaces, Unicode, and reserved characters without breaking links or API requests.

Learn how to safely encode URL parameters, path segments, fragments, spaces, reserved characters, and Unicode so links and API requests remain predictable. This practical URL encoder and decoder checklist also shows how to identify malformed URLs, repeated parameters, and accidental double encoding.

Overview

A URL is made of several parts, and each part has different encoding needs. A typical address may include a scheme such as https, a host, a path, a query string, and a fragment:

https://example.com/products/books?category=fiction&sort=title#reviews

Percent encoding represents a byte with a percent sign followed by two hexadecimal digits. For example, a space can be represented as %20, while the ampersand in a query string is commonly written as %26 when it is data inside a parameter value.

The most important rule is to encode according to the URL component you are building. A query parameter value, a path segment, and a complete URL are not interchangeable inputs. Encoding an entire URL after adding its scheme, host, and separators can turn structural characters such as :, /, ?, and & into data, breaking the address.

Use a URL encoder when inserting user or application data into a URL. Use a URL decoder when inspecting an existing value, but decode only the component you intend to read. A browser-based URL encoder is useful for quick checks, while application code should use the URL and query-building utilities provided by its language or framework.

Quick percent-encoding reference

CharacterEncoded formTypical significance
Space%20Whitespace in a component
&%26Data inside a value; otherwise separates query parameters
=%3DData inside a value; otherwise separates a key from its value
?%3FData inside a component; otherwise begins a query
#%23Data inside a component; otherwise begins a fragment
+%2BA literal plus sign
%%25A literal percent sign
/%2FSlash used as data in a path segment

In form-style query encoding, a space may also appear as +. Do not assume that every decoder treats plus signs identically: some query parsers convert + to a space, while a literal plus should be represented as %2B when that distinction matters.

Checklist by scenario

Building a URL query string

  1. Start with the base URL, such as https://example.com/search.
  2. Keep parameter names and values as separate strings.
  3. Encode each name and value, rather than encoding the finished URL.
  4. Join parameters with & and place = between each name and value.
  5. Test values containing spaces, ampersands, equals signs, question marks, and non-ASCII characters.

If the search value is red & blue, the resulting parameter should preserve the ampersand as data: ?q=red%20%26%20blue. The separator between multiple parameters remains an unencoded &.

In JavaScript, URLSearchParams can build a query string without manual concatenation:

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

For repeated parameters, append each value instead of overwriting the previous one:

const params = new URLSearchParams();
params.append('tag', 'javascript');
params.append('tag', 'api');

This produces a query with two tag entries. Whether a server accepts repeated parameters and how it interprets them is an application-level decision, so confirm the API contract.

Encoding a path segment

A path is hierarchical. Slashes normally separate segments, so encode a slash when it belongs inside a single identifier. For example, the value reports/2025 may need to become reports%2F2025 if it is one parameter in a route rather than two path segments.

In JavaScript, encodeURIComponent(value) is generally suited to an individual component. It should not be used blindly on a complete URL because it will encode URL structure as well as data. When constructing paths, encode each dynamic segment separately and then join the segments with literal slashes.

Handling a fragment

A fragment begins after # and is usually used for a document location or client-side state. Encode dynamic fragment data as a fragment component. Remember that fragments are not normally sent to the server in an HTTP request, so they cannot be used as a substitute for a server-readable query parameter.

Working with Unicode and non-ASCII text

Encode text using the URL utility for your language or framework rather than manually converting characters. Unicode text is represented through UTF-8 bytes and then percent encoded where needed. Test names, search terms, and identifiers containing accented characters, non-Latin scripts, emoji, or combining marks if your application accepts them.

For API work, inspect both the final request URL and the server's parsed parameter value. A display that looks correct in a browser does not prove that every intermediary, router, or backend parser handles the value as intended.

Inspecting or decoding an existing URL

  1. Parse the URL into its components before decoding anything.
  2. Read the query parameters with a query parser where possible.
  3. Decode a parameter value once and compare it with the expected original text.
  4. Preserve the raw value when investigating a production or API error.

A URL decoder is useful for examining a copied parameter, but decoding a complete URL may make its structure harder to distinguish from its data. Keep a raw copy and a decoded working copy during debugging.

What to double-check

  • Component boundaries: Decide whether you are encoding a full URL, a query key, a query value, a path segment, or a fragment.
  • Separators: Keep structural ?, &, =, /, and # outside the encoded data when they define URL structure.
  • Spaces: Check whether your parser expects %20, plus signs, or both. Avoid converting a literal plus into a space unintentionally.
  • Existing percent sequences: Determine whether %2F is already encoded data before passing it through another encoder.
  • Repeated parameters: Confirm whether the receiving service expects repeated keys, comma-separated values, or a JSON-encoded value.
  • Case and normalization: Treat encoded bytes consistently and avoid changing decoded identifiers unless the application defines a normalization rule.
  • Redirects and logs: Compare the URL before the redirect, after the redirect, and at the server boundary. Different layers may display encoded and decoded forms differently.
  • Security-sensitive values: Avoid placing secrets, access tokens, or private data in URLs unless the design explicitly requires it. URLs can be copied, logged, cached, or displayed in browser history.

When diagnosing an API request, browser developer tools or an API debugging client can help you compare the constructed request with the server response. For broader request-testing workflows, see How to Debug REST APIs with Postman and Best API Debugging Tools for Developers.

Common mistakes

Encoding the complete URL

Passing https://example.com/search?q=hello world to a component encoder can encode the scheme and separators. Build the URL from components instead.

Encoding twice

If a value contains %20 and is encoded again, the percent sign may become %25, producing %2520. This is not automatically wrong: it may be correct when the literal text %20 is intended. The problem is accidental repeated encoding. Track whether each value is raw or already encoded, and encode at one clear boundary.

Decoding too early

Decoding a URL before parsing its structure can turn encoded delimiters into apparent separators. Parse first, then decode the selected component.

Confusing a plus sign with a space

The plus sign can represent a space in some form-encoded query contexts, but it can also be literal data. Encode a literal plus as %2B when the distinction is important.

Manually replacing characters

Replacing spaces with %20 is not a complete encoding strategy. Other reserved characters, Unicode bytes, and existing percent sequences still need correct handling. Prefer standard library functions or a carefully tested URL encoder.

If the value is a structured payload, encode it according to its own format first, then place it into the appropriate URL component. A JSON formatter can help validate a JSON payload before it is serialized into a request; see the JSON Formatter and Validator Guide.

When to revisit

Revisit this checklist whenever a URL workflow changes, including a new router, framework, HTTP client, API gateway, redirect rule, or backend parser. Also review it before releasing filters, search pages, pagination, tracking links, file paths, or webhook endpoints that accept user-provided values.

Make URL behavior part of automated tests. Include ordinary values as well as spaces, reserved characters, literal percent signs, repeated keys, empty values, Unicode text, and values that already contain encoded sequences. Verify the complete round trip: raw input, encoded URL, parsed server value, and any returned or redirected URL.

Before shipping, use this final action list:

  1. Identify the exact URL component being built.
  2. Keep raw data separate from encoded output.
  3. Use a standard component-aware URL utility.
  4. Test delimiters, spaces, plus signs, percent signs, Unicode, and repeated parameters.
  5. Inspect requests across redirects and server parsing.
  6. Confirm that sensitive data is not unnecessarily exposed in the URL.

For related browser-based coding and debugging workflows, review the Frontend Developer Toolchain Checklist. The same discipline applies to other developer utilities: preserve the original input, transform it once with a suitable tool, and validate the result at the boundary where another system will read it.

Related Topics

#URLs#web standards#API development#JavaScript#HTTP#developer tools
W

Webbclass Editorial Team

Technical Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.