Google SERP API (Synchronous Search)

SERP endpoints are for "ask and get an answer" search: you submit a query and the server blocks until done and returns the results directly, unlike scraper's async "submit → poll → fetch" model. Ideal for small jobs; large jobs that exceed the sync window fall back to a pollable run (see below).

Three differences from scraper

Quick reference

• Base URL: https://api.antsdata.com/v1
• Method & path: POST /v1/serp/{platform}/{resource}. Currently platform is only google; see the endpoint list below for resource.
• Auth: header Authorization: Bearer ants_xxx (static API Key, same as scraper)
• Content-Type: application/json
• Request body: query fields flattened at the top level, plus two optional run-level fields:
  • recordLimit: record cap for this query (omit / 0 = derived from available credits).
  • dataFormat: result format, json (default, returns a records array) / csv / html / markdown (the latter three return exported text).

Status codes & response body

Uniform envelope { code, message, data }; the shape of data depends on the outcome:

• Timeout fallback: if a large query doesn't finish within the server's sync window → 202 + runId, and the run keeps running in the background. Switch to polling: GET /v1/serp/runs/{id}, then on success GET /v1/serp/runs/{id}/records to fetch or GET /v1/serp/runs/{id}/download?format=json|csv|excel to download.
• Payload too large: a synchronous payload > 16 MiB returns an error — use GET /v1/serp/runs/{id}/download to fetch the full result.
• Billing: same as scraper, charged per successfully returned record; failures release the hold and are not charged (see Authentication & Errors).

Endpoints

Search — Web Search

POST /v1/serp/google/search

Query fields (flattened at the top level of the body):

Output fields (records, one result per record):

Example:

curl -X POST "https://api.antsdata.com/v1/serp/google/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "bitcoin",
    "searchType": "web",
    "geo_location": "California,United States",
    "host_language": "en",
    "recordLimit": 50
  }'

Synchronous response (HTTP 200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "runId": "1287345",
    "status": "succeeded",
    "records": [
      {
        "organic": {
          "pos": 1,
          "pos_overall": 1,
          "title": "Bitcoin - Open source P2P money",
          "url": "https://bitcoin.org/",
          "desc": "Bitcoin is an innovative payment network ..."
        }
      }
    ]
  }
}

Shopping

POST /v1/serp/google/shopping

Query fields:

Output fields (records.products[], one product per record):

Example:

curl -X POST "https://api.antsdata.com/v1/serp/google/shopping" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "wireless earbuds",
    "gl": "us",
    "hl": "en",
    "minPrice": 50,
    "maxPrice": 300
  }'

News

POST /v1/serp/google/news

Query fields:

Output fields (records.articles[], one article per record):

Example:

curl -X POST "https://api.antsdata.com/v1/serp/google/news" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI regulation EU",
    "timeRange": "7d",
    "cluster": true,
    "hl": "en",
    "gl": "us"
  }'

Maps

POST /v1/serp/google/maps

Query fields:

Output fields (records.places[], one place per record):

Example:

curl -X POST "https://api.antsdata.com/v1/serp/google/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "coffee shop",
    "location": "Manhattan, NY",
    "gl": "us",
    "hl": "en",
    "openNow": false
  }'

Ads-creatives — Ad Creatives

POST /v1/serp/google/ads-creatives

Creative list from the Google Ads Transparency Center. The returned creative_id / sponsor_id can feed the "Creative Details" endpoint.

Query fields:

Output fields (records, one creative per record):

Example:

curl -X POST "https://api.antsdata.com/v1/serp/google/ads-creatives" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "nike.com",
    "regions": ["US"],
    "start_date": "2026-01-01",
    "end_date": "2026-06-30",
    "platform": 1
  }'

Ads-creative-details — Creative Details

POST /v1/serp/google/ads-creative-details

Impression / spend / political-ad disclosure details for a single creative. Get sponsor_id and creative_id from the "Ad Creatives" endpoint first; don't hardcode them.

Query fields:

Output fields (records, one creative detail per record):

Example:

curl -X POST "https://api.antsdata.com/v1/serp/google/ads-creative-details" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sponsor_id": "AR00040546930815664129",
    "creative_id": "CR12886158981977866241"
  }'

FAQ

Q: How is SERP different from /v1/scraper/google/*?

They share the same underlying Google scraping capability, but SERP (/v1/serp/google/*) is a synchronous, flat-input wrapper: one call returns results directly, with no targets array and no polling. Use /v1/scraper/google/* for async batches and webhook delivery.

Q: I got a 202 — what now?

202 means the query was large and didn't finish within the sync window, but the run continues in the background. Take the runId and poll GET /v1/serp/runs/{id}; once succeeded, fetch with GET /v1/serp/runs/{id}/records or download via /download.

Q: Which dataFormat values are supported?

json (default, records array) and csv / html / markdown (returns content text + format).

Q: The result is too big to return?

The synchronous payload limit is 16 MiB; larger returns an error. Use GET /v1/serp/runs/{id}/download?format=json|csv|excel to fetch it all at once.

Q: How is it billed?

Same as scraper — charged per successfully returned record; failures release the hold and aren't charged. See Authentication & Errors.