Analyseur de Paramètres Query

What Is a Query String?

A query string is the portion of a URL that follows the question mark (?) and carries key-value data to the server or client application. In the URL https://example.com/search?q=typescript&page=2&sort=date, the query string is q=typescript&page=2&sort=date. Each parameter consists of a key, an equals sign, and a value. Multiple parameters are separated by ampersands (&). Query strings are the primary mechanism for passing state through URLs — powering search filters, pagination, tracking parameters, API requests, and form submissions via GET method.

This tool parses raw query strings into structured key-value pairs, handles duplicate keys, decodes percent-encoded characters, and supports array parameter notations. Unlike a full URL parser that decomposes protocol, host, port, path, and fragment, this tool focuses exclusively on the parameter layer — extracting, decoding, and organizing the data carried within the query string itself.

Query String Anatomy and Syntax Rules

A query string begins immediately after the ? delimiter in a URL. The structure follows a simple grammar: key=value pairs joined by & separators. Keys and values are percent-encoded according to RFC 3986 — spaces become %20 (or + in form submissions), and reserved characters like &, =, and # are encoded as %26, %3D, and %23 respectively.

Important parsing rules:

• Empty values are valid: ?key= produces the key with an empty string value, while ?key (no equals sign) produces the key with a null or undefined value depending on the parser.
• Order matters contextually: While HTTP does not assign meaning to parameter order, some APIs use positional significance for signature computation (e.g., OAuth 1.0 signature base string).
• Duplicate keys are permitted: ?color=red&color=blue is syntactically valid. Different frameworks handle this differently — PHP creates arrays, Express.js returns the last value by default, and URLSearchParams preserves all values.
• The fragment comes after: The hash fragment (#section) is never part of the query string and is not sent to the server. Parsers must stop at #.
• Maximum length: While RFC 3986 imposes no limit, browsers typically support URLs up to 2048 characters, and web servers like Apache default to 8190 bytes for the entire request line.

Parameter Encoding and the Plus Sign Convention

Query string encoding follows two overlapping standards that frequently cause confusion. RFC 3986 (URI Generic Syntax) specifies percent-encoding where spaces become %20. However, the HTML form specification (application/x-www-form-urlencoded) encodes spaces as + signs. Both are widely used:

• RFC 3986 encoding: Used by encodeURIComponent() in JavaScript. Spaces become %20. This is the standard for programmatically constructed URLs and REST APIs.
• Form encoding: Used by HTML <form method="GET"> submissions. Spaces become +. The URLSearchParams API follows this convention for serialization.

When decoding, a robust parser must handle both conventions — replacing + with spaces and decoding %XX sequences. The decodeURIComponent() function does not convert + to space, which is why using it alone on form-encoded data produces incorrect results. The URLSearchParams API handles both correctly.

Special characters that must always be encoded in query values include: & (parameter separator), = (key-value delimiter), # (fragment delimiter), + (space in form encoding), and non-ASCII characters (encoded as UTF-8 byte sequences). Keys follow the same encoding rules, though in practice most APIs use alphanumeric keys that require no encoding.

Array Parameters and Nested Objects

There is no single standard for representing arrays and nested objects in query strings. Different frameworks have adopted different conventions, and this parser recognizes the most common patterns:

• Repeated keys: ?tag=js&tag=ts&tag=rust — the simplest form. URLSearchParams stores all values via getAll('tag').
• Bracket notation: ?tags[]=js&tags[]=ts — used by PHP, Ruby on Rails, and jQuery. The brackets signal array intent to the server parser.
• Indexed brackets: ?tags[0]=js&tags[1]=ts — explicit ordering. Used when order matters or when interleaving with other indexed parameters.
• Comma-separated: ?tags=js,ts,rust — compact but ambiguous (what if a value contains a comma?). Common in REST APIs like Google's.
• Nested objects: ?filter[status]=active&filter[role]=admin — PHP and qs (Node.js) parse this into { filter: { status: 'active', role: 'admin' } }.

When building APIs, prefer repeated keys or bracket notation for arrays — they are unambiguous and widely supported. For nested objects, consider whether query strings are the right transport; complex structures are often better served by POST request bodies with JSON encoding.

The URLSearchParams API

Modern JavaScript provides the URLSearchParams interface for parsing, manipulating, and serializing query strings without manual string splitting. It handles encoding, decoding, duplicate keys, and iteration correctly:

• new URLSearchParams('?q=hello+world&page=1') — parses a query string (leading ? is optional).
• params.get('q') — returns the first value for a key, or null if absent.
• params.getAll('tag') — returns all values for duplicate keys as an array.
• params.has('page') — checks existence without retrieving the value.
• params.set('page', '2') — replaces all values for a key with a single new value.
• params.append('tag', 'new') — adds a value without removing existing ones.
• params.delete('tracking') — removes all values for a key.
• params.sort() — sorts parameters alphabetically by key (useful for cache normalization).
• params.toString() — serializes back to a query string (without leading ?).

URLSearchParams is available in all modern browsers, Node.js 10+, Deno, and Bun. It correctly handles the plus-sign-as-space convention during parsing and uses it during serialization. However, it does not support bracket notation for arrays or nested objects — for those patterns, libraries like qs (Node.js) or manual parsing are required.

Code Examples

Parsing and manipulating query strings with URLSearchParams

// Parse a query string
const params = new URLSearchParams('q=hello+world&page=2&tag=js&tag=ts');

// Read values
params.get('q');         // "hello world" (+ decoded to space)
params.get('page');      // "2"
params.getAll('tag');    // ["js", "ts"]
params.has('sort');      // false

// Modify parameters
params.set('page', '3');
params.append('tag', 'rust');
params.delete('q');

// Serialize back
params.toString();
// → "page=3&tag=js&tag=ts&tag=rust"

// Iterate all entries
for (const [key, value] of params) {
  console.log(`${key} = ${value}`);
}

// Build from object
const fresh = new URLSearchParams({
  search: 'TypeScript generics',
  limit: '20',
  offset: '0'
});
fresh.toString();
// → "search=TypeScript+generics&limit=20&offset=0"

Output:

page=3&tag=js&tag=ts&tag=rust
page = 3
tag = js
tag = ts
tag = rust
search=TypeScript+generics&limit=20&offset=0

Manual parsing for bracket notation and nested parameters

// Parse bracket-notation arrays: ?colors[]=red&colors[]=blue
function parseBracketArrays(queryString) {
  const params = new URLSearchParams(queryString);
  const result = {};

  for (const [key, value] of params) {
    // Detect array bracket notation: key[]
    const arrayMatch = key.match(/^(.+)\[\]$/);
    if (arrayMatch) {
      const name = arrayMatch[1];
      if (!result[name]) result[name] = [];
      result[name].push(value);
    } else {
      result[key] = value;
    }
  }
  return result;
}

parseBracketArrays('colors[]=red&colors[]=blue&page=1');
// → { colors: ["red", "blue"], page: "1" }

Standards & Specifications

• RFC 3986 — URI Generic Syntax — Section 3.4 defines the query component grammar and percent-encoding rules
• WHATWG URL Standard — Defines the URLSearchParams interface used by browsers and server runtimes
• HTML Living Standard — Form Submission — Specifies application/x-www-form-urlencoded encoding (plus-sign convention for spaces)