Skip to content

About

Google SERP API: scrape Google search results (organic, People Also Ask, AI Overviews, ads, knowledge panel) as structured JSON in any country and language. Python, Node.js, Go, PHP and cURL examples.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

Google SERP API

Semust Google SERP API: Google search results as JSON

Get API key Documentation MCP server License: MIT

The Semust Google SERP API returns Google search results as clean, structured JSON: organic results, People Also Ask, AI Overviews, the knowledge panel, related searches, image carousels and ads. Send a keyword, a country and a language, and get the results page exactly as a searcher there would see it, on desktop or mobile. No proxies, CAPTCHAs or HTML parsing on your side.

It is built for SEO teams and developers who need rank tracking, SERP feature monitoring, competitor research and grounding data for AI agents. The API is part of the Semust SEO platform.

How it works

Your code sends POST /v1/serp to Semust and receives Google results as JSON. Long requests return 202 and are collected from /v1/tasks.

1. Get your API credentials

Create an API user on the Semust API access page. You get a username and a password. Every request sends them as two headers:

Header Value
SEMUST-API-USER Your API username
SEMUST-API-PASSWORD Your API password

The examples in this repository read them from environment variables, so they never end up in your code:

export SEMUST_API_USER="your_username"
export SEMUST_API_PASSWORD="your_password"

Tip

There is no subscription. You top up a prepaid balance and pay only for successful requests; failed requests are refunded automatically. Prices are on the Google SERP API page.

2. Send a request

import os, time, requests

HEADERS = {
    "SEMUST-API-USER": os.environ["SEMUST_API_USER"],
    "SEMUST-API-PASSWORD": os.environ["SEMUST_API_PASSWORD"],
}

resp = requests.post(
    "https://data.semust.com/v1/serp",
    params={"wait": 60},
    headers=HEADERS,
    json={"keyword": "best seo tools", "country": "US", "language": "en"},
    timeout=90,
)
while resp.status_code == 202:  # still running: poll the task
    time.sleep(int(resp.headers.get("Retry-After", 5)))
    resp = requests.get(resp.json()["poll_url"], headers=HEADERS, timeout=30)

for result in resp.json().get("organic", []):
    print(result["rank"], result["title"], result["link"])

3. Run the examples

Language File Run
Python examples/python/serp.py python serp.py "best seo tools"
Python, rank checker examples/python/rank_check.py python rank_check.py example.com "seo tools" "serp api"
Node.js 18+ examples/node/serp.mjs node serp.mjs "best seo tools"
Go examples/go/main.go go run . "best seo tools"
PHP examples/php/serp.php php serp.php "best seo tools"
cURL examples/curl/serp.sh ./serp.sh

Request parameters

POST https://data.semust.com/v1/serp with a JSON body:

Parameter Type Default Description
keyword (required) string – The search query, exactly as a user would type it.
country string US Results country, ISO 3166-1 alpha-2 (US, GB, DE, TR, …).
language string en Interface language, ISO 639-1 (en, de, tr, …).
mobile boolean false true returns mobile results instead of desktop. Same price.
format string json json for parsed results, raw for the results page HTML.
start_page integer 1 First results page to return, 1–10.
end_page integer 1 Last results page to return, 1–10 and ≥ start_page. Results from every page are merged into one organic array.
Query parameter Default Description
wait 60 Seconds to hold the connection before answering 202, 0–80. 0 answers 202 at once (fire and collect).
Header Description
Idempotency-Key Optional, up to 128 characters. Repeating a request with the same key returns the same task and is charged once.

Output sample

Parsed Google results for "best seo tools" returned by the Semust SERP API

A shortened response for {"keyword": "best seo tools", "country": "US", "language": "en"}. Lists are cut to two items; the complete response is in output-google-serp-scraper.json.

{
  "ai_overview": {
    "markdown": "The \"best\" SEO tool `depends on your specific goal, budget, and whether you need an all-in-one suite or a specialized utility`.[[1]](https://google.com/goto?...",
    "references": [
      {
        "link": "https://www.reddit.com/r/SEO/comments/1269zj7/whats_the_best_seo_tools_right_now_in_the_market/",
        "source": "Reddit",
        "text": "Specialized SEO Tools: Beyond comprehensive suites, several tools are highly recommended for specific SEO tasks. Surfer SEO is valued for on-page optimizatio...",
        "title": "What's the best SEO tools right now in the market? - Reddit"
      },
      {
        "link": "https://zapier.com/blog/best-seo-tools/",
        "source": "Zapier",
        "text": "Instead, I focused on products that could fit into one of four distinct SEO product categories. * SEO audit tools: These tools are designed primarily to perf...",
        "title": "The 11 Best SEO Tools in 2026 | Zapier"
      }
    ],
    "texts": [
      "The \"best\" SEO tool depends on your specific goal, budget, and whether you need an all-in-one suite or a specialized utility.",
      "Semrush: Widely considered the top all-around choice for comprehensive SEO, competitor analysis, keyword research, and modern AI-visibility/search tracking. ..."
    ]
  },
  "organic": [
    {
      "description": "Feb 24, 2026 — Best SEO Tools in 2026: Our Detailed List · 1. Semrush · 2. SE Ranking · 3. Ahrefs · 4. Moz Pro · 5. Mangools · 6. Majestic · 7. Screaming Fro...",
      "display_link": "https://www.01net.com › seo › tools",
      "extensions": [
        {
          "description": null,
          "link": "https://google.com/goto?url=CAESvwIBxCJF1-nqPhTSoHMpRhl-9-G-rNCsgaTgLxoDkxW9L6_VG7mGa_i9MbFmBOa-_pwvbcwM3pMdNGy47vX6qZcWq8b1XCWVubePVWvgVNlUUlPkjPx5cvaMkYD4B...",
          "text": "Read more",
          "type": "site_link"
        }
      ],
      "global_rank": 2,
      "link": "https://google.com/goto?url=CAESYAHEIkXXVRE5gKzYwYDm0us8F3ByD8GeQayX-_upQodLutQmdPUIkkcM12QU-4ljnS7swkjOPU9W6O9-Jhb50Hs4eW-sLLgAvvuHg-eGz-RdVNvYPhuI1MaauAViz...",
      "rank": 1,
      "source": "01net.com",
      "title": "The 10 Best SEO Tools to Use in 2026 [All Tested]"
    },
    {
      "description": "May 19, 2025 — Our list of the best SEO tools for keyword research, backlink analysis, on-page SEO, site audits and more.",
      "display_link": "https://www.stylefactoryproductions.com › blog › best-...",
      "global_rank": 3,
      "link": "https://google.com/goto?url=CAESeAHEIkXXeYGOmh8L3McEdB88nyaA1uP9ErzKnOqQ23ewW9g6K4YntVhqF-E4tWmsKhHI5jmoVH-mQCaJGbpPyh6CnrjyMrdQhO68u_fvOoiP_QOQoCtp-9VPQXBjO...",
      "rank": 2,
      "source": "stylefactoryproductions.com",
      "title": "Best SEO Tools (2025) — 10 Tools You Must Consider"
    }
  ],
  "people_also_ask": [
    {
      "answer_source": "",
      "answers": [],
      "global_rank": 5,
      "question": "Is SEO dead or evolving in 2026?",
      "rank": 1
    },
    {
      "answer_source": "",
      "answers": [],
      "global_rank": 6,
      "question": "Is SEO paid or free?",
      "rank": 2
    }
  ],
  "related": [
    {
      "global_rank": 12,
      "link": "https://www.google.com/search?q=Best+seo+tools+free",
      "rank": 1,
      "text": "Best seo tools free"
    },
    {
      "global_rank": 13,
      "link": "https://www.google.com/search?q=Top+10+best+seo+tools",
      "rank": 2,
      "text": "Top 10 best seo tools"
    }
  ]
}

Fields only appear when Google shows that element for the query: a query with no AI Overview has no ai_overview key.

JSON output structure

Top-level fields

Field Type Description
organic array Organic results, in order. With end_page > 1 this holds every requested page.
people_also_ask array "People also ask" questions and their answers.
ai_overview object Google's AI Overview: the answer as markdown, its texts blocks and the references it cites.
knowledge object Knowledge panel: name, subtitle, description, facts.
related array Related searches at the bottom of the page.
images array Image carousel results.
top_ads, bottom_ads array Sponsored results above and below the organic results.
perspectives array Forum, social and video perspectives.
navigation array Search tabs (Images, News, Videos, …).
overview object Knowledge Graph metadata such as kgmid.

Organic result

Field Type Description
rank integer Position among organic results, starting at 1.
global_rank integer Position among all elements on the page, including PAA, ads and carousels.
title string Result title.
description string Snippet text.
link string Destination URL.
display_link string The URL breadcrumb as Google shows it.
source string Site name.
extensions array Sitelinks, dates and other rich-result extras.
image, duration, duration_sec Thumbnail and length, for video results.

People also ask item

Field Type Description
rank, global_rank integer Position in the PAA box and on the page.
question string The question.
answers array The expanded answer blocks.
answer_source string Where the answer comes from.

Long-running requests (202 and polling)

Most requests finish in a few seconds and return 200 with the result. If a request is still running after wait seconds (60 by default, maximum 80), the API returns 202 Accepted with a task_id instead. Nothing is lost and you are not charged twice:

  1. Read task_id from the body (also in the X-Task-Id header).
  2. Wait Retry-After seconds.
  3. Call GET https://data.semust.com/v1/tasks/{task_id} with the same headers until the status is no longer 202. The final answer is exactly what the original request would have returned.

Every example in examples/ already handles this. Results stay available for 72 hours, and fetching them again is free. Set your HTTP client's read timeout above wait (for example wait + 30 seconds). Send an Idempotency-Key header to retry a request safely without paying twice. Details: Tasks & long-running requests.

Errors

Errors return JSON with a readable error and a stable code. Failed requests are not charged.

HTTP code Meaning
200 EMPTY_SERP Google returned no results for this query. The body has error and code instead of organic.
400 INVALID_REQUEST, KEYWORD_REQUIRED, INVALID_FORMAT The body is malformed, keyword is missing, or format is not json/raw.
401 MISSING_CREDENTIALS, INVALID_CREDENTIALS, CREDENTIALS_EXPIRED Check the two auth headers.
402 INSUFFICIENT_CREDITS Top up your balance.
403 IP_NOT_WHITELISTED Your API user only accepts requests from listed IP addresses.
429 RATE_LIMIT_EXCEEDED Slow down; the default limit is 60 requests per minute.
503 SERP_FAILED, TIMEOUT Temporary failure. Retry with the same Idempotency-Key.

Pricing

$0.0017 per results page, desktop or mobile. Pages are counted from 1 to end_page, because Google results are always fetched from the top: start_page: 3, end_page: 3 costs the same as pages 1–3. Failed requests are refunded automatically. Current prices are on the SERP API page.

Use cases

  1. Rank tracking. Check where your pages rank for each keyword, in every country and on mobile and desktop. Start from rank_check.py.
  2. SERP feature monitoring. Track which queries show AI Overviews, People Also Ask, video or image carousels, and whether your site is cited in them.
  3. Competitor research. See who ranks for your money keywords, and how titles and snippets are written.
  4. Content briefs. Collect PAA questions and related searches to plan headings and FAQs that match search intent.
  5. AI agents and LLM grounding. Give an agent fresh, structured Google results instead of a scraped page.

Why Semust

  • Pay as you go. No monthly plan or minimum commitment for the API. Top up once, pay per successful request, and get failed requests refunded automatically.
  • One account, every SEO dataset. SERP, keyword data, backlinks, domain research, YouTube, Google Trends, Lighthouse and Google Business data use the same credentials, the same error format and the same task system.
  • Any country, any language. Localised results for every Google market, including strong coverage of Türkiye and Turkish-language queries.
  • Built for AI workflows. Plug the same data into Claude, Cursor or ChatGPT with the open-source Semust MCP server.

FAQ

Is scraping Google search results legal?

Search results are publicly available, and collecting public data is generally lawful in many jurisdictions. Laws differ by country, and how you store and use the data matters. Check the rules that apply to you, or ask a lawyer. This is not legal advice.

How many results does one request return?

One results page, usually around 10 organic results plus every other element on the page. Set end_page (up to 10) to collect deeper results in one call.

Can I get results for a specific country, language or device?

Yes. Set country and language to any Google market, and mobile: true for mobile results.

Does it return Google AI Overviews?

Yes. When Google shows an AI Overview for the query, the response has an ai_overview object with its text and the sources it cites.

Can I get the raw HTML?

Yes. Send "format": "raw" and the response is the results page HTML.

Can I use it from Claude, ChatGPT or Cursor?

Yes. The Semust MCP server connects your Semust account to AI assistants, and the Rank Tracker MCP lets them read your tracked rankings.

Learn more

Related repositories

SEO data APIs

Repository What it does Product page
google-images-scraper Google Images results with titles, source pages and image URLs Google Images API
youtube-scraper YouTube search, video details, transcripts and comments YouTube API
google-trends-scraper Interest over time, regions, related queries and demographics Google Trends API
google-business-scraper Google Business profiles, local search and reviews Google Business Data API
keyword-research-api Search volume, CPC, competition, intent and related keywords Keyword Research API
backlinks-api Backlinks, referring domains, anchors and link history Backlinks API
domain-research-api Organic keywords, competitors, top pages and keyword gaps for any domain Domain Research API
technical-seo-api 27 technical SEO checks for any URL in one call Technical SEO API
lighthouse-on-page-api Lighthouse scores, on-page audits and page content extraction Lighthouse & On-Page API

MCP servers for AI assistants

Repository What it does Product page
semust-mcp One MCP server for Search Console, GA4, Google Ads, rank tracking and social posting Semust MCP Server
seo-mcp Search Console, rank tracking, indexing and competitor tools for AI assistants SEO MCP
google-search-console-mcp Ask your AI assistant about clicks, queries and pages Google Search Console MCP
google-analytics-mcp GA4 traffic, channels and conversions in your AI assistant Google Analytics MCP
google-ads-mcp Campaigns, search terms and spend in your AI assistant Google Ads MCP
rank-tracker-mcp Keyword rankings and AI-search visibility for AI assistants Rank Tracker MCP
web-analytics-mcp Privacy-friendly first-party analytics in your AI assistant Web Analytics MCP
bing-webmaster-mcp Bing queries, pages, links and crawl issues Bing Webmaster MCP
yandex-metrica-mcp Yandex Metrica traffic and search phrases Yandex Metrica MCP
social-media-mcp Draft and schedule LinkedIn, Facebook and Instagram posts Social Media MCP

Support

Found a problem with an example? Open an issue.

License

The code examples in this repository are released under the MIT License. Use of the Semust API is subject to the Semust Terms of Service.

About

Google SERP API: scrape Google search results (organic, People Also Ask, AI Overviews, ads, knowledge panel) as structured JSON in any country and language. Python, Node.js, Go, PHP and cURL examples.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors