ScrapeUnblocker Documentation

The /serpApi endpoint scrapes Google search results and returns normalized JSON. It handles the CAPTCHA gauntlet, ad rendering delays, and proxy rotation that make Google scraping painful.

Minimum request

curl -X POST "https://api.scrapeunblocker.com/serpApi?keyword=best+running+shoes" \
  -H "x-scrapeunblocker-key: YOUR_API_KEY"

import requests

r = requests.post(
    "https://api.scrapeunblocker.com/serpApi",
    params={"keyword": "best running shoes"},
    headers={"x-scrapeunblocker-key": "YOUR_API_KEY"},
    timeout=120,
)
data = r.json()

const res = await fetch(
  "https://api.scrapeunblocker.com/serpApi?keyword=best%20running%20shoes",
  {
    method: "POST",
    headers: { "x-scrapeunblocker-key": "YOUR_API_KEY" },
  }
);
const data = await res.json();

Response shape

{
  "keyword": "best running shoes",
  "proxyCountry": "us",
  "totalResults": 458000000,
  "topAdsCount": 1,
  "bottomAdsCount": 0,
  "organicResultsCount": 1,
  "resultsCollected": 1,
  "pagesFetched": 1,
  "topAds": [
    {
      "title": "Nike Run Club - Free Shipping",
      "url": "https://www.nike.com/...",
      "displayedUrl": "nike.com",
      "description": "Shop the latest running shoes...",
      "position": 1
    }
  ],
  "bottomAds": [ ... ],
  "organic": [
    {
      "title": "10 Best Running Shoes of 2026",
      "url": "https://runnersworld.com/...",
      "displayedUrl": "runnersworld.com",
      "description": "Our experts tested...",
      "position": 1
    }
  ],
  "aiOverview": {
    "text": "Running shoes are generally chosen by gait, cushioning and...",
    "markdown": "Running shoes are generally chosen by gait, cushioning and...",
    "sources": ["runnersworld.com", "reddit.com"],
    "references": [ ... ]
  }
}

Every response carries keyword, proxyCountry, totalResults, the count fields (topAdsCount, bottomAdsCount, organicResultsCount, resultsCollected), pagesFetched (how many result pages were rendered - this is how many API requests the call was billed, see pages_to_check), the three result lists (topAds, bottomAds, organic) and aiOverview. On a country fallback it also carries requestedCountry and note (see proxy_country below).

`aiOverview`

Google’s AI-written summary above the results, or null when the search does not have one. Whether Google generates an overview depends on the query and the region, so treat this as an extra rather than a guarantee - a commercial query usually has none, an informational one usually does.

Field	Notes
`text`	The overview as plain text, one paragraph, heading or list item per line.
`markdown`	The same overview as Markdown: headings, nested lists, and formulas written as LaTeX ( $...$ ), ready to display or to pass to an LLM.
`sources`	The hostnames the overview cites, e.g. `energysage.com`. Google’s own sites, such as YouTube, are left out.
`references`	The pages the overview cites: `title`, `url`, `source` (the site’s name), `domain` and `snippet`. `url` is the real page URL, or `null` when Google exposes no address for that page. A cited URL that cannot be tied to one of the cards is listed on its own, with `title` and `snippet` `null`.

A real example, trimmed, for keyword=how do solar panels work:

{
  "aiOverview": {
    "text": "Solar panels convert sunlight into usable electricity through a process called the photovoltaic effect, using semiconductor materials inside individual solar cells.\nStep-by-Step How Solar Panels Work\nAbsorbing Photons: Sunlight ...",
    "markdown": "Solar panels convert sunlight into usable electricity through a process called the photovoltaic effect, using semiconductor materials inside individual solar cells.\n\n### Step-by-Step How Solar Panels Work\n\n- Absorbing Photons: Sunlight is made of tiny packets of energy called photons. When photons strike a Solar panel, they are absorbed by the solar cells.\n- Creating an Electric Field: Most solar cells are made of silicon treated with two different layers: an N-doped layer (with extra electrons) and a P-doped layer (with \"holes\" for electrons), creating a PN junction. This junction forms an internal electric field.\n...",
    "sources": [
      "energysage.com",
      "renewableenergyhub.co.uk",
      "maxeon.com",
      "en.wikipedia.org",
      "reddit.com",
      "environmentamerica.org",
      "iberdrola.com"
    ],
    "references": [
      {
        "title": "How Do Solar Panels Work? Solar Power Explained | EnergySage",
        "url": "https://www.energysage.com/solar/solar-panels-work/",
        "source": "EnergySage",
        "domain": "energysage.com",
        "snippet": "Core Process: Solar panels utilize silicon solar cells to absorb photons from sunlight, generating direct current (DC) electricity..."
      },
      {
        "title": "How Do Solar Panels Work? A Simple Guide (With Facts for Kids)",
        "url": null,
        "source": "The Renewable Energy Hub",
        "domain": "renewableenergyhub.co.uk",
        "snippet": "Solar panels work by harnessing the energy from the sun and converting it into electricity through a process known as the photovol..."
      },
      {
        "title": null,
        "url": "https://www.renewableenergyhub.co.uk/main/solar-panels/how-do-solar-panels-work-for-kids",
        "source": "The Renewable Energy Hub",
        "domain": "renewableenergyhub.co.uk",
        "snippet": null
      }
    ]
  }
}

It is read from the page we already fetched and never waited for, so it costs you no extra time. In rare cases where the overview is still being written when the page is captured, the field is null.

topAds and bottomAds cover the paid units wherever Google puts them, including the blocks it now renders inside the organic column. Anything paid is in one of those two lists and never in organic.

Useful parameters

`pages_to_check`

How many SERP pages to scrape, 1 to 10. Defaults to 1.

curl -X POST "https://api.scrapeunblocker.com/serpApi?keyword=running+shoes&pages_to_check=3" \
  -H "x-scrapeunblocker-key: YOUR_API_KEY"

Results from all pages are concatenated into topAds, bottomAds, and organic with position reflecting cross-page ordering. Billing: each result page rendered is charged as one API request - a pages_to_check=3 call that returns three pages counts as 3 requests, not 1. The pagesFetched field in the response tells you exactly how many were charged (it can be lower than pages_to_check when Google has fewer pages). /getPageSource and /getImage bill a flat 1 per request; plugins that page through results count pages the same way as /serpApi, and each plugin page says how its calls are counted.

`proxy_country`

Two-letter ISO code forcing the request through that country’s IP pool. Affects what Google shows you - SERP composition varies by region.

curl -X POST "https://api.scrapeunblocker.com/serpApi?keyword=pizza&proxy_country=de" \
  -H "x-scrapeunblocker-key: YOUR_API_KEY"

Available countries (ISO2): BE, CA, CH, CN, DE, DK, ES, FR, GB, HK, HR, IE, IT, JP, KR, LT, NL, NO, PL, RO, SE, SG, TW, US. Country fallback. If you request a country we do not have an exit for, the request does not error. The results are served from an available exit, and the JSON response carries two extra fields so you know it happened:

Field	Type	Meaning
`requestedCountry`	string	The ISO2 country you asked for.
`note`	string	Human-readable explanation of the fallback.

{
  "keyword": "pizza",
  "proxyCountry": "de",
  "requestedCountry": "il",
  "note": "Country 'IL' is not available. Results were served from 'DE'. Available countries: BE, CA, CH, CN, DE, DK, ES, FR, GB, HK, HR, IE, IT, JP, KR, LT, NL, NO, PL, RO, SE, SG, TW, US.",
  "organic": [ ... ]
}

requestedCountry and note appear only on a country fallback. On a normal request where your proxy_country is available, neither field is present and proxyCountry echoes the country you asked for.

`wait_after_load`

Extra seconds to wait before extraction, on top of the wait we already do. You should not normally need it: extraction waits for the paid units to finish arriving before reading the page, so ads are not missed because of timing. Reach for this only when you have a specific reason to let a SERP settle longer - it is added to your response time as-is.

curl -X POST "https://api.scrapeunblocker.com/serpApi?keyword=insurance&wait_after_load=3" \
  -H "x-scrapeunblocker-key: YOUR_API_KEY"

`captcha_pause`

Seconds to pause if Google shows a CAPTCHA, giving an interactive user time to solve it. Only useful when running the API in attended mode. Leave at 0 for automated workloads - rely on proxy_country rotation instead.

Errors

Code	Meaning
`403`	Google CAPTCHA after retries on multiple proxies. Try a different `proxy_country` or wait.
`502`	Zero results with no “no results” notice on the page, on two separate fetches - an upstream block, not an empty search. Retry.
`504`	SERP fetch timed out. Lower `pages_to_check` or retry.
`422`	Missing `keyword` or invalid parameter range

A keyword Google genuinely has no results for is not an error: you get 200 with resultsCollected: 0 and an empty organic array. This is normal for narrow site: queries, and it means you can trust an empty result set instead of retrying it.

Tips

Phrase keywords like a user would. keyword=best+pizza+nyc performs differently from keyword=best%20pizza%20nyc%202026. Use spaces or +, not commas.
Watch totalResults for sanity. A totalResults of 0 with valid organic results means the count couldn’t be extracted - not that there are no results.
Cross-page dedup is your job. If you call with pages_to_check=10, expect some overlap on borderline results. Dedup on url.

Get Started

No-code area

Spider Cloud

Plugins

AI Assistants

Guides

Code Examples

Google SERP scraping

Minimum request

Response shape

`aiOverview`

Useful parameters

`pages_to_check`

`proxy_country`

`wait_after_load`

`captcha_pause`

Errors

Tips

​Minimum request

​Response shape

​aiOverview

​Useful parameters

​pages_to_check

​proxy_country

​wait_after_load

​captcha_pause

​Errors

​Tips

Minimum request

Response shape

`aiOverview`

Useful parameters

`pages_to_check`

`proxy_country`

`wait_after_load`

`captcha_pause`

Errors

Tips