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

  1. Set your key

    Create a key in the dashboard and pass it as an environment variable.

    Shell
    export BESTSERP_API_KEY=bsa_your_key
  2. A search function with polling

    Works in Node.js 18+ as an ES module (search.mjs).

    search.mjs
    const 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);
  3. 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.
StatusCodeMeaningCredits
202-Not finished within timeout (or async: true). Poll pollUrl.Reserved
400invalid_requestMalformed body or a parameter out of range.No
400unknown_parameterA field the API does not know (typo?).No
400unsupported_parameterA known field that this endpoint does not support yet (e.g. location).No
401missing_api_key / invalid_api_keyNo key, or the key is wrong or revoked.No
402insufficient_creditsYour balance is too low for this request.No
403account_suspendedThe account is suspended.No
404not_foundUnknown requestId, or it belongs to another account.-
429rate_limitedToo many requests this minute. See Retry-After.No
502search_failedThe search could not be completed (blocked or timed out).Refunded
503busyNo 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.