urlSearchParams.get()
Returns the first value for a query parameter name, or null when that name is absent.
urlSearchParams.get(name)- Added in Node.js v7.5.0, v6.13.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$name | string | The parameter name to look up. Matching is exact and case-sensitive; non-string arguments are coerced to a string. |
Return value
string | nullA string, or null if there is no name-value pair with the given name.
Errors
Throws a TypeError when called with no arguments.
get() looks up a parameter by name and returns its value already percent-decoded — %20 and + come back as spaces, %26 as &. Because the collection is a multimap, it returns the value of the first matching pair only.
When to reach for it
Use it for the everyday single-value read: a page number, a search term, an OAuth code. Reach for getAll() instead whenever the parameter is a filter or tag that a client may legitimately repeat, and for has() when you only care about presence.
What trips people up
Three return values look alike but mean different things. A missing key gives null. A key present with nothing after the = (?empty=) gives the empty string ''. A bare flag with no = at all (?flag) also gives '', not null — so if (params.get('flag')) is false even though the flag was supplied. Use has() for flags.
The result is always a string, never a number. params.get('page') + 1 on ?page=2 produces '21'; wrap it in Number() first. Names are also case-sensitive: get('Page') will not find page.
Example
When to use it
- Read the search term out of an incoming request's query string
- Pull code and state from an OAuth redirect before exchanging the token
- Fall back to a default page size when the caller omitted the parameter
- Detect whether a webhook URL carried the expected verification token
Frequently asked questions
Why does urlSearchParams.get return null?
Because no pair with that exact name exists — check spelling and case, since lookups are case-sensitive. If the parameter is present but has no value you get an empty string instead, not null.
How do I get all values when a query parameter repeats?
Use getAll(name), which returns an array of every matching value in order; get(name) only ever returns the first. getAll returns an empty array rather than null when the name is absent.
Does get() decode percent-encoded values?
Yes. Values are returned fully decoded, with %XX sequences and + both resolved, so you should not call decodeURIComponent on the result — doing so can corrupt values containing a literal %.
More examples
Reading parameters with safe defaults
?? only falls back when get() returns null, so an explicitly empty q= would stay empty rather than being replaced. Note that %20 in the URL comes back as a real space — get() decodes for you.
const url = new URL('https://api.example.com/items?page=3&q=node%20url');
const p = url.searchParams;
const page = Number(p.get('page') ?? 1);
const perPage = Number(p.get('per_page') ?? 25);
const q = p.get('q') ?? '';
console.log({ page, perPage, q });
console.log('decoded query term:', JSON.stringify(q));Handling repeated keys correctly
get() silently discards 'pending' — a classic source of filters that half work. getAll() always returns an array, even for a single occurrence, which makes it safe to use unconditionally for list-shaped parameters.
const p = new URLSearchParams('status=open&status=pending&assignee=carol');
console.log('get:', p.get('status'));
console.log('getAll:', p.getAll('status'));
console.log('assignee:', p.getAll('assignee'));
const filters = { status: p.getAll('status'), assignee: p.get('assignee') };
console.log(filters);Case sensitivity and decoding
Lookups are exact: 'token' misses the 'Token' entry and returns null. Both encodings decode on read — %2B becomes a literal +, %20 and + both become spaces.
const p = new URLSearchParams('Token=a%2Bb%20c¬e=hello+world');
console.log(p.get('Token'));
console.log(p.get('token'));
console.log(p.get('note'));
console.log([...p.keys()]);
Discussion