SERP Results API

SERP Results API is aimed at getting the TOP 100 SERP results from Google for the key phrases (with URL, snipped, site’s position) without having an active project in SE Ranking.

One request to SERP Results API costs:

$0.003

Adding a keyword

Description

The method allows to add a query to the queue to obtain SERP results.

Parameters

Name	Required	Description
query	Yes	Search query or a query array (a max number of characters in a query – 255, a max number of queries in an array — 1000)
engine_id	Yes	Unique search engine ID. A complete list of search engines and their unique IDs can be obtained via GET /system/search-engines (be sure to type in Google)
region_name	No	Name of region for search (only for the Google search engine)

Request format

POST /parsing/serp/tasks

{

    “engine_id”: 1,

    “query”: “text”

    or

    “query”: [“text”, “text2”]

}

Result

If successful, the server returns the unique ID of every query added to the queue

Name	Required	Description
task_id	Yes	Unique query ID

Response example

[

    {

        “query”: :”text”,

        “task_id”: 123456

    }

]

Errors

HTTP code	Error message
400	Invalid engine_id
400	Empty query
400	Query $query too long
403	Empty balance

Status verification and getting the verification results

Description

The method allows to get the result of a keyword that was previously added to the queue. If the keyword positions have not yet been recorded, the invoked method returns the status. The results are stored for 24 hours, then they are deleted.

Parameters

Name	Required	Description
task_id	Yes	Unique query ID

Request format

GET /parsing/serp/tasks/{task_id}

Result

If successful, the server returns the query status.

If the query is in queue, the server returns the following status: processing.

Response example

{

    “status”: “processing”

}

If the verification has been completed, the results of the verification are returned. If successful, the server returns an array containing the query results from the TOP 100 SERPs.

Name	Requery	Description
position	Yes	Page position in the TOP 100
url	Yes	URL of the page that’s ranked in the TOP 100
title	Yes	Title of the page in the TOP 100
snippet	Yes	Description snippet of the page in the TOP 100
cache_url	No	Link to the cached copy of a page that’s ranked in the TOP 100

Response example

{

    “results”: [

        {

        “position”: “1”,

        “url”: “https://www.pizzahut.com/”,

        “title”: “Pizza Hut: Pizza Delivery”,

        “snippet”: “Order pizza online for fast delivery or carryout from a store near you. View our full menu, see nutritional information, find store locations, and more.“,

        “cache_url”: “https://webcache.googleusercontent.com/search?q=cache:oiTvlHsuOeEJ:https://www.pizzahut.com/+&cd=4&hl=en&ct=clnk&gl=us”

        },

        …

        “position”: “99”,

        “url”: “https://techcrunch.com/2018/08/20/google-doctor-fork/”,

        “title”: “Google created a fake pizza brand to test out creative strategies for …”,

        “snippet”: “Aug 20, 2018 – Google’s Unskippable Labs team has been testing ad effectiveness in a compelling new way: It created a fake pizza brand called Doctor Fork, …“,

        “cache_url”: “https://webcache.googleusercontent.com/search?q=cache:wi5sKCy0ResJ:https://techcrunch.com/2018/08/20/google-doctor-fork/+&cd=120&hl=en&ct=clnk&gl=us”

        }

    ]

}

Errors

HTTP code	Error message
404	Task not found

List of all user queries

Description

The method allows to obtain a list of all user queries that were added to the queue in the last 24 hours.

Request format

GET /parsing/serp/tasks

Result

If successful, the server returns an array of queries that were added to the queue, and their statuses.

Name	Description
id	Unique query ID
query	Keyword or phrase (query)
region_name	Name of region for search (only for the Google search engine)
engine_id	Unique search engine ID. A complete list of search engines and their unique IDs can be obtained via GET /system/search-engines (be sure to type in Google)
added	The date when the query was added to the queue.
is_completed	Query verification status (1 – checked, 0 – no)

Response example

{

    “tasks”: [

        {

            “id”: “18638740”,

            “query”: “book”,

            “region_name”: null,

            “engine_id”: “411”,

            “added”: “2018-08-28 10:25:29”,

            “is_completed”: “0”

        },

        …

        {

            “id”: “18639398”,

            “query”: “pizza”,

            “region_name”: “New York”,

            “engine_id”: “200”,

            “added”: “2018-08-28 12:25:52”,

            “is_completed”: “1”

        }

    ]

}