API
API / Data API / SERP

SERP

You are reading the Data API docs

Base URL: api.seranking.com

Data API and Project API keys are not interchangeable — use the correct one to avoid authentication errors.

Data apikey example:
80cfee7d-xxxx-xxxx-xxxx-fc8500816bb3
(UUID format)
Project apikey example:
253a73adxxxxxxxxxxxxxx340aa0a939
(40-char hex)
API dashboard

API keys are available in your account. For any questions or 401 errors, email [email protected] for support.

The following limits apply to the SERP API:
  • up to 600 SERP tasks can run in parallel
  • up to 10 keywords per task can be submitted
  • up to 10 tasks per second can be created
Contact [email protected] to discuss your volume needs and custom limits.

SERP API provides programmatic access to Google search engine results pages (SERPs) for specified keywords.

Using the API, you can:

  • Submit SERP collection tasks for one or more keywords across specific locations, languages, and devices
  • Retrieve standard SERP results, including organic results, ads, and featured snippets
  • Retrieve advanced SERP results with full SERP items and features
  • Download raw HTML dumps of Google search results pages
  • List recent SERP tasks created within the last 24 hours
  • Retrieve available search locations

Add SERP tasks

POST https://api.seranking.com/v1/serp/classic/tasks
Cost: 10 credits per keyword

Adds one or more search queries to the queue for SERP collection. Each task later returns SERP results for the specified keywords, including URLs, snippets, and positions, which can be retrieved using the Get standard SERP results or Get advanced SERP results endpoints below.

Note: Supports Google search results only. Bing and Yahoo! are in development — contact [email protected] for release updates.

Request parameters

Note: Up to 600 SERP tasks can run in parallel. Requests exceeding this limit will return a processing_limit_exceeded error.
ParameterTypeRequiredDefaultDescription
search_engineStringYesN/ASearch engine name (currently only google is supported).
query[]Array of stringsYesN/AArray of keywords (≤ 255 chars each). Up to 10 keywords per task by default (higher limits are available for custom plans).

For example: ["avocado", "interstellar"].
deviceStringYesN/ASearch device type. Supported values: "desktop", "mobile".
language_codeStringYesN/ALanguage code (ISO 639-1, e.g., fr).
location_idIntegerYesN/ALocation identifier. You can retrieve available IDs using the Get locations endpoint.
tagStringNoN/AOptional tag for grouping tasks.

Request example

Copy
curl -X POST 'https://api.seranking.com/v1/serp/classic/tasks' \

  -H 'Authorization: Token YOUR_API_KEY' \

  --data '{

      "search_engine": "google",

      "device": "desktop",

      "language_code": "fr",

      "location_id": 31808,

      "query": [

          "seo report",

          "seo api"

      ],

      "tag": "test_tag"

  }'

Response parameters

If successful, the server returns an array of task objects, each representing a submitted query.

ParameterTypeDescription
idIntegerUnique ID assigned to each SERP collection task.
queryStringKeyword for the task.
location_idIntegerID of the location for the search results.
language_codeStringLanguage code for the search results.
is_completedBooleanIndicates whether the task is completed (true or false).
addedStringTimestamp when the task was added in YYYY-MM-DD HH:MM:SS format.

Response example

Copy
[

    {

        "id": 385103,

        "query": "seo report",

        "location_id": 31808,

        "language_code": "fr",

        "is_completed": false,

        "added": "2025-11-13 09:03:40"

    },

    {

        "id": 385106,

        "query": "seo api",

        "location_id": 31808,

        "language_code": "fr",

        "is_completed": false,

        "added": "2025-11-13 09:03:40"

    }

]

Get standard SERP results

GET https://api.seranking.com/v1/serp/classic/tasks
Cost: 0 credits

Retrieves the status or standard results of a SERP task previously added via the Add SERP tasks endpoint. If the SERP results have not yet been collected, the server returns a status object. Once the task is complete, the server returns a results array containing the top 100 SERP results. Results are stored for 24 hours and then deleted.

Note: This endpoint provides results for the following SERP item types only: organic, ads, and featured_snippet.

Request parameters

ParameterTypeRequiredDefaultDescription
task_idIntegerYesN/AUnique ID of the query task created using the Add SERP tasks method.

Request example

Copy
curl -X GET 'https://api.seranking.com/v1/serp/classic/tasks?task_id=14' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

  • If the task is still in progress:
ParameterTypeDescription
statusStringIndicates that the task is currently being processed: "processing".
  • If the task is complete:
ParameterTypeDescription
request_metadataObjectMetadata about the request.
request_metadata.keywordStringKeyword used in the search query.
request_metadata.deviceStringSearch device type.
request_metadata.location_idIntegerID of the location for the search results.
request_metadata.language_codeStringLanguage code for the search results.
request_metadata.tagStringCustom tag for the request (optional).
request_metadata.crawled_atStringTimestamp when the SERP was crawled.
request_metadata.serp_urlStringFull SERP URL.
summaryObjectSummary statistics for the search results.
summary.total_resultsIntegerTotal number of search results found.
summary.organic_items_countIntegerNumber of organic results on the page.
summary.SERP_featuresArrayList of all SERP features present (e.g., tads, video).
itemsArrayArray of search result objects.
items[].typeStringType of the SERP item. Possible values for this endpoint are:
– organic
– ads
– featured_snippet
items[].rank_absoluteIntegerAbsolute ranking of the item in the SERP.
items[].rank_groupIntegerRank within its group of similar items.
items[].positionStringPosition on the page (e.g., top, bottom).
items[].serp_featuresArrayList of SERP features associated with this result.
items[].domainStringDomain of the page (if available).
items[].urlStringURL of the page.
items[].titleStringTitle of the page as shown in the SERP.
items[].descriptionStringDescription snippet of the page (if available).
items[].breadcrumbStringBreadcrumb or main URL path of the page.
items[].highlighted_termsArrayTerms highlighted in the snippet matching the query.
items[].linksArrayArray of link objects.
items[].links[].urlStringURL of the link.
items[].links[].titleStringTitle of the link.
items[].displayUrlStringDisplayed URL of the result as shown in the SERP.

Response examples

  • If the task is still in progress:
Copy
{

    "status": "processing"

}
  • If the task is complete:
Copy
{

  "request_metadata": {

    "keyword": "seo report",

    "device": "desktop",

    "location_id": 31808,

    "language_code": "fr",

    "tag": "test_tag",

    "crawled_at": "2025-11-03 17:50:45",

    "serp_url": "https://www.google.com/search?q=seo+report&hl=fr&gl=FR&ie=UTF-8"

  },

  "summary": {

    "total_results": 1160000000,

    "organic_items_count": 99,

    "SERP_features": [

      "tads",

      "people_also_ask",

      "bads",

      "related_searches",

      "reviews",

      "video"

    ]

  },

  "items": [

    {

      "type": "organic",

      "rank_absolute": 1,

      "rank_group": 1,

      "serp_features": [

        "tads"

      ],

      "position": "top",

      "title": "SEO Report Tool - SE Ranking SEO Software",

      "links": [

        {

          "url": "https://seranking.com/easy-to-use.html",

          "title": "SEO Report Tool - SE Ranking SEO SoftwareSE Rankinghttps://www.seranking.com"

        }

      ],

      "displayUrl": "https://www.seranking.com"

    }

  ]

}

Get advanced SERP results

GET https://api.seranking.com/v1/serp/classic/tasks/results_advanced
Cost: 10 credits

Retrieves the full, detailed SERP results of a task previously added via the Add SERP tasks endpoint. This call returns summaries, SERP features, and detailed items (organic, videos, images, AI overviews, etc.). Results are stored for 24 hours and then deleted.

Note: Advanced results for mobile searches do not include AI overviews and therefore cost 0 credits.
  • If the SERP results have not yet been collected, the server returns a status object.
  • Once the task is complete, the server returns a results array containing the advanced results.

Request parameters

ParameterTypeRequiredDefaultDescription
task_idIntegerYesN/AUnique ID of the query task for which advanced results are requested.

Request example

Copy
curl -X GET 'https://api.seranking.com/v1/serp/classic/tasks/results_advanced?task_id=14' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

  • If the task is still in progress:
ParameterTypeDescription
statusStringIndicates that the task is currently being processed: "processing".
  • If the task is complete:
ParameterTypeDescription
request_metadataObjectMetadata about the request.
request_metadata.keywordStringKeyword submitted in the request. Example: "how to enjoy learning".
request_metadata.deviceStringSearch device type.
request_metadata.location_idIntegerID of the location for the search results.
request_metadata.language_codeStringLanguage code for the search results.
request_metadata.tagStringCustom tag for the request (optional).
request_metadata.crawled_atStringTimestamp when the SERP was crawled.
request_metadata.serp_urlStringFull SERP URL.
summary.total_resultsIntegerTotal number of search results found.
summary.organic_items_countIntegerNumber of organic results on the page.
summary.SERP_featuresArrayList of SERP features present (e.g., video, tads, etc.).
items[].typeStringType of the SERP item (e.g., organic).
items[].rank_absoluteIntegerAbsolute ranking of the item in the SERP.
items[].rank_groupIntegerRank within its group of similar items.
items[].positionStringPosition of the item on the SERP (e.g., top, bottom).
items[].serp_featuresArrayList of SERP features associated with this result.
items[].domainStringDomain of the page (if available).
items[].urlStringURL of the page.
items[].titleStringTitle of the page as shown in the SERP.
items[].descriptionStringDescription snippet of the page (if available).
items[].breadcrumbStringBreadcrumb or main URL path of the page.
items[].highlighted_termsArrayTerms highlighted in the snippet matching the query.
items[].linksArrayArray of link objects.
items[].links[].urlStringURL of the link.
items[].links[].titleStringTitle of the link.
items[].displayUrlStringDisplayed URL of the result as shown in the SERP.
items[].searchesArrayArray of related search queries (only present for related_searches items).

Response examples

  • If the task is still in progress:
Copy
{

    "status": "processing"

}
  • If the task is complete:
Copy
{

  "request_metadata": {

    "keyword": "seo report",

    "device": "desktop",

    "location_id": 31808,

    "language_code": "fr",

    "tag": "test_tag",

    "crawled_at": "2025-11-18 16:12:29",

    "serp_url": "https://www.google.com/search?q=seo+report&hl=fr&source=hp&gl=US&ie=UTF-8&sclient=gws-wiz&uule=w+CAIQIFISCcVu4B8B2MJQEVDYwwkSgdS5&pws=0"

  },

  "summary": {

    "total_results": 1520000000,

    "organic_items_count": 100,

    "SERP_features": [

      "people_also_ask",

      "bads",

      "related_searches",

      "reviews",

      "video"

    ]

  },

  "items": [

    {

      "type": "organic",

      "rank_absolute": 1,

      "rank_group": 1,

      "position": "center",

      "serp_features": [],

      "domain": "www.seoptimer.com",

      "url": "https://www.seoptimer.com/",

      "title": "SEOptimer: Analyze Websites With Free SEO Audit ...",

      "description": "SEOptimer is a free SEO Audit Tool that will perform a detailed SEO Analysis across 100 website data points, and provide clear and actionable recommendations.",

      "breadcrumb": "https://www.seoptimer.com",

      "highlighted_terms": [

        "SEOptimer is a free SEO Audit Tool"

      ]

    },

    {

      "type": "organic",

      "rank_absolute": 2,

      "rank_group": 2,

      "position": "center",

      "serp_features": [],

      "domain": "aioseo.com",

      "url": "https://aioseo.com/seo-analyzer/",

      "title": "FREE SEO Analyzer Tool - Generate Website SEO Audit ...",

      "description": "Analyze your WordPress site to detect critical errors and get actionable insights to boost your SEO and get more traffic.",

      "breadcrumb": "https://aioseo.com › seo-analyzer",

      "highlighted_terms": [

        "Analyze your WordPress site"

      ]

    },

    {

      "type": "organic",

      "rank_absolute": 110,

      "rank_group": 100,

      "position": "center",

      "serp_features": [],

      "domain": "ahrefs.com",

      "url": "https://ahrefs.com/site-audit",

      "title": "A Free SEO Audit Tool by Ahrefs",

      "description": "Scan your website for 170+ technical and on-page SEO issues to get a comprehensive website analysis. Site Audit segments issues into errors, warnings, and ...",

      "breadcrumb": "https://ahrefs.com › site-audit",

      "highlighted_terms": [

        "SEO"

      ]

    },

    {

      "type": "related_searches",

      "rank_absolute": 111,

      "rank_group": 10,

      "serp_features": [

        "related_searches"

      ],

      "position": "center",

      "title": "Recherches associées",

      "links": [

        { "url": "", "title": "SEO Checker" },

        { "url": "", "title": "SEO score" },

        { "url": "", "title": "Aioseo seo analyzer" },

        { "url": "", "title": "SEO checker free" },

        { "url": "", "title": "SEO test Google" },

        { "url": "", "title": "Audit SEO" },

        { "url": "", "title": "Website Analyzer" },

        { "url": "", "title": "SEO tools" }

      ],

      "searches": [

        "SEO Checker",

        "SEO score",

        "Aioseo seo analyzer",

        "SEO checker free",

        "SEO test Google",

        "Audit SEO",

        "Website Analyzer",

        "SEO tools"

      ]

    }

  ]

}

Get HTML SERP dump

GET https://api.seranking.com/v1/serp/classic/tasks/html
Cost: 0 credits

Retrieves the raw HTML version of Google search results pages for a completed SERP task. This method delivers the original SERP markup as rendered by Google, including pagination and layout. The response is returned as a ZIP archive containing Google SERP HTML files and a manifest.

Note: Since the response is a ZIP archive, it must be saved to a file.

Saving the response in Postman

  1. Send the request.
  2. Click Save Response.
  3. Choose Save response to file.
  4. Save the file.

After saving the ZIP file, extract the HTML dump. Use the following command to extract all HTML files and metadata into the serp_data directory:

Copy
unzip SERP_00000_desktop_us_12345.zip -d serp_data

Request parameters

ParameterTypeRequiredDefaultDescription
task_idIntegerYesN/AUnique ID of the query task created using the Add SERP tasks method.

Request example

Copy
curl -X GET 'https://api.seranking.com/v1/serp/classic/tasks/html?task_id=803249' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

  • If the task is still in progress:
ParameterTypeDescription
statusStringIndicates that the task is currently being processed: "processing".
  • If the task is complete:

The server returns a ZIP archive containing the HTML dump. The contents of the HTML dump depend on the device parameter specified when creating the SERP task.

For mobile SERP tasks, the extracted archive contains:

  • One manifest.json file with metadata about the SERP task (e.g., device type, language, location)
  • One HTML file containing up to 100 search results on a single page

For desktop SERP tasks, the extracted archive contains:

  • One manifest.json file with metadata about the SERP task (e.g., device type, language, location)
  • Ten HTML files, each containing ten search results

Response examples

  • If the task is still in progress:
Copy
{

  "status": "processing"

}
  • If the task is complete (mobile output):
Copy
serp_data/

└── mobile/

    ├── manifest.json

    └── page-1.html
  • If the task is complete (desktop output):
Copy
serp_data/

└── desktop/

    ├── manifest.json

    ├── page-1.html

    ├── page-2.html

    ├── ...

    └── page-10.html

List SERP tasks

GET https://api.seranking.com/v1/serp/classic/tasks
Cost: 0 credits

Retrieves a list of all SERP tasks that were added to the queue in the last 24 hours.

Request parameters

No parameters are required for this request.

Request example

Copy
curl -X GET 'https://api.seranking.com/v1/serp/classic/tasks' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns an array of task objects. Each object in the array represents a single task.

ParameterTypeDescription
idIntegerUnique ID of the query task.
queryStringKeyword for the task.
location_idIntegerID of the location for the search results.
language_codeStringLanguage code for the search results.
is_completedBooleanCompletion status of the task (true if completed, false otherwise).
addedStringTimestamp (UTC) when the task was added to the queue.

Response example

Copy
[

        {

        "id": 62,

        "query": "seo report",

        "location_id": 31808,

        "language_code": "fr",

        "is_completed": true,

        "added": "2025-11-03 17:49:34"

    },

    {

        "id": 65,

        "query": "seo api",

        "location_id": 31808,

        "language_code": "fr",

        "is_completed": true,

        "added": "2025-11-03 17:49:34"

    }

]

Get locations

GET https://api.seranking.com/v1/serp/classic/locations
Cost: 0 credits

Retrieves a list of available locations for SERP queries.

Request parameters

ParameterTypeRequiredDefaultDescription
country_codeStringNoN/ACountry code to filter locations by country.

For acceptable values, see Regional database codes.
qStringNoN/AParameter for matching a specific city.
includeStringNoN/AAdditional data to include in the response; currently supports google_ads_location_id.

Request example

Copy
curl -X GET 'https://api.seranking.com/v1/serp/classic/locations?country_code=ES&q=Barcelona&include=google_ads_location_id' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

ParameterTypeDescription
location_idStringLocation identifier for the search query.
location_nameStringFull name of the location returned in the search.
country_codeStringCountry code of the location returned in the search.
coordinatesObjectGeographical coordinates of the location, including latitude and longitude.
google_ads_location_idStringGoogle Ads location ID associated with the location (optional).

Response example

Copy
{

  "data": [

    {

      "location_id": "LOCATION_ID_1",

      "location_name": "Barcelona, Catalonia, Spain",

      "country_code": "ES",

      "google_ads_location_id": "GOOGLE_ADS_ID_1"

    },

    {

      "location_id": "LOCATION_ID_2",

      "location_name": "Province of Barcelona, Catalonia, Spain",

      "country_code": "ES",

      "google_ads_location_id": "GOOGLE_ADS_ID_2"

    },

    {

      "location_id": "LOCATION_ID_3",

      "location_name": "Barcelona, Catalonia, Spain",

      "country_code": "ES",

      "google_ads_location_id": "GOOGLE_ADS_ID_3"

    }

  ]

}

Learn how SE Ranking’s API can boost your SEO!

Hi! Meet our product expert, Alex.

He’ll walk you through the API and show you how to get the most out of it.

  • Enjoy a tailored demo on integrating rich, structured SEO data into your stack.
  • Pin down every tech detail live—auth, endpoints, rate limits, data formats.
  • Compare usage tiers and pricing so you can unlock maximum data value.

Request a free demo to see our tools and integrations in action

By clicking this button, you agree to SE Ranking’s Terms of Services and Privacy Policy.