semust logo

API Platform

SERP API

Retrieve Google search results in structured JSON or raw HTML format.

Retrieve Google search results in structured JSON or raw HTML format. Supports multi-page queries, mobile/desktop results, and localized searches by language and country.

Product page: SERP API.

Authentication

All requests require header-based authentication. Include your API credentials in every request.

HeaderTypeDescription
SEMUST-API-USERstringYour API user's username
SEMUST-API-PASSWORDstringYour API user's password

Create API credentials from the API Access page.

SEMUST-API-USER: your_username
SEMUST-API-PASSWORD: your_password

Request Parameters

Send a application/json body with the following parameters:

Body

keywordstringrequired

The search query to look up on Google.

languagestringdefault: en

Language code (ISO 639-1). Controls the language of search results. Examples: "en", "tr", "de", "fr", "es".

countrystringdefault: US

Country code (ISO 3166-1 alpha-2). Geo-targets search results to a specific country. Examples: "US", "TR", "DE", "GB".

formatstringdefault: json

Response format. "json" returns parsed structured data. "raw" returns the full HTML of the search results page.

mobilebooleandefault: false

When true, returns mobile search results instead of desktop.

start_pageintegerdefault: 1

First page of results to fetch. Must be between 1 and 10.

end_pageintegerdefault: 1

Last page of results to fetch. Must be between 1 and 10, and >= start_page.

Pagination:

Both start_page and end_page must be between 1 and 10. end_page must be >= start_page. Multi-page requests return an array.

{
  "keyword": "best seo tools",
  "language": "en",
  "country": "US",
  "format": "json",
  "mobile": false,
  "start_page": 1,
  "end_page": 1
}

Code Examples

Complete examples showing how to call the SERP API in different languages.

curl -X POST https://data.semust.com/v1/serp \
  -H "Content-Type: application/json" \
  -H "SEMUST-API-USER: your_username" \
  -H "SEMUST-API-PASSWORD: your_password" \
  -d '{
    "keyword": "best seo tools",
    "language": "en",
    "country": "US",
    "format": "json"
  }'

Multi-Page Requests

To fetch multiple pages of search results, set start_page and end_page.

The response will be an array of result objects, one per page. Each object contains the same fields as a single-page response (organic, knowledge_graph, …).

Credits

Each page in a paginated request is charged at the base cost. For example, requesting 3 pages (start_page: 1, end_page: 3) will consume 3x the base credit cost.

import requests

response = requests.post(
    "https://data.semust.com/v1/serp",
    headers={
        "SEMUST-API-USER": "your_username",
        "SEMUST-API-PASSWORD": "your_password",
    },
    json={
        "keyword": "best seo tools",
        "format": "json",
        "start_page": 1,
        "end_page": 3,
    },
)

pages = response.json()
for i, page in enumerate(pages, start=1):
    print(f"--- Page {i} ---")
    for result in page.get("organic", []):
        print(f"  {result['rank']}. {result['title']}")
        print(f"     URL: {result['link']}")
        print(f"     Source: {result.get('source', 'N/A')}")

Response

JSON Format

Returns parsed search result data. Single-page requests return an object, multi-page requests return an array.

Internal metadata fields (general, url, pagination, input) are automatically removed.

Raw Format

Returns the raw HTML content of the search results page as text/html.

{
  "organic": [
    {
      "rank": 1,
      "global_rank": 1,
      "title": "10 Best SEO Tools in 2025",
      "description": "Discover the top SEO tools for improving your website rankings...",
      "link": "https://example.com/best-seo-tools",
      "display_link": "https://example.com › best-seo-tools",
      "source": "Example.com",
      "extensions": [
        {
          "type": "site_link",
          "text": "Free Tools",
          "link": "https://example.com/free-tools",
          "rank": 1
        }
      ]
    },
    {
      "rank": 2,
      "global_rank": 6,
      "title": "SEO Software & Tools",
      "description": "Get more search traffic with our comprehensive SEO toolkit...",
      "link": "https://www.example.com",
      "display_link": "https://www.example.com",
      "source": "Example"
    }
  ],
  "knowledge": {
    "name": "SEO",
    "subtitle": "Search engine optimization",
    "description": "Search engine optimization is the process of...",
    "description_source": "Wikipedia",
    "facts": [{ "key": "Full name", "value": [{ "text": "Search Engine Optimization" }] }]
  },
  "people_also_ask": [
    {
      "rank": 1,
      "global_rank": 2,
      "question": "What is SEO?",
      "answer_source": "Wikipedia",
      "answers": [{ "rank": 1, "type": "answer", "value": { "text": "SEO is..." } }]
    }
  ],
  "related": [
    { "rank": 1, "global_rank": 10, "text": "SEO tools free", "link": "https://..." }
  ],
  "navigation": [{ "title": "Images", "href": "https://..." }],
  "perspectives": [{ "title": "SEO Tips", "author": "Expert", "source": "YouTube" }],
  "ai_overview": { "references": [...], "texts": [...] },
  "images": [{ "rank": 1, "title": "SEO Diagram", "link": "https://...", "image": "https://..." }],
  "top_ads": [{ "rank": 1, "title": "SEO Tool", "link": "https://...", "referral_link": "https://..." }],
  "bottom_ads": [...]
}
[
  {
    "organic": [
      { "rank": 1, "global_rank": 1, "title": "Result 1", "link": "https://...", "source": "..." }
    ],
    "knowledge": { "name": "...", "description": "..." },
    "people_also_ask": [{ "rank": 1, "question": "...", "answers": [...] }],
    "navigation": [{ "title": "Images", "href": "https://..." }]
  },
  {
    "organic": [
      { "rank": 1, "global_rank": 11, "title": "Page 2 Result", "link": "https://...", "source": "..." }
    ],
    "related": [{ "rank": 1, "text": "Related search", "link": "https://..." }]
  }
]

Response Fields Reference

Root-Level Fields

The response contains multiple SERP elements. Not all fields are present in every response.

FieldTypeDescription
organicarrayMain organic search results
knowledgeobjectKnowledge panel information (Wikipedia-like data)
people_also_askarray"People also ask" questions with answers
relatedarrayRelated searches at bottom of SERP
navigationarraySearch type tabs (Images, Videos, News, etc.)
perspectivesarraySocial media and forum perspectives
ai_overviewobjectAI-generated overview (Google AI Overviews)
imagesarrayImage carousel results
top_adsarraySponsored results at top of page
bottom_adsarraySponsored results at bottom of page
overviewobjectKnowledge graph metadata (kgmid, title)

Organic Result Fields

FieldTypeDescription
rankintegerPosition within organic results (1-indexed)
global_rankintegerPosition across all SERP elements
titlestringResult title
descriptionstringResult snippet/description
linkstringDestination URL
display_linkstringFormatted URL as displayed in SERP
sourcestringWebsite or source name
extensionsarraySite links, dates, and other extensions
imagestringThumbnail URL (for video results)
durationstringVideo duration (e.g., "19:10")
duration_secintegerVideo duration in seconds

Error Codes

All errors return a JSON object with a human-readable message and an error code.

HTTPCodeMeaning
400INVALID_REQUESTRequest body is malformed or missing required fields
400KEYWORD_REQUIREDThe keyword field is empty or missing
400INVALID_FORMATThe format field is not "json" or "raw"
401INVALID_API_KEYAuthentication failed — invalid username or password
402INSUFFICIENT_CREDITSYour account does not have enough credits
429RATE_LIMIT_EXCEEDEDToo many requests — rate limit exceeded
500INTERNAL_ERRORAn internal server error occurred
502SERP_FAILEDFailed to fetch search results
504TIMEOUTThe request timed out (max 10 minutes)
{
  "error": "Your account does not have enough credits",
  "code": "INSUFFICIENT_CREDITS"
}

Credits & Rate Limits

Credits

Each request consumes credits from your balance. Cost may vary based on the mobile parameter. If your balance is insufficient, the API returns HTTP 402.

Rate Limits

Requests are subject to per-minute and per-day limits based on your plan. Exceeding limits returns HTTP 429.

Last updated: 2026-08-22