Google SERP API in Node.js
In Node.js 18 or later, call BestSERP with the built-in fetch: POST a JSON body such as {"q": "coffee"} to /search with your key in the X-API-KEY header, then read the organic array of the JSON response. No package is needed. Poll /requests/{requestId} if the API answers 202.
Last updated:
Key takeaways
- No SDK to install: Node.js's standard HTTP client is enough.
- Send the key in the X-API-KEY header, never in a URL or in browser code.
- 202 means the search is still running: poll GET /requests/{requestId}.
- 60 searches per minute per account by default; 429 and 503 are not charged.
Step by step
Set your key
Create a key in the dashboard and pass it as an environment variable.
Shellexport BESTSERP_API_KEY=bsa_your_keyA search function with polling
Works in Node.js 18+ as an ES module (search.mjs).
search.mjsconst API = "https://api.bestserp.com"; const headers = { "X-API-KEY": process.env.BESTSERP_API_KEY, "Content-Type": "application/json" }; const sleep = (ms) => new Promise((r) => setTimeout(r, ms)); export async function search(endpoint, body) { let res = await fetch(`${API}/${endpoint}`, { method: "POST", headers, body: JSON.stringify({ timeout: 120, ...body }) }); while (res.status === 202) { const { requestId } = await res.json(); await sleep(2000); res = await fetch(`${API}/requests/${requestId}`, { headers }); } const data = await res.json(); if (!res.ok) throw new Error(`${res.status} ${data.error?.code}: ${data.error?.message}`); return data; } const data = await search("search", { q: "best running shoes", gl: "us", hl: "en" }); for (const item of data.organic ?? []) console.log(item.position, item.title, item.link);Use it in a server route
Call the API from your backend, never from the browser: the key must stay secret.
Status codes to handle
What the search endpoints answer, and whether the request costs credits.
| Status | Code | Meaning | Credits |
|---|---|---|---|
| 202 | - | Not finished within timeout (or async: true). Poll pollUrl. | Reserved |
| 400 | invalid_request | Malformed body or a parameter out of range. | No |
| 400 | unknown_parameter | A field the API does not know (typo?). | No |
| 400 | unsupported_parameter | A known field that this endpoint does not support yet (e.g. location). | No |
| 401 | missing_api_key / invalid_api_key | No key, or the key is wrong or revoked. | No |
| 402 | insufficient_credits | Your balance is too low for this request. | No |
| 403 | account_suspended | The account is suspended. | No |
| 404 | not_found | Unknown requestId, or it belongs to another account. | - |
| 429 | rate_limited | Too many requests this minute. See Retry-After. | No |
| 502 | search_failed | The search could not be completed (blocked or timed out). | Refunded |
| 503 | busy | No capacity right now. Retry after Retry-After seconds. | Refunded |
Frequently asked questions
Do I need axios or another package?
No. fetch is built into Node.js 18 and later. Any HTTP client works if you prefer one.
Can I call the API from the browser?
Do not: the key would be visible to every visitor. Call it from your server or a serverless function.
Does it work with TypeScript?
Yes. The response fields are listed on each API page and in the docs; describe the parts you use as interfaces.
What about rate limits?
60 searches per minute per account by default. On 429, wait for the Retry-After seconds; the rejected request is not charged.
Start with 3,000 free searches
No credit card. Sign in with Google, create a key, send your first request.