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.