API

SERP

Documentation for legacy SERP API methods is available upon request. You can contact [email protected] or refer to the relevant Postman collection here.

The SERP API allows retrieving search engine results pages (SERPs) for keywords, including URLs, titles, and snippets, without requiring an active project in SE Ranking. The API supports task creation, checking task status, retrieving standard or advanced results, listing recent tasks, and obtaining 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

Parameter	Type	Required	Default	Description
search_engine	String	Yes	N/A	Search engine name (currently only `google` is supported).
query[]	Array of strings	Yes	N/A	Array of keywords (≤ 255 chars each, up to 1,000 per request). For example: `["avocado", "interstellar"]`.
device	String	Yes	N/A	Search device type. Supported values: `"desktop"`, `"mobile"`.
language_code	String	Yes	N/A	Language code (ISO 639-1, e.g., `fr`).
location_id	Integer	Yes	N/A	Location identifier. You can retrieve available IDs using the Get locations endpoint.
tag	String	No	N/A	Optional 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.

Parameter	Type	Description
id	Integer	Unique ID assigned to each SERP collection task.
query	String	Keyword for the task.
location_id	Integer	ID of the location for the search results.
language_code	String	Language code for the search results.
is_completed	Boolean	Indicates whether the task is completed (`true` or `false`).
added	String	Timestamp 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

Parameter	Type	Required	Default	Description
task_id	String	Yes	N/A	Unique ID of the query task from 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:

Parameter	Type	Description
status	String	Indicates that the task is currently being processed: `"processing"`.

If the task is complete:

Parameter	Type	Description
request_metadata	Object	Metadata about the request.
request_metadata.keyword	String	Keyword used in the search query.
request_metadata.device	String	Search device type.
request_metadata.location_id	Integer	ID of the location for the search results.
request_metadata.language_code	String	Language code for the search results.
request_metadata.tag	String	Custom tag for the request (optional).
request_metadata.crawled_at	String	Timestamp when the SERP was crawled.
request_metadata.serp_url	String	Full SERP URL.
summary	Object	Summary statistics for the search results.
summary.total_results	Integer	Total number of search results found.
summary.organic_items_count	Integer	Number of organic results on the page.
summary.SERP_features	Array	List of all SERP features present (e.g., `tads`, `video`).
items	Array	Array of search result objects.
items[].type	String	Type of the SERP item. Possible values for this endpoint are: – `organic`– `ads`– `featured_snippet`
items[].rank_absolute	Integer	Absolute ranking of the item in the SERP.
items[].rank_group	Integer	Rank within its group of similar items.
items[].position	String	Position on the page (e.g., `top`, `bottom`).
items[].serp_features	Array	List of SERP features associated with this result.
items[].domain	String	Domain of the page (if available).
items[].url	String	URL of the page.
items[].title	String	Title of the page as shown in the SERP.
items[].description	String	Description snippet of the page (if available).
items[].breadcrumb	String	Breadcrumb or main URL path of the page.
items[].highlighted_terms	Array	Terms highlighted in the snippet matching the query.
items[].links	Array	Array of link objects.
items[].links[].url	String	URL of the link.
items[].links[].title	String	Title of the link.
items[].displayUrl	String	Displayed URL of the result as shown in the SERP.

Response example

Processing:

Copy

{

    "status": "processing"

}

Completed:

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

Parameter	Type	Required	Default	Description
task_id	String	Yes	N/A	Unique 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:

Parameter	Type	Description
status	String	Indicates that the task is currently being processed: `"processing"`.

If the task is complete:

Parameter	Type	Description
request_metadata	Object	Metadata about the request.
request_metadata.keyword	String	Keyword submitted in the request. Example: `"how to enjoy learning"`.
request_metadata.device	String	Search device type.
request_metadata.location_id	Integer	ID of the location for the search results.
request_metadata.language_code	String	Language code for the search results.
request_metadata.tag	String	Custom tag for the request (optional).
request_metadata.crawled_at	String	Timestamp when the SERP was crawled.
request_metadata.serp_url	String	Full SERP URL.
summary.total_results	Integer	Total number of search results found.
summary.organic_items_count	Integer	Number of organic results on the page.
summary.SERP_features	Array	List of SERP features present (e.g., `video`, `tads`, etc.).
items[].type	String	Type of the SERP item (e.g., `organic`).
items[].rank_absolute	Integer	Absolute ranking of the item in the SERP.
items[].rank_group	Integer	Rank within its group of similar items.
items[].position	String	Position of the item on the SERP (e.g., `top`, `bottom`).
items[].serp_features	Array	List of SERP features associated with this result.
items[].domain	String	Domain of the page (if available).
items[].url	String	URL of the page.
items[].title	String	Title of the page as shown in the SERP.
items[].description	String	Description snippet of the page (if available).
items[].breadcrumb	String	Breadcrumb or main URL path of the page.
items[].highlighted_terms	Array	Terms highlighted in the snippet matching the query.
items[].links	Array	Array of link objects.
items[].links[].url	String	URL of the link.
items[].links[].title	String	Title of the link.
items[].displayUrl	String	Displayed URL of the result as shown in the SERP.
items[].searches	Array	Array of related search queries (only present for `related_searches` items).

Response example

Processing:

Copy

{

    "status": "processing"

}

Completed:

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"

      ]

    }

  ]

}

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.

Parameter	Type	Description
id	Integer	Unique ID of the query task.
query	String	Keyword for the task.
location_id	Integer	ID of the location for the search results.
language_code	String	Language code for the search results.
is_completed	Boolean	Completion status of the task (`true` if completed, `false` otherwise).
added	String	Timestamp (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

Parameter	Type	Required	Default	Description
country_code	String	No	N/A	Country code to filter locations by country. For acceptable values, see Regional database codes.
q	String	No	N/A	Parameter for matching a specific city.
include	String	No	N/A	Additional 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

Parameter	Type	Description
location_id	String	Location identifier for the search query.
location_name	String	Full name of the location returned in the search.
country_code	String	Country code of the location returned in the search.
coordinates	Object	Geographical coordinates of the location, including latitude and longitude.
google_ads_location_id	String	Google 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"

    }

  ]

}

SERP

You are reading the Data API docs

Add SERP tasks

Request parameters

Request example

Response parameters

Response example

Get standard SERP results

Request parameters

Request example

Response parameters

Response example

Get advanced SERP results

Request parameters

Request example

Response parameters

Response example

List SERP tasks

Request parameters

Request example

Response parameters

Response example

Get locations

Request parameters

Request example

Response parameters

Response example

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

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