API reference

13 endpoints on one host, authenticated with a header. Every successful request costs one credit, and failures cost nothing.

Authentication

Send your key in the x-api-key header. Keys are shown once when created, on the API keys page. Never ship a key in client-side code — anyone who can read it can spend your credits.

Making a request

Every endpoint takes GET with query string parameters or POST with a JSON body.

curl "https://api.serpdata.dev/google/search/web?q=best%20espresso%20machine" \
  -H "x-api-key: $SEARCHAPI_KEY"

curl -X POST "https://api.serpdata.dev/google/search/news" \
  -H "x-api-key: $SEARCHAPI_KEY" \
  -H "content-type: application/json" \
  -d '{"q":"openai"}'

City targeting

On /google/search/web, combine a canonical-name Google uule with the matching two-letter gl country code. Both search modes support location: mode=simple uses Google's Web results (udm=14), while mode=rich uses the full results page (no udm).

These examples target London, England, United Kingdom. For GET, use URL encoding so the plus sign survives transport. For a POST JSON body, paste the original w+…value. Do not paste an already percent-encoded value into JSON or the playground.

curl --get "https://api.serpdata.dev/google/search/web" \
  -H "x-api-key: $SEARCHAPI_KEY" \
  --data-urlencode "q=coffee shops near me" \
  --data-urlencode "mode=simple" \
  --data-urlencode "gl=gb" \
  --data-urlencode "uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20="

curl -X POST "https://api.serpdata.dev/google/search/web" \
  -H "x-api-key: $SEARCHAPI_KEY" \
  -H "content-type: application/json" \
  -d '{"q":"coffee shops near me","mode":"rich","gl":"gb","uule":"w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20="}'

Supply a valid UULE encoded from a canonical name in Google's geographic-target dataset. Raw city names and coordinate-form a+ values are not accepted. Validation checks the value's syntax; it does not verify that the encoded city exists or matches your country. Successful responses echo gl and uule in searchParameters.

Location biases results toward the requested city; it does not exclude every result from elsewhere. In the playground, search for a city, region, or postal code in Location. Selecting a result sets UULE and its matching Country automatically. You can also paste a raw value into Location (UULE) under Advanced. Clear the location for a country-only search. The picker uses English names from Google’s location catalog. Suggestions are sorted by available population estimates from GeoNames, largest first. Locations without a matched population appear last.

Response

{  "searchParameters": {    "q": "python asyncio",    "type": "search",    "engine": "google"  },  "organic": [    {      "title": "Python's asyncio: A Hands-On Walkthrough",      "link": "https://realpython.com/async-io-python/",      "snippet": "Python's asyncio library enables you to write concurrent code using the async and await keywords. The core building bloc…",      "subtitle": "https://realpython.com › async-io-python",      "position": 3,      "date": "Jul 30, 2025",      "source": "Real Python",      "sitelinks": [        {          "title": "Async I/O in Python With asyncio",          "href": "https://realpython.com/async-io-python/#async-io-in-python-with-asyncio",          "style": "chip"        }      ]    }  ],  "latencyMs": 255,  "credits": 1,  "creditsRemaining": 2499}

Results come back in Google's order. Every response carries your remaining balance as creditsRemaining; the search and vertical routes also carry the credits that call cost, which is always 1. Entities gain fields over time, so parse leniently and ignore what you do not recognize.

Endpoints

Base url https://api.serpdata.dev.

Rate limits

API keys have no requests-per-second limit. Each request requires an active key and sufficient credits. Service capacity still applies: an overloaded service can return 503, and failed requests do not consume credits.

Errors

A 200 costs one credit, including one that finds nothing — an empty result is an answer we had to go and get. Every failure above either never took the credit or gives it back, so retrying a failure cannot drain a balance.

Client library

npm install @serpdata.dev/client gives you a typed client for every endpoint above. It is server-side only, for the same reason keys are: it carries your key.

OpenAPI

/openapi.json is generated from the same contract the API implements, so it cannot drift from what the endpoints above actually return. Import it into Postman or generate a client in your own language.

Search supports country targeting with gl and city targeting with uule. Autocomplete supports country (gl) and language (hl). See each endpoint's parameters above for supported options.