SERP checker API

One authenticated POST returns live structured Google SERP results for a keyword — positions, titles, URLs, and types — with device, location, and language parameters.

One REST Endpoint
Precise Market Targeting
Device And Browser Fidelity
Structured Result Items
Idempotent Billable Writes
Predictable Error Codes

Tool API Agent

Request examples

View API docs Full API reference

curl -X POST "https://api.agentbody.io/v1/seo/google-serp" \
  -H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"browser_screen_density":"1","browser_screen_height":"1","browser_screen_resolution":"YOUR_BROWSER_SCREEN_RESOLUTION","browser_screen_width":"1","calculate_rectangles":"true","depth":"1","device":"desktop","keyword":"YOUR_KEYWORD","language_code":"YOUR_LANGUAGE_CODE","language_name":"YOUR_LANGUAGE_NAME","load_async_ai_overview":"true","location_code":"1","location_coordinate":"YOUR_LOCATION_COORDINATE","location_name":"YOUR_LOCATION_NAME","os":"windows","se_domain":"YOUR_SE_DOMAIN","search_param":"YOUR_SEARCH_PARAM"}'

Response examples

Documented responses from the OpenAPI specification.

Organic search results.

{
  "items": [],
  "items_count": 0,
  "keyword": "example_value"
}

Features

Use the SERP API to fetch live, structured Google results for a keyword — with device, location, language, and domain parameters — for rank trackers, SEO tooling, and data pipelines.

One REST Endpoint

Call POST /v1/seo/google-serp with a bearer API key and a keyword. The SERP API runs the search live and returns the results page as structured JSON, so your application gets rankings without hosting browsers, rotating proxies, or maintaining a parser.

Precise Market Targeting

Pin each request to a market with location_name, location_code, or location_coordinate, a language, and a Google se_domain. Rankings differ by geography and tongue; these parameters make every request reproducible for the market your product tracks.

Device And Browser Fidelity

Set device to desktop or mobile, and optionally the browser screen dimensions the search should run at. SERP layout and feature coverage differ per device class — the API exposes the knobs so your data matches how users actually search.

Structured Result Items

Receive ordered result items with position, title, URL, and result type, plus optional deeper parsing controls such as depth and calculate_rectangles. The schema is designed for storage: drop items straight into a rank-tracking table or analysis pipeline.

Idempotent Billable Writes

Live SERP requests are metered operations. Send an Idempotency-Key header on retries so an interrupted response does not turn into a double-billed search — the gateway treats repeated identical requests with the same key as one.

Predictable Error Codes

Handle failures with documented status codes: 400 for an invalid request, 401 for a missing or bad API key, 402 for insufficient balance, and 502, 503, or 504 for temporary upstream issues. Each class maps to a distinct retry or fix action.

How to use

Follow these six steps to call the SERP API: create a key, build the POST request with a keyword and market parameters, and process the structured results.

Create An API Key

Create an AgentBody account and generate an API key in the console. Keep the key in your server environment or an approved secret store and send it as a bearer token. Never place a live key in browser code or client bundles.

Build The Request Body

Send POST /v1/seo/google-serp with the required keyword and your chosen options — device, location, language, se_domain, and depth. The generated examples on this page show the exact request in curl, JavaScript, Python, Java, and Go.

Add An Idempotency Key

Attach an Idempotency-Key header to every search you might retry — timeouts, connection drops, worker restarts. The gateway returns the original response for a repeated key instead of running and billing a second identical search.

Keep The Key Server-Side

Call the endpoint from your backend, a serverless function, or a scheduled job — anywhere the API key stays out of the browser. If end users trigger checks, proxy the call through your own endpoint so key and billing stay under your control.

Parse The JSON Response

Read the ordered result items with their position, title, URL, and type fields. Store what your tracker needs, tag each row with the request's market parameters, and you have a reproducible rank series from day one.

Handle Errors Correctly

Fix 400 responses by correcting the request body, 401 by configuring a valid key, and 402 by topping up balance. Retry 502, 503, and 504 with backoff and the same idempotency key — they are temporary upstream conditions, not permanent failures.

Frequently asked questions

What is SerpApi, and what is this SERP API?

SerpApi is a well-known provider of scraped search results. This SERP API is AgentBody's take on the same job: an authenticated POST endpoint, /v1/seo/google-serp, that runs a live Google search and returns the results page as structured JSON with position, title, URL, and result type per item, plus device, location, and language controls.

How does SERP API pricing work?

Each live search is a metered operation that runs on your account's credits. Usage-based pricing is governed by the gateway rather than fixed numbers on this page — check the console for current per-call costs, and use idempotency keys so retries never double-bill.

How does it compare to a Serper API or other SERP scrapers?

Whether you evaluated a Serper API, a SerpApi plan, or a self-hosted Google SERP API scraper, the tradeoff is the same: headless browsers, proxy rotation, CAPTCHA handling, and a parser that breaks on layout changes. AgentBody's SERP API replaces that stack with one documented endpoint — POST /v1/seo/google-serp with market parameters and idempotent retries, reading live public results only.

Can I get results for a specific country or city?

Yes. Pass location_name, location_code, or location_coordinate in the request body. The search executes for that market, so the rankings reflect what searchers there see — the core of local rank tracking.

Does it support non-Google.com domains and languages?

Set se_domain to the Google domain your market uses and language_name or language_code for the search language. Combined with the location options, each request is pinned to a reproducible market configuration.

How do I handle API errors?

Correct the request body on 400, fix your bearer key on 401, and resolve balance on 402. Treat 502, 503, and 504 as temporary upstream failures and retry with backoff under the same idempotency key. Log status codes so your pipeline distinguishes bad requests from transient issues.