URL Query Parameters: Parsing, Encoding, and Best Practices

Anatomy of a Query String

A URL query string starts with ? and contains key-value pairs separated by &. Each key and value can be percent-encoded.

https://example.com/search?q=hello+world&lang=en&page=2
                                ^^^^^^^^^^^^^^^^^^^^^^^^^
                                      query string

URLSearchParams: The Modern API

The browser's built-in URLSearchParams handles all the parsing and encoding for you:

const params = new URLSearchParams(window.location.search);

params.get('q');          // "hello world"
params.get('lang');       // "en"
params.getAll('tag');     // ["js", "ts"] for ?tag=js&tag=ts

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

// Convert to a plain object
const obj = Object.fromEntries(params);

Query Params to JSON

Converting a query string to a structured JSON object is a common task when debugging API requests or building middleware. The main challenge is handling repeated keys (arrays) and nested objects.

function queryToJson(search) {
  const params = new URLSearchParams(search);
  const result = {};
  for (const [key, value] of params) {
    if (result[key] !== undefined) {
      result[key] = [].concat(result[key], value);
    } else {
      result[key] = value;
    }
  }
  return result;
}

queryToJson('?a=1&b=2&a=3');
// { a: ['1', '3'], b: '2' }

Percent-Encoding Rules

Query string values must be percent-encoded when they contain reserved characters. Common ones:

• space → %20 (or + in application/x-www-form-urlencoded)
• & → %26
• = → %3D
• + → %2B
• # → %23
• / → %2F

Use encodeURIComponent() for values, and URLSearchParams to build the full string — it handles encoding automatically.

const params = new URLSearchParams({
  q: 'hello & world',
  tags: 'css+js'
});
params.toString();
// q=hello+%26+world&tags=css%2Bjs

Nested Parameters

HTTP does not define a standard for nested parameters — different frameworks use different conventions:

# PHP / Ruby on Rails style
filter[status]=active&filter[type]=user

# Repeated keys for arrays
tag[]=js&tag[]=ts

# Dot notation (some ORMs)
user.name=Alice&user.age=30

When parsing nested params, you need to know the convention your backend uses. URLSearchParams treats all keys as flat strings — parsing the bracket or dot notation is the application's responsibility.

Best Practices

• Use URLSearchParams to build query strings — never concatenate manually
• Keep keys lowercase and hyphenated — consistent with HTTP header conventions
• Avoid sensitive data in query strings — they appear in server logs, referrer headers, and browser history
• Use pagination params consistently — prefer page/per_page or offset/limit, not a mix
• Document defaults — if ?page= is omitted, document what the default is

Debugging Query Strings

When a query string arrives malformed — double-encoded, wrong separators, missing values — parsing it into a JSON object lets you inspect the structure immediately. You can spot at a glance whether %26 was used as a literal value or accidentally double-encoded.