SERP API

Endpoint

POST https://data.semust.com/v1/serp

Authentication

All requests require authentication headers. See Authentication for details.

Header	Type	Description
`SEMUST-API-USER`	string	Your API username
`SEMUST-API-PASSWORD`	string	Your API password

Request Parameters

Send parameters as JSON in the request body with Content-Type: application/json.

Parameter	Type	Required	Default	Description
`keyword`	string	Yes	—	The search keyword to fetch results for
`language`	string	No	`"en"`	Language code (e.g., “en”, “es”, “fr”)
`country`	string	No	`"US"`	Country code (e.g., “US”, “GB”, “DE”)
`format`	string	No	`"json"`	Response format: “json” or “raw”
`mobile`	boolean	No	`false`	Whether to fetch mobile results
`start_page`	integer	No	`1`	Starting page number (1-indexed)
`end_page`	integer	No	`1`	Ending page number for multi-page requests

Pagination: Each page from start_page to end_page counts as a separate credit charge. Requesting pages 1-3 costs 3x the base credit cost.

Code Examples

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 results, use start_page and end_page parameters. The response will be an array of result objects, one per page.

Python

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']}")

Credits: Each page counts as a separate credit charge. Requesting pages 1-3 will use 3 credits.

Response Format

JSON Format (`format: "json"`)

Returns structured data with organic results, knowledge panels, and other SERP elements.

Raw Format (`format: "raw"`)

Returns the raw HTML of the search results page. Useful for custom parsing or debugging.

Example Response

Single Page Response

{
  "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": []
}

Multi-Page Response

[
  {
    "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

Not all fields are present in every response. Fields are included only when data is available.

Field	Type	Description
`organic`	array	Main organic search results
`knowledge`	object	Knowledge panel information (Wikipedia-like data)
`people_also_ask`	array	”People also ask” questions with answers
`related`	array	Related searches at bottom of SERP
`navigation`	array	Search type tabs (Images, Videos, News, etc.)
`perspectives`	array	Social media and forum perspectives
`ai_overview`	object	AI-generated overview (Google AI Overviews)
`images`	array	Image carousel results
`top_ads`	array	Sponsored results at top of page
`bottom_ads`	array	Sponsored results at bottom of page
`overview`	object	Knowledge graph metadata (kgmid, title)

Organic Result Fields

Field	Type	Description
`rank`	integer	Position within organic results (1-indexed)
`global_rank`	integer	Position across all SERP elements
`title`	string	Result title
`description`	string	Result snippet/description
`link`	string	Destination URL
`display_link`	string	Formatted URL as displayed in SERP
`source`	string	Website or source name
`extensions`	array	Site links, dates, and other extensions
`image`	string	Thumbnail URL (for video results)
`duration`	string	Video duration (e.g., “19:10”)
`duration_sec`	integer	Video duration in seconds

Error Codes

Error Response

{
  "error": "Your account does not have enough credits",
  "code": "INSUFFICIENT_CREDITS"
}

Status	Code	Description
400	`INVALID_REQUEST`	Invalid request format or malformed JSON
400	`KEYWORD_REQUIRED`	Missing required keyword parameter
400	`INVALID_FORMAT`	Format must be “json” or “raw”
401	`INVALID_API_KEY`	Authentication failed - invalid credentials
402	`INSUFFICIENT_CREDITS`	Your account does not have enough credits
429	`RATE_LIMIT_EXCEEDED`	Too many requests, please slow down
500	`INTERNAL_ERROR`	Server-side error occurred
502	`SERP_FAILED`	Failed to retrieve SERP data
504	`TIMEOUT`	Request timed out

Credits & Rate Limits

Credits

Each SERP request consumes credits from your account balance. Multi-page requests consume one credit per page.

Rate Limits

API requests are rate-limited to ensure fair usage. Contact support if you need higher limits.

Getting Started

API Reference

Endpoint

Authentication

Request Parameters

Code Examples

Multi-Page Requests

Response Format

JSON Format (`format: "json"`)

Raw Format (`format: "raw"`)

Example Response

Single Page Response

Multi-Page Response

Response Fields Reference

Root-Level Fields

Organic Result Fields

Error Codes

Credits & Rate Limits

Credits

Rate Limits

Getting Started

API Reference

​Endpoint

​Authentication

​Request Parameters

​Code Examples

​Multi-Page Requests

​Response Format

​JSON Format (format: "json")

​Raw Format (format: "raw")

​Example Response

​Single Page Response

​Multi-Page Response

​Response Fields Reference

​Root-Level Fields

​Organic Result Fields

​Error Codes

​Credits & Rate Limits

Credits

Rate Limits

Endpoint

Authentication

Request Parameters

Code Examples

Multi-Page Requests

Response Format

JSON Format (`format: "json"`)

Raw Format (`format: "raw"`)

Example Response

Single Page Response

Multi-Page Response

Response Fields Reference

Root-Level Fields

Organic Result Fields

Error Codes

Credits & Rate Limits