Getting started

Quickstart

Submit your first search and read the results in under 5 minutes.

1. Get an API key

Create an account, then generate a key from the SERP API dashboard. The raw key is shown once at creation, so copy it immediately. Keys look like sk_xxxxxxxxxxxxxxxxxxxxxxxx and carry a tier and a monthly quota.

Store the key securely

Treat the key like a password. Send it only from your server, never from browser code, and keep it out of version control.

2. Submit a search

Post a keyword and a location. By default the search is asynchronous: you get a job_id back immediately while the crawl runs on the worker fleet.

request

curl -X POST https://serp-api.hoangha.shop/v1/search \
  -H "X-API-Key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "best running shoes",
    "location": "Hanoi, Vietnam",
    "device": "desktop"
  }'

response

{
  "job_id": "9f3c1e2a-...",
  "status": "queued",
  "cached": false
}

3. Poll for the result

Fetch the job by id, asking for the serpapi output format. While the crawl runs, the endpoint returns a non-terminal status; keep polling every second or two until the status is done or partial.

request

curl "https://serp-api.hoangha.shop/v1/search/9f3c1e2a-...?output=serpapi" \
  -H "X-API-Key: sk_..."

still running (HTTP 202)

{ "job_id": "9f3c1e2a-...", "status": "running" }

done (HTTP 200)

{
  "search_metadata": { "id": "9f3c1e2a-...", "status": "done" },
  "search_parameters": { "q": "best running shoes", "gl": "vn", "hl": "vi", "device": "desktop" },
  "organic_results": [
    {
      "position": 1,
      "title": "The 12 Best Running Shoes of 2026",
      "link": "https://example.com/best-running-shoes",
      "displayed_link": "https://example.com › running",
      "snippet": "Our testers logged 500+ miles to rank..."
    }
  ],
  "ai_overview": { "text_blocks": [ ... ], "references": [ ... ] },
  "related_questions": [ ... ]
}

4. (Optional) Get results in one call

If you need a single blocking call instead of polling, set async: false. The request holds open until the crawl finishes or the server-side sync timeout elapses, then returns the job’s current state.

synchronous request

curl -X POST https://serp-api.hoangha.shop/v1/search \
  -H "X-API-Key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword": "best running shoes", "location": "Hanoi, Vietnam", "async": false}'

Sync mode trades throughput for latency and can still time out on slow crawls. For batch or high-volume work, prefer the default async flow. See Guides for the trade-offs.

Next steps

Submit a search — every request parameter, including geo, device, and Google query knobs.
Retrieve results — job lifecycle, polling, and the three output formats.
MCP server — let an AI agent run searches as a tool.