Google SERP API documentation

One endpoint returns a live Google results page as JSON: organic results with positions, People Also Ask, ads and the complete AI Overview with its cited sources. This page covers authentication, parameters, the response schema, errors and limits.

Authentication
Request
Response
AI Overview
Errors
Markets
Code examples

Authentication

Send your key in the Authorization header as a Bearer token on every request. Keys are issued per account — request one with 20,000 free test requests. Never put the key in browser code; call the API from your backend.

Authorization: Bearer YOUR_API_KEY

Request: POST /v1/search

POST https://serp.hilgard.cz/v1/search with a JSON body (Content-Type: application/json, max 4 KB).

Parameter	Type	Default	Description
query	string	required	Search query, 1–200 characters.
country	string	"us"	Google country code (gl). See supported markets below.
language	string	"en"	Interface and results language (hl).
include_ai_overview	boolean	true	Extract the AI Overview. Set false when you only need rankings (~2 s instead of ~15 s).

Response

A successful call returns HTTP 200 and the object below. Only these responses are billed.

Field	Type	Description
search_metadata.status	number	Always 200 on success.
search_metadata.latency_ms	number	End-to-end time of the request.
search_metadata.ai_overview_status	string	"extracted", "not_present" (Google showed none), "failed" or "skipped".
organic_results[]	array	Organic results in ranking order.
organic_results[].position	number	1-based rank on the page.
organic_results[].title / url / snippet	string	Result title, resolved target URL and snippet.
organic_results[].domain	string	Registrable domain, e.g. "teamwork.com" — handy for share-of-voice.
organic_results[].displayed_url	string	Breadcrumb URL as Google shows it.
people_also_ask[].question	string	People Also Ask questions, in page order.
ads[]	array	Paid results: position, headline, url, domain, description.
has_next_page	boolean	Whether Google offers a further results page.
ai_overview.present	boolean	False when Google shows no AI Overview for this query and market.
ai_overview.markdown	string	Full AI Overview as markdown, with a numbered source list.
ai_overview.text	string	The same answer as plain text.
ai_overview.sources[]	array	Cited sources in citation order: position, title, url, domain, attribution.
ai_overview.cited_domains[]	array	Per-domain roll-up: domain, count, first_position.

AI Overview extraction

Google renders the AI Overview progressively, so the API waits until the answer stops growing before reading it — you get the complete text, not the first paragraph. That is why a request with include_ai_overview: true takes around 15 seconds, while organic results alone come back in about 2 seconds.

Citation chips, embedded video cards and the source panel are stripped from the text; the citations are returned separately in sources (in the order Google cites them) and rolled up per domain in cited_domains — the metric to track when you measure AI visibility for a brand.

Google does not show an AI Overview for every query. In that case ai_overview.present is false and ai_overview_status is "not_present": a real observation for that query and market, not an error.

Errors and limits

Errors are JSON { "error": "...", "message": "..." }. Failed requests are never billed.

HTTP	error	Meaning
400	bad_request	Invalid JSON, missing query or unsupported country / language.
401	unauthorized	Missing or invalid API key.
429	rate_limited	Per-key rate limit exceeded — honour the Retry-After header.
502 / 504	upstream_error	Google could not be fetched in time. Retry — failed requests are not billed.

Supported markets

Countries (country): United States (us), United Kingdom (gb), Germany (de), France (fr), Spain (es), Italy (it), Netherlands (nl), Poland (pl), Czechia (cz), Slovakia (sk), Austria (at), Switzerland (ch), Canada (ca), Australia (au), India (in), Brazil (br), Mexico (mx), Japan (jp).

Languages (language): English (en), German (de), French (fr), Spanish (es), Italian (it), Dutch (nl), Polish (pl), Czech (cs), Slovak (sk), Portuguese (pt), Japanese (ja). Need another market? Ask.

Code examples

cURL, Python, Node.js and Go. Want to see real output first? Run a live query in the playground.

curl -X POST https://serp.hilgard.cz/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best enterprise crm",
    "country": "us",
    "include_ai_overview": true
  }'

200 OK · application/json

{
  "search_metadata": {
    "status": 200,
    "latency_ms": 1420,
    "query": "best enterprise crm",
    "country": "us",
    "language": "en",
    "ai_overview_status": "extracted"
  },
  "ai_overview": {
    "present": true,
    "markdown": "The best enterprise CRM depends on scale and ecosystem…\n\n- **Salesforce:** the most customizable…\n- **Microsoft Dynamics 365:** strongest fit for…",
    "sources": [
      {
        "position": 1,
        "title": "The 10 Best Enterprise CRM Software of 2026",
        "url": "https://www.example.com/enterprise-crm",
        "domain": "example.com",
        "attribution": "Example"
      },
      {
        "position": 2,
        "title": "Enterprise CRM comparison",
        "url": "https://www.example.org/crm",
        "domain": "example.org",
        "attribution": "Example Org"
      }
    ],
    "cited_domains": [
      {
        "domain": "example.com",
        "count": 2,
        "first_position": 1
      }
    ]
  },
  "organic_results": [
    {
      "position": 1,
      "title": "Best Enterprise CRM Software",
      "url": "https://www.example.com/",
      "domain": "example.com",
      "displayed_url": "https://www.example.com › crm",
      "snippet": "…"
    }
  ],
  "people_also_ask": [
    {
      "question": "What is the #1 CRM for enterprise?"
    }
  ]
}