Blog
3 min read

Query Parameters Explained: The ?key=value Part of a URL

Query parameters are the key=value pairs after the ? in a URL, used for search, filters, sorting and pagination. How they're written and encoded, reading them in JavaScript, Express and Next.js, query vs path parameters, and what never to put in them.

In this URL:

https://shop.example.com/products?category=lamps&sort=price&page=2

everything after the ? is the query string, made of query parameters: category=lamps, sort=price, page=2. They pass extra information to the page or API without changing which page you're on. (Anatomy of a URL)

The format

  • Starts with ?
  • Each parameter is key=value
  • Parameters are separated by &
  • Order doesn't matter (usually)
  • Repeated keys are allowed: ?tag=red&tag=blue

What they're used for

  • Search: ?q=desk+lamp
  • Filters: ?category=lamps&in_stock=true
  • Sorting: ?sort=price&order=desc
  • Pagination: ?page=2&limit=20 (API pagination)
  • Tracking: ?utm_source=newsletter (marketing campaigns)
  • State you want shareable: a filtered view someone can bookmark or send

That last point is the real superpower: if your app's filters live in the URL, people can share exactly what they see, and the back button works.

Encoding special characters

Spaces, &, =, ?, # and non-English characters must be encoded so they don't break the URL:

Character Encoded
space %20 (or + in query strings)
& %26
= %3D
é %C3%A9

Don't build query strings by gluing text together — use the built-in tools, which encode for you:

const params = new URLSearchParams({ q: 'rock & roll', page: '2' })
fetch(`/api/search?${params}`) // /api/search?q=rock+%26+roll&page=2

Reading them

In the browser:

const params = new URLSearchParams(window.location.search)
params.get('page')   // "2"  — always a string, or null if missing
params.getAll('tag') // ["red", "blue"]

In Express:

app.get('/products', (req, res) => {
  const page = Number(req.query.page ?? 1)
})

In Next.js (App Router) — pages receive searchParams; client components use the useSearchParams() hook.

Values always arrive as strings. "2" isn't 2, and "false" is truthy. Convert and validate them. (Validating input with Zod)

Query parameters vs path parameters

/users/42           ← path parameter: which resource
/users?role=admin   ← query parameter: how to filter or view

A good rule: the path identifies what you're looking at; the query describes how (filtered, sorted, which page). /products/123 for one product, /products?category=lamps for a filtered list. (Designing a REST API)

What never to put in query parameters

Secrets. Passwords, API keys, session tokens and personal data in URLs end up in:

  • browser history,
  • server and proxy logs,
  • analytics tools,
  • the Referer header sent to other sites when someone clicks a link.

Send sensitive data in the request body (for POST) or a header (for tokens). (GET vs POST, HTTP headers explained)

SEO note

Parameters like ?sort= or ?utm_source= can create many URLs with the same content. Use a canonical URL to tell search engines which version is the real one. (Canonical URLs explained)

The summary

  • Query parameters = ?key=value&key2=value2 after the path.
  • Use them for search, filters, sorting, pagination and shareable state.
  • Build and read them with URLSearchParams; values are always strings.
  • Never put secrets in them.

EasySpawn runs your app and API on one server, with Claude Code on hand to wire up filters, pagination and validation properly. See how it works or join the waitlist.

Related: Anatomy of a URL · GET vs POST · What Is an API? · HTTP Headers Explained

Keep reading