Launch pricing: 78% of pool capacity allocated. Rates rise as it fills. Lock in today's rate →
Skip to content

API reference

The SerpWiz API is a set of read-only HTTPS GET endpoints that return JSON.

  • Base URL: https://api.serpwiz.com/v1
  • Auth: X-API-Key: sw_live_… (details)
  • Format: JSON (UTF-8), gzip if you send Accept-Encoding: gzip
  • Machine-readable spec: OpenAPI 3.1

Endpoints

Method Path Description Cost
GET /v1/google/search Google web search results 1 query
GET /v1/google/maps Google Maps places (up to 20 per request) 1 query
GET /v1/account Balance, free allowance, RPS limit, plan free

Paths follow /v1/{engine}/{type}. New engines are added as new paths; existing paths don't change within v1.

Conventions

  • Parameters go in the query string, URL-encoded. Names are snake_case. Unknown parameters are ignored.
  • Charging: you're charged only when the response is 200. Every other status costs nothing.
  • Timeouts: searches usually return in a few seconds. Use a client timeout of at least 60 seconds.
  • Optional fields: result groups (ads, top stories, knowledge panel…) appear only when the results page has them. Treat every field except results as optional.

Response headers

Header Description
X-Request-Id Unique ID for the request. Include it when you contact support.
X-Credits-Charged Queries deducted for this request: 1 on success, 0 otherwise.
X-Credits-Remaining Free allowance plus balance left after this request.
X-RateLimit-Limit Your account's requests-per-second limit.
Retry-After On 429 and 503: seconds to wait before retrying.

Errors

Errors use one shape across every endpoint:

{
  "error": {
    "status": 429,
    "code": "rate_limited",
    "message": "Rate limit exceeded for your plan (1 RPS). Retry after the Retry-After header, or upgrade for more RPS.",
    "request_id": "9f2c1a7b3e4d5f60",
    "docs": "https://serpwiz.com/docs/errors"
  }
}

See Errors for every code.

CORS

The API sends Access-Control-Allow-Origin: * so you can test from a browser, but don't put API keys in client-side code — call the API from your server.

← Authentication Google Search →

This page as Markdown: /docs/api.md