Google Scraper Guide: Maps, Web Search, Shopping, News & Ads Transparency

Scraping is async: submit a run → poll → fetch records. See the flow in Quick Start; the shared envelope, run state machine, billing, and errors are in Auth & Error Handling.

Quick Facts

• Base URL: https://api.antsdata.com/v1
• Auth: header Authorization: Bearer ants_xxx (static API Key)
• Content-Type: application/json
• Request body: every endpoint is POST /v1/scraper/google/<resource>, with a uniform body { "deliveryMode": "async", "recordLimit": 1000, "targets": [ … ] }; each element of targets[] is one query (fields listed under each endpoint's "Target fields").

💡 You can also use deliveryMode: "sync" (small jobs block until terminal, auto fallback to polling on timeout) — see quick-start · Sync mode.

• Submit receipt: on success returns HTTP 201 + a Run object (with id, status: "queued"). Note the id.
• Fetch: poll GET /v1/scraper/runs/{id} by id until succeeded, then GET /v1/scraper/runs/{id}/records?page=&pageSize= to page records, or GET /v1/scraper/runs/{id}/download?format=json|csv|excel to download. Full end-to-end flow: Quick Start.
• Billing: charged per successfully produced record; failed targets release the hold and are not billed. Details in Auth & Error Handling.

Endpoint Overview

Maps

POST /v1/scraper/google/maps

Extract Google Maps places / businesses: keyword search, reverse geo lookup, and geocoding.

Target fields (each element of targets[]):

Output fields (each record when fetching):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/google/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "query": "coffee shop", "location": "San Francisco, CA", "resultsLimit": 20 }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }, then poll by id and fetch records (see Quick Start).

Web Search

POST /v1/scraper/google/search

Extract Google web search organic results.

Target fields (each element of targets[]):

Output fields (each record when fetching):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/google/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "query": "best web scraping tools", "geo_location": "California,United States", "host_language": "en" }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }, then poll by id and fetch records (see Quick Start).

Shopping

POST /v1/scraper/google/shopping

Extract Google Shopping product listings.

Target fields (each element of targets[]):

Output fields (each record when fetching):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/google/shopping" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "query": "wireless earbuds", "gl": "us", "sortBy": "price_asc", "resultsLimit": 30 }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }, then poll by id and fetch records (see Quick Start).

News

POST /v1/scraper/google/news

Extract Google News results across keyword, top, topic, and publication feeds.

Target fields (each element of targets[]):

Output fields (each record when fetching):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/google/news" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "feedType": "keyword", "query": "artificial intelligence", "timeRange": "7d", "gl": "US" }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }, then poll by id and fetch records (see Quick Start).

Ads Transparency

Scrape Google's Ads Transparency Center: advertisers, ad creatives, and their impression / spend data. Typical chain: use Ads Suggestions to get a sponsor_id → Ads Creatives to list creative_ids → Ads Creative Details for spend / impression ranges; Ads Advertiser for entity info.

Ads Suggestions

POST /v1/scraper/google/ads-suggestions

Suggest advertisers / keywords by search term — use it to locate a sponsor_id.

Target fields (each element of targets[]):

Output fields (each record when fetching):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/google/ads-suggestions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "keyword": "nike" }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }, then poll by id and fetch records (see Quick Start).

Ads Creatives

POST /v1/scraper/google/ads-creatives

List ad creatives by advertiser or keyword.

Target fields (each element of targets[]):

Output fields (each record when fetching):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/google/ads-creatives" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "advertiser_id": "AR16735076323512287233", "regions": ["US"], "platform": 1, "limit": 100 }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }, then poll by id and fetch records (see Quick Start).

Ads Creative Details

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

Full details for a single creative, including spend and impression ranges.

Target fields (each element of targets[]):

Output fields (each record when fetching):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/google/ads-creative-details" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "sponsor_id": "AR16735076323512287233", "creative_id": "CR12886158981977866241" }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }, then poll by id and fetch records (see Quick Start).

Ads Advertiser

POST /v1/scraper/google/ads-advertiser

Advertiser entity information.

Target fields (each element of targets[]):

Output fields (each record when fetching):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/google/ads-advertiser" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "advertiser_id": "AR16735076323512287233" }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }, then poll by id and fetch records (see Quick Start).

Fetching Records & Billing

After submitting to any endpoint:

1. Poll GET /v1/scraper/runs/{id} until status: "succeeded" (back off 1s→2s→5s).
2. GET /v1/scraper/runs/{id}/records?page=1&pageSize=20 to page records — each items[] element carries the "Output fields" listed per endpoint above; or GET /v1/scraper/runs/{id}/download?format=csv to download the full output.
3. Billing settles per successfully produced record (the run object's chargedCredits); if all targets fail, the hold is released and nothing is billed.

End-to-end examples and the run state machine: Quick Start and Auth & Error Handling.

Next Steps

• Platform guides: TikTok · X · Instagram · Facebook · LinkedIn · YouTube · Amazon
• Synchronous search: Google SERP
• Auth & Error Handling — Unified envelope, run state machine, billing & error codes

FAQ

Q: Why don't I get data back directly after submitting?

Scraping is async: submit to get a run id, it runs in the background, you poll id until succeeded, then fetch records / download. See Quick Start.

Q: Can I query multiple targets at once?

Yes. targets is an array — one run can contain many queries (e.g. several search terms / advertisers). Per-target outcomes appear in the tasks[] of the polled run.

Q: Does Web Search always return an AI Overview?

No. The search endpoint returns organic results (pos / title / url / desc, etc.). AI Overview and other rich blocks only appear for topics where Google shows them and are not guaranteed. pos_overall reflects whole-page rank including non-organic blocks.

Q: Are Ads Transparency spend / impression figures exact?

No. Google only discloses ranges: spend_lower / spend_upper, impressions_lower / impressions_upper, and typically only for political / EU ads — for regular ads these fields are null. This API returns them as-is.

Q: Where does a creative's creative_id come from?

Call Ads Suggestions to get a sponsor_id, then Ads Creatives to list creative_ids, then query Ads Creative Details with both. Do not hard-code creative_id.

Q: Am I charged for failed scrapes?

No. If all targets fail the hold is released and nothing is billed; partial success is charged only for the records actually produced. See Auth & Error Handling.

Q: How is this page's Google different from "Google SERP"?

This page is the scraper product line (/v1/scraper/google/*): async runs, input is a targets[] array, and you poll for records after submitting. If you want search results returned synchronously (flat input, one call gets the data), use Google SERP (/v1/serp/google/*). The two share endpoint names (search / shopping / news / maps / ads-creatives / ads-creative-details), but their input shape and required fields differ — follow each page for its own contract.