NAVNavbar
Logo
php python csharp java

SERP API

SERP API provides the Top-100 SERP results for a keyword. The results are specific to the selected search engine (see the List of Search Engines) and location (see the List of Locations) settings.
The SERP HTML endpoint provides a raw HTML page of the SERP based on the specified keyword and search engine.
You can also use the SERP Reviews endpoint for fetching user reviews for a specific local establishment (restaurant, shop, etc.) directly from SERP.

There are two different methods you can use to retrieve data: Delayed and Live.

The operating principle of Delayed SERP API is similar to that of Rank Tracker API. Unlike the Live method, Delayed SERP API doesn’t return all completed results at once but instead provides a list of task identifiers (task_id) that are unique and assigned to each separate task. You can then use the task’s task_id to return its results. The delayed method is supported across all endpoints of SERP API.

Live SERP API allows you to get data immediately after the task is completed without making a separate request. This is useful if your app’s functionality implies real-time data. To date, the Live method is supported in SERP and Extra SERP endpoints.

Live SERP

Live SERP provides real-time data on top 100 search engine results for the specified keyword, search engine, and location. Note that this endpoint does not provide a complete overview of featured snippets and other extra elements of SERPs – please, refer to Live Extra SERP if your project requires a detailed real-time depiction of SERPs.

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com/', null, 'login', 'password');
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
    exit();
}

$post_array = array();

$my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "se_name" => "google.co.uk",
    "se_language" => "English",
    "loc_name_canonical"=> "London,England,United Kingdom",
    "key" =>  mb_convert_encoding("online rank checker", "UTF-8")
);

try {
    // POST /v2/live/srp_tasks_post/$data
    // $tasks_data must by array with key 'data'
    $result = $client->post('v2/live/srp_tasks_post', array('data' => $post_array));
    print_r($result);

    //do something with post results

    $post_array = array();
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.2373 sec.",
    "results_count": 99,
    "results": {
        "organic": [
            {
                "post_id": "64461328",
                "task_id": 4113773646,
                "se_id": 22,
                "loc_id": 1006886,
                "key_id": 1095202,
                "post_key": "online rank checker",
                "result_datetime": "2019-02-01 15:03:52 +00:00",
                "result_position": 1,
                "result_url": "https://smallseotools.com/keyword-position/",
                "result_breadcrumb": "https://smallseotools.com/keyword-position/",
                "result_title": "Keyword Rank Checker - A Free online Google keyword position ...",
                "result_snippet_extra": "",
                "result_snippet": "To check the keyword rank in Google ranking, use our free Keyword Position Checker. Just enter the domain name, keywords and search engine and click the ...",
                "results_count": 8680000,
                "result_extra": "people_also_ask,videos",
                "result_stat": [],
                "result_spell": "",
                "result_spell_type": "",
                "result_highlighted": [
                    "RANK CHECKER",
                    "check",
                    "rank",
                    "ranking",
                    "Position Checker",
                    "Check Position"
                ],
                "result_se_check_url": "https://www.google.co.uk/search?q=online%20rank%20checker&num=100&hl=en&gl=GB&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            },
            {
                "post_id": "64461328",
                "task_id": 4113773646,
                "se_id": 22,
                "loc_id": 1006886,
                "key_id": 1095202,
                "post_key": "online rank checker",
                "result_datetime": "2019-02-01 15:03:52 +00:00",
                "result_position": 2,
                "result_url": "https://www.serprobot.com/",
                "result_breadcrumb": "https://www.serprobot.com/",
                "result_title": "serprobot.com: Free SERP checker - google ranking check",
                "result_snippet_extra": "",
                "result_snippet": "Free SERP check, track and monitor your search engine keyword ranking quickly and accurately.",
                "results_count": 8680000,
                "result_extra": "people_also_ask,videos",
                "result_stat": [],
                "result_spell": "",
                "result_spell_type": "",
                "result_highlighted": [
                    "rankings",
                    "Check"
                ],
                "result_se_check_url": "https://www.google.co.uk/search?q=online%20rank%20checker&num=100&hl=en&gl=GB&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            },
            {
                "post_id": "64461328",
                "task_id": 4113773646,
                "se_id": 22,
                "loc_id": 1006886,
                "key_id": 1095202,
                "post_key": "online rank checker",
                "result_datetime": "2019-02-01 15:03:52 +00:00",
                "result_position": 3,
                "result_url": "https://www.thehoth.com/search-engine-rankings/",
                "result_breadcrumb": "https://www.thehoth.com/search-engine-rankings/",
                "result_title": "Free Google Search Engine Rankings Checker Tool - The Hoth",
                "result_snippet_extra": " Rating: 4.8 - \u200e1,873 votes",
                "result_snippet": "The HOTH Search Engine Ranking Tool helps you identify high volume keywords for your domain.",
                "results_count": 8680000,
                "result_extra": "people_also_ask,videos",
                "result_stat": {
                    "rating": 4.8,
                    "rating_type": "stars",
                    "rating_max": 5,
                    "votes": 1873
                },
                "result_spell": "",
                "result_spell_type": "",
                "result_highlighted": [
                    "Ranking Checker",
                    "Ranking",
                    "ranking",
                    "position"
                ],
                "result_se_check_url": "https://www.google.co.uk/search?q=online%20rank%20checker&num=100&hl=en&gl=GB&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            },

            {
                "post_id": "64461328",
                "task_id": 4113773646,
                "se_id": 22,
                "loc_id": 1006886,
                "key_id": 1095202,
                "post_key": "online rank checker",
                "result_datetime": "2019-02-01 15:03:52 +00:00",
                "result_position": 99,
                "result_url": "https://www.accuranker.com/rank-tracker",
                "result_breadcrumb": "https://www.accuranker.com/rank-tracker",
                "result_title": "Live serp Tool | AccuRanker",
                "result_snippet_extra": "",
                "result_snippet": "Live SERP Tool is 100% free SEO Rank tracking tool. ... Our fast, free SERP checker solves the problem of being unable to get accurate location specific SERP ...",
                "results_count": 8680000,
                "result_extra": "people_also_ask,videos",
                "result_stat": [],
                "result_spell": "",
                "result_spell_type": "",
                "result_highlighted": [
                    "Rank Checker",
                    "web"
                ],
                "result_se_check_url": "https://www.google.co.uk/search?q=online%20rank%20checker&num=100&hl=en&gl=GB&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            }
        ],
        "paid": [],
        "extra": {
            "related": [
                [
                    "seo ranking checker free",
                    "website rank checker",
                    "google ranking tool",
                    "bulk keyword rank checker",
                    "google search ranking",
                    "seo checker",
                    "how to check keyword ranking in google analytics",
                    "rank tracker"
                ]
            ]
        }
    }
}

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. You can set only one task at a time. If you use the url field, then the processing of each task will take more time. If you use our system identifiers (se_idloc_idkey_id), the processing of tasks will be faster.

Below you will find a detailed description of the fields you can use for setting a task.

Description of the fields for setting a task:

Field name Type Description
se_id integer search engine id
optional field, if you specify se_name
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
also, when the information about set task is returned, you will get the se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_name by making a separate request to the List of Search Engines
example: “google.co.uk”
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with se_language by making a separate request to the List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
loc_name_canonical string full name of the search engine location
optional field if you specify loc_id
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
key_id integer keyword id
optional field if you specify key
when you set a task for the first time you won’t be able to know this field. But if you plan to collect rankings for this keyword, we recommend saving the key_id returned after the task was set, and use this field to get the results later on.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”if this field contains ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’ then the charge per task will be multiplied by 10.
se_param_add string additional parameters of the search query
optional field
for example, if you want to disable auto-correction of the search query misspelling for Google, you should use the “&nfpr=1” parameter
Get the list of available parameters and additional details here.
url string direct URL of the search query
optional field
you can specify a direct URL, and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process, and also requires specifying the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS


When setting tasks, you send its data in the array using data fields. The index of the task in this array ($my_unq_id variable in examples) can be used at any time after that, as the post_id field. It will be returned to you with all server responses as well as our unique task_id field. Thanks to this feature, you can use this field to associate the set tasks with the identifiers in your system.

As a response of the API server, you will receive a JSON array in the results field of which there will be information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      organic array results array of organic SERP
            task_id integer unique task identifier in our system (UInt64)
            post_id string the index in the array received in the POST array
            se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines
            loc_id integer search engine location id
You can use it for matching your search engines with the DataForSEO List of Search Engines
            key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
            post_key string key received in the POST array
a keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            result_position integer position in SERP
            result_datetime string date and time when the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
            result_url string relevant URL in SERP
            result_breadcrumb string breadcrumb, i.e. the internal navigation links that reflect the structure of the page
            result_title string snippet header in SERP
            result_snippet_extra string the enhanced snippet in SERP
for example: ratings, price, author, etc
            result_snippet string snippet in SERP
            results_count integer total number of results in SERP
            result_stat array information about the reviews element of the result
empty array if the result does not have a reviews element
                  rating integer/float rating
the popularity rate based on reviews and displayed in SERPs
                  rating_type string measurement units
shows which measurement units are used in the rating field
there are two possible options: starspercents
                  rating_max integer the maximum value for a rating
                  votes integer amount of feedback
            result_extra string additional (extra) elements in SERP
all extra elements in the string are separated by commas, e.g.: top_stories, featured_snippet, people_also_ask, local_pack, carousel, images, map, video, twitter, app, shopping, google_flights, jobs, answer_box, related_search, knowledge_graph, google_review, mention
            result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
            result_spell_type string type of auto-correction
types of hints: did_you_meanshowing_results_forno_results_found_for
            result_highlighted array words highlighted in bold within the results snippet
            result_se_check_url string direct URL to search engine results
you can use it to make sure that we provided exact results
      paid array results array of paid SERP
            task_id integer unique task identifier in our system (UInt64)
            post_id string the index of the array received in the POST array
            se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines
            loc_id integer search engine location id
You can use it for matching your search engines with the DataForSEO List of Search Engines
            key_id integer keyword id in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
            post_key string keyreceived in the POST array
a keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            result_position integer position in SERP
            result_datetime string date and time when the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
            result_url string relevant URL in SERP
            result_breadcrumb string breadcrumb, i.e. the internal navigation links that reflect the structure of the page
            result_title string snippet header in SERP
            result_snippet_extra string the enhanced snippet in SERP
for example: ratings, price, author, etc
            result_snippet string snippet in SERP
            results_count integer total number of results in SERP
            result_stat array informational array about the reviews element of the result
empty array if the result does not have a reviews element
                  rating integer/float rating
the popularity rate based on reviews and displayed in SERPs
                  rating_type string measurement units
shows which measurement units are used in the rating field
there are two possible options: starspercents
                  rating_max integer the maximum value for a rating
                  votes integer amount of feedback
            result_extra string additional (extra) elements in SERP
all extra elements in the string are separated by commas, e.g.: top_stories, featured_snippet, people_also_ask, local_pack, carousel, images, map, video, twitter, app, shopping, google_flights, jobs, answer_box, related_search, knowledge_graph, google_review
            result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
            result_spell_type string type of auto-correction
types of hints: did_you_meanshowing_results_forno_results_found_for
            result_highlighted array words highlighted in bold within the results snippet
            result_se_check_url string direct URL to search engine results
You can use it to make sure that we provided exact results
      extra array results array of extra SERP elements
extra SERP elements are available only for Google search engine
            related array array of the ‘related search queries’ string
this array will be present if the element is found in SERP

‌‌
Possible error codes:

Error Code Meaning
404 “not found or not enough data: search engine” – you’ve specified a nonexistent se_id or a search engine according to the specified se_name wasn’t found
404 “not found or not enough data: location” – you’ve specified a nonexistent loc_id or the location of the search engine according to the specified loc_name_canonical wasn’t found
404 “not enough data: keyword” – you didn’t specify a keyword in the task
404 “search engine did not return results” – SERP is empty. Check if you have added the key correctly
404 “top results not found” – there is no SERP with the specified parameters
501 “invalid ‘data’ field” – probably you haven’t passed data for the tasks in the data field. POST data should be represented as an array and added to the data field: array(‘data’ => $post_array_for_tasks)
501 “invalid data” – data in the data field isn’t an array with the required structure.
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Setting SERP Tasks

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip
require('RestClient.php');

$api_url = 'https://api.dataforseo.com/';
try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient($api_url, null, 'login', 'password');
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
    exit();
}

$post_array = array();

// example #1 - simplest
// you set only a website URL and a search engine URL.
// This search engine URL string will be searched, compared to our internal parameters
// and used as:
// "se_id", "loc_id", "key_id" ( actual and fresh list can be found here: "se_id":
// https://api.dataforseo.com/v2/cmn_se , "loc_id": https://api.dataforseo.com/v2/cmn_locations ) (see example #3 for details)
// If a task was set successfully, this *_id will be returned in results: 'v2/srp_tasks_post' so you can use it.
// The setting of a task can fail, if you set not-existent search engine, for example.
// Disadvantages: You cannot work with "map pack", "maps", "mobile"
$my_unq_id = mt_rand(0, 30000000); // your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "url" => "https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
);

// example #2 - will return results faster than #1, but is simpler than example #3
// All parameters should be set in the text format.
// All data will be will be searched, compared to our internal parameters
// and used as:
// "se_id", "loc_id", "key_id" ( actual and
// fresh list can be found here: "se_id": https://api.dataforseo.com/v2/cmn_se ,
// "loc_id": https://api.dataforseo.com/v2/cmn_locations )
// If a task was set successfully, this *_id will be returned in results: 'v2/srp_tasks_post' so you can use it.
// The setting of a task can fail, if you set not-existent search engine, for example.
// Disadvantages: The process of search and comparison of provided data to our internal parameters may take some time.
$my_unq_id = mt_rand(0, 30000000); // your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "se_name" => "google.co.uk",
    "se_language" => "English",
    "loc_name_canonical" => "London,England,United Kingdom",
    "key" => mb_convert_encoding("party wigs", "UTF-8")
    //,"pingback_url" => "http://your-domain.com/pingback_url_example.php?task_id=$task_id" //see pingback_url_example.php script
);

// example #3 - the fastest one. All parameters should be set in our internal format.
// Actual and fresh list can be found here: "se_id": https://api.dataforseo.com/v2/cmn_se ,
// "loc_id": https://api.dataforseo.com/v2/cmn_locations
$my_unq_id = mt_rand(0, 30000000); // your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "se_id" => 22,
    "loc_id" => 1006886,
    "key_id" => 59837
    //,"postback_url" => "http://your-domain.com/postback_url_example.php" //see postback_url_example.php script
);

// This example has a 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
if (count($post_array) > 0) {
    try {
        // POST /v2/srp_tasks_post/$tasks_data
        // $tasks_data must by array with key 'data'
        $task_post_result = $client->post('/v2/srp_tasks_post', array('data' => $post_array));
        print_r($task_post_result);

        //do something with post results

        $post_array = array();
    } catch (RestClientException $e) {
        echo "\n";
        print "HTTP code: {$e->getHttpCode()}\n";
        print "Error code: {$e->getCode()}\n";
        print "Message: {$e->getMessage()}\n";
        print  $e->getTraceAsString();
        echo "\n";
    }
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 3,
    "results": {
        "11913049": {
            "post_id": 11913049,
            "post_key": "online rank checker",
            "task_id": 404227822,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "20469414": {
            "post_id": 20469414,
            "post_key": "party wigs",
            "task_id": 404227823,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1562667,
            "status": "ok"
        },
        "6273173": {
            "post_id": 6273173,
            "post_key": "seo tools",
            "task_id": 404227824,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 59837,
            "status": "ok"
        }
    }
}

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. We recommend to set up to 100 tasks at a time. Such limits were set due to the variations of task setting methods that you may use.

If you use the url field, then the processing of each task will take more time. If you use our system identifiers (se_id, loc_id, key_id), the processing of tasks will be faster.

You can also retrieve the results of completed tasks using the unique task identifier task_id. Alternatively, we can send them to you as soon as they are ready if you specify the postback_url or pingback_url when setting a task. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

Below you will find a detailed description of the fields you can use for setting a task.

Description of the fields for setting a task:

Field name Type Description
priority integer execution priority
optional field
can have the following values:
1 – normal execution priority (set by default)
2 – high execution priority

url string direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
se_id integer search engine id
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
also, when the information about set task is returned, you will get the se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_name by making a separate request to the List of Search Engines
example: “google.co.uk”
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with se_language by making a separate request to the List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about the set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
key_id integer keyword id
optional field if you specify key
when you set a task for the first time you won’t be able to know this field. But if you plan to collect rankings for this keyword, we recommend saving the key_id returned after the task was set, and use this field to get the results later on.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”if this field contains ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’ then the charge per task will be multiplied by 10.
se_param_add string additional parameters of the search query
optional field
for example, if you want to disable auto-correction of the search query misspelling for Google, you should use the “&nfpr=1” parameter
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify the postback URL there will be no need to use Get SERP Tasks Results for obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$task_id’ string as a $task_id variable and ‘$post_id’ as $post_id variable. We will set the necessary values before sending the request. For example:
http://your-server.com/pingscript?taskId=$task_id
http://your-server.com/pingscript?taskId=$task_id&postId=$post_id


When setting a task, you send its data in the array using data fields. The index of the task in this array ($my_unq_id variable in examples) can be used at any time after that, as the post_id field. It will be returned to you with all server responses as well as our unique task_id field. Thanks to this feature, you can use this field to associate the set tasks with identifiers in your system.

Here are some examples:

  1. There is an identifier in your system that corresponds to a task that you set to collect data, for example, 100500. When you set the task you send it in the data array with 100500 index, e.g.: "{"data":{"100500":{"priority":1,"se_name":"google.co.uk","se_language":"English","loc_name_canonical":"London,England,United Kingdom","key":"online rank tracker"}}}"
    When you get a result of this task, 100500 will be returned in the post_id field, and you will be able to associate the received result with the task specified in your system.
  2. You may also want to associate other kinds of data in your system. For instance:
    • a keyword has id=1238 at your system,
    • a search engine has id=43289,
    • a location id=97435,
    • a language id=2,
    • a user for whom you want to complete this task has id=9999.

    Since the index of a task in the data array can be specified as a string, you can create this index using any symbol as a delimiter that fits you the most to send the information mentioned above as a post_id. For instance, let’s see how it will look like if we use # as a delimiter. The index that includes all the necessary data will have this value 1238#43289#97435#2#9999. As a result, the request for setting a task will look like this: "{"data":{"1238#43289#97435#2#9999":{"priority":1,"se_name":"google.co.uk","se_language":"English","loc_name_canonical":"London,England,United Kingdom","key":"online rank tracker"}}}"
    When you get the result of this task, you will be able to put in order the string to get the values you need. It will make the integration with our service easier for you.

As a response of the API server, you will receive JSON array in the results field  of which there will be an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the  results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
            status string results of this task setting
“ok” – success
“error” – error
if status=“error”, check the error array for more details
            error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
                  code integer error code
                  message string text description of the error
            post_id string the index in the array received in the POST request
            post_key string key received in the POST request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            se_id integer search engine id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
            loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
            key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task

‌‌
Possible error codes:

Error Code Meaning
404 “not found or not enough data: search engine” – you’ve specified a nonexistent se_id or a search engine according to the specified se_name wasn’t found
404 “not found or not enough data: location” – you’ve specified a nonexistent loc_id or the location of the search engine according to the specified loc_name_canonical wasn’t found
404 “not enough data: keyword” – you didn’t specify a keyword in the task
501 “invalid ‘data’ field” – probably you haven’t passed data for the tasks in the data field. POST data should be represented as an array and added to the data field: array(‘data’ => $post_array_for_tasks)
501 “invalid data” – data in the data field isn’t an array with the required structure.
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get SERP Completed Tasks

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com', null, 'login', 'password');

    // #1 - get task_id list of ALL ready results
    //GET /v2/srp_tasks_get
    $tasks_get_result = $client->get('v2/srp_tasks_get');
    print_r($tasks_get_result);

    //get tasks one by one

} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0120 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 107,
            "post_id": 11577837,
            "post_key": "online rank checker",
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "results_count": 4690000,
            "result_extra": "videos",
            "result_spell": "",
            "result_spell_type": "",
            "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
        }
    ]
}

You will get the list of completed tasks, the results of which haven’t been collected yet. Note that after you make a new call to this endpoint, all task_id received as a result of the previous call will be permanently removed from this list of completed tasks in order to avoid duplication.

If you specify pingback_url or postback_url  you don’t have to use srp_tasks_get to get the list of completed tasks. Our system will send a GET request to the pingback_url or a POST request with the results to the postback_url.

Please note that if you specify the postback_url or pingback_url field, the task will not be in the list of completed tasks. The task can only be found in the list only if your server returned HTTP code response less than 200 or higher than 300.

As a response of the API server, you will receive an array in the results field containing a list of completed results.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
     code integer error code
     message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
     results array results array of tasks setting
       task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
       post_id string the index in the array received in the POST request
       post_key string key received in the POST request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
       se_id integer search engine id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
       loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
       key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
       results_count integer total number of results in SERP
       result_extra string additional (extra) elements in SERP
all extra elements in the string are separated by commas, e.g.: top_stories, featured_snippet, people_also_ask, local_pack, carousel, images, map, video, twitter, app, shopping, google_flights, jobs, answer_box, related_search, knowledge_graph, google_review
       result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
       result_spell_type string type of auto-correction
types of hints: did_you_mean, showing_results_for, no_results_found_for
       result_se_check_url string direct URL to search engine results
You can use it to make sure that we provided exact results

Get SERP Results by task_id

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com', null, 'login', 'password');

    // #1 - get task_id list of ALL ready results
    //GET /v2/srp_tasks_get
    $tasks_get_result = $client->get('v2/srp_tasks_get');
    print_r($tasks_get_result);
    if ($tasks_get_result["status"] == "ok") {
        foreach($tasks_get_result["results"] as $tasks_get_row) {
            // #2 - get result by task_id
            //GET /v2/srp_tasks_get/$task_id
            $serp_result = $client->get('v2/srp_tasks_get/'.$tasks_get_row["task_id"]);
            print_r($serp_result);

            //do something with results
        }
    }
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0135 sec.",
    "results_count": 100,
    "results": {
            "organic": [
                {
                    "post_id": 2833944,
                    "task_id": 405460981,
                    "se_id": 22,
                    "loc_id": 1006886,
                    "key_id": 1095202,
                    "post_key": "online rank checker",
                    "result_datetime": "2016-12-19 14:41:33 +02:00",
                    "result_position": 1,
                    "result_url": "https:\/\/serps.com\/tools\/rank-checker\/",
                    "result_breadcrumb": "https:\/\/serps.com\/tools\/rank-checker\/",
                    "result_title": "Free Keyword Rank Checker - Google & Yahoo | SERPs.com",
                    "result_snippet_extra": "",
                    "result_snippet": "International and local keyword rankings. Check keyword rankings positions in Google or Yahoo from over 100 country and language combinations.",
                    "results_count": 4690000,
                    "result_extra": "videos",
                    "result_stat": [],
                    "result_spell": "",
                    "result_spell_type": "",
                    "result_highlighted": [
                        "RANK CHECKER",
                        "check",
                        "rank",
                        "ranking",
                        "Position Checker",
                        "Check Position"
                    ],
                    "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
                },
                {
                    "post_id": 2833944,
                    "task_id": 405460981,
                    "se_id": 22,
                    "loc_id": 1006886,
                    "key_id": 1095202,
                    "post_key": "online rank checker",
                    "result_datetime": "2016-12-19 14:41:33 +02:00",
                    "result_position": 2,
                    "result_url": "https:\/\/ranksonic.com\/",
                    "result_breadcrumb": "https:\/\/ranksonic.com\/",
                    "result_snippet_extra": "Rating: 4.6 - ‎6,054 reviews",
                    "result_title": "RankSonic ⓴⓰ - Rank Tracking SEO software. Website ranking SEO ...",
                    "result_snippet": "⓴⓰ Rank Tracking SEO Software ? Keyword Google online search engine seo \n... Check what potential your keywords have to evaluate their competition level.",
                    "results_count": 4690000,
                    "result_extra": "videos",
                    "result_stat": [],
                    "result_spell": "",
                    "result_spell_type": "",
                    "result_highlighted": [
                        "rankings",
                        "Check"
                    ],
                    "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
                },

                {
                    "post_id": 2833944,
                    "task_id": 405460981,
                    "se_id": 22,
                    "loc_id": 1006886,
                    "key_id": 1095202,
                    "post_key": "online rank checker",
                    "result_datetime": "2016-12-19 14:41:33 +02:00",
                    "result_position": 99,
                    "result_url": "http:\/\/www.prcheckingtool.com\/",
                    "result_breadcrumb": "http:\/\/www.prcheckingtool.com\/",
                    "result_title": "PR Checking Tool - Website Ranking Checker",
                    "result_snippet_extra": "",
                    "result_snippet": "It is a simple yet powerful tool checking the online ranking of different websites. If you think that its sole utilization is for web ranking only then you are wrong as it ...",
                    "results_count": 4690000,
                    "result_extra": "videos",
                    "result_stat": {
                        "rating": 4.2,
                        "rating_type": "stars",
                        "rating_max": 5,
                        "votes": 23
                    },
                    "result_spell": "",
                    "result_spell_type": "",
                    "result_highlighted": [
                        "Ranking Checker",
                        "Ranking",
                        "ranking",
                        "position"
                    ],
                    "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
                }
        ],

        "paid": [
                {
                    "post_id": 2833944,
                    "task_id": 405460981,
                    "se_id": 22,
                    "loc_id": 1006886,
                    "key_id": 1095202,
                    "post_key": "online rank checker",
                    "result_datetime": "2016-12-19 14:41:33 +02:00",
                    "result_position": 1,
                    "result_url": "https:\/\/www.seorankmonitor.com\/",
                    "result_breadcrumb": "https:\/\/www.seorankmonitor.com\/",
                    "result_title": "SEO Rank Monitor - The Most Complete Rank Checker",
                    "result_snippet_extra": "",
                    "result_snippet": "Everything you need to keep your Website Ranked High - Start a Free Trial Now!",
                    "results_count": 4690000,
                    "result_extra": "videos",
                    "result_stat": [],
                    "result_spell": "",
                    "result_spell_type": "",
                    "result_highlighted": [
                        "Rank Checker",
                        "web"
                    ],
                    "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
                }
        ],
        "extra": {
            "related": [
                [
                    "what is seo and how it works",
                    "seo definition",
                    "seo google",
                    "how to do seo",
                    "seo wiki",
                    "seo tutorial",
                    "seo tutorial",
                    "seo company"                    
                ]
            ]
        }
    }
}

Description of the fields for sending a request:

Field name Type Description
task_id integer task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time


As a response of the API server, you will receive an array in the results field containing a list of completed results.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      organic array results array of organic SERP
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time. You are charged for each GET request for receiving the results.
            post_id string the index of the array received in the POST array
            se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines
            loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
            key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
            post_key string key received in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            result_position integer position in SERP
            result_datetime string date and time when the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
            result_url string relevant URL in SERP
            result_breadcrumb string breadcrumb, i.e. the internal navigation links that reflect the structure of the page
            result_title string snippet header in SERP
            result_snippet_extra string the enhanced snippet in SERP
For example: ratings, price, author, etc
            result_snippet string snippet in SERP
            results_count integer total number of results in SERP
            result_stat array information about the reviews element of the result
empty array if the result does not have a reviews element
                  rating integer/float rating
the popularity rate based on reviews and displayed in SERPs
                  rating_type string measurement units
shows which measurement units are used in the rating field
there are two possible options: stars, percents
                  rating_max integer the maximum value for a rating
                  votes integer amount of feedback
            result_extra string additional (extra) elements in SERP
all extra elements in the string are separated by commas, e.g.: top_stories, featured_snippet, people_also_ask, local_pack, carousel, images, map, video, twitter, app, shopping, google_flights, jobs, answer_box, related_search, knowledge_graph, google_review, mention
            result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
            result_spell_type string type of auto-correction
types of hints: did_you_mean, showing_results_for, no_results_found_for
            result_highlighted array words highlighted in bold within the results snippet
            result_se_check_url string direct URL to search engine results
You can use it to make sure that we provided exact results
      paid array results array of paid SERP
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
            post_id string the index of the array received in the POST array
            se_id integer search engine id
            loc_id integer search engine location id
You can use it for matching your search engines with the DataForSEO List of Search Engines
            key_id integer keyword id in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when you setting a task
            post_key string key received in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            result_position integer position in SERP
            result_datetime string date and time when the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
            result_url string relevant URL in SERP
            result_breadcrumb string breadcrumb, i.e. the internal navigation links that reflect the structure of the page
            result_title string snippet header in SERP
            result_snippet_extra string the enhanced snippet in SERP
For example: ratings, price, author, etc
            result_snippet string snippet in SERP
            results_count integer total number of results in SERP
            result_stat array information about the reviews element of a result
empty array if the result does not have a reviews element
                  rating integer/float rating
the popularity rate based on reviews and displayed in SERPs
                  rating_type string measurement units
shows which measurement units are used in the rating field
there are two possible options: stars, percents
                  rating_max integer the maximum value for a rating
                  votes integer amount of feedback
            result_extra string additional (extra) elements in SERP
all extra elements in the string are separated by commas, e.g.: top_stories, featured_snippet, people_also_ask, local_pack, carousel, images, map, video, twitter, app, shopping, google_flights, jobs, answer_box, related_search, knowledge_graph, google_review, mention
            result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
            result_spell_type string type of auto-correction
types of hints: did_you_mean, showing_results_for, no_results_found_for
            result_highlighted array words highlighted in bold within the results snippet
            result_se_check_url string direct URL to search engine results
You can use it to make sure that we provided exact results
      extra array results array of extra SERP elements
extra SERP elements are available only for Google search engine
            related array array of the ‘related search queries’ strings
this array will be present if the element is found in SERP


Possible error codes

Error Code Meaning
102 “task in queue” – the task is being enqueued to handling, please, try again later
201 “task handed” – the task has been received and sent to handling, please, try again later
202 “in progress” – the task is in the handling process, please, try again later
404 “search engine did not return results” – SERP is empty. Check if you have added key correctly
404 “top results not found” – there is no SERP with the specified parameters

Setting SERP HTML Tasks

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

$api_url = 'https://api.dataforseo.com/';
try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient($api_url, null, 'login', 'password');
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
    exit();
}

$post_array = array();

// example #1 - simplest
// you set only a website URL and a search engine URL.
// This search engine URL string will be searched, compared to our internal parameters
// and used as:
// "se_id", "loc_id", "key_id" ( actual and fresh list can be found here: "se_id":
// https://api.dataforseo.com/v2/cmn_se , "loc_id": https://api.dataforseo.com/v2/cmn_locations ) (see example #3 for details)
// If a task was set successfully, this *_id will be returned in results: 'v2/srp_html_tasks_post' so you can use it.
// The setting of a task can fail, if you set not-existent search engine, for example.
// Disadvantages: You cannot work with "map pack", "maps", "mobile"
$my_unq_id = mt_rand(0, 30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "url" => "https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
);

// example #2 - will return results faster than #1, but is simpler than example #3
// All parameters should be set in the text format.
// All data will be will be searched, compared to our internal parameters
// and used as:
// "se_id", "loc_id", "key_id" ( actual and
// fresh list can be found here: "se_id": https://api.dataforseo.com/v2/cmn_se ,
// "loc_id": https://api.dataforseo.com/v2/cmn_locations )
// If a task was set successfully, this *_id will be returned in results: 'v2/srp_html_tasks_post' so you can use it.
// The setting of a task can fail, if you set not-existent search engine, for example.
// Disadvantages: The process of search and comparison of provided data to our internal parameters may take some time.
$my_unq_id = mt_rand(0, 30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "se_name" => "google.co.uk",
    "se_language" => "English",
    "loc_name_canonical" => "London,England,United Kingdom",
    "key" => mb_convert_encoding("online rank checker", "UTF-8")
);

// example #3 - the fastest one. All parameters should be set in our internal format.
// Actual and fresh list can be found here: "se_id": https://api.dataforseo.com/v2/cmn_se ,
// "loc_id": https://api.dataforseo.com/v2/cmn_locations
$my_unq_id = mt_rand(0, 30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "se_id" => 22,
    "loc_id" => 1006886,
    "key_id" => 1095202
);

// This example has a 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
if (count($post_array) > 0) {
    try {
        // POST /v2/srp_html_tasks_post/$tasks_data
        // $tasks_data must by array with key 'data'
        $task_post_result = $client->post('v2/srp_html_tasks_post', array('data' => $post_array));
        print_r($task_post_result);

        //do something with post results

        $post_array = array();
    } catch (RestClientException $e) {
        echo "\n";
        print "HTTP code: {$e->getHttpCode()}\n";
        print "Error code: {$e->getCode()}\n";
        print "Message: {$e->getMessage()}\n";
        print  $e->getTraceAsString();
        echo "\n";
    }
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 3,
    "results": {
        "20469414": {
            "status": "ok",
            "post_id": 20469414,
            "post_key": "online rank checker",
            "task_id": 348906716,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202
        },
        "6273173": {
            "status": "ok",
            "post_id": 6273173,
            "post_key": "online rank checker",
            "task_id": 348908817,
            "se_id": 22,
            "loc_id": 9041110,
            "key_id": 1095202
        },
        "19840083": {
            "status": "ok",
            "post_id": 19840083,
            "post_key": "online rank checker",
            "task_id": 348909840,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202
        }
    }
}

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. We recommend to set up to 100 tasks at a time. Such limits were set due to the variations of task setting methods that you may use.

If you use the url field, then the processing of each task will take more time. If you use our system identifiers (se_id, loc_id, key_id), the processing of tasks will be faster.

You can also retrieve the results of completed tasks using the unique task identifier task_id. Alternatively, we can send them to you as soon as they are ready if you specify the postback_url or pingback_url when setting a task. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

Below you will find a detailed description of the fields you can use for setting a task.

Description of the fields for setting a task:

Field name Type Description
priority integer execution priority
optional field
can have the following values:
1 – normal execution priority (set by default)
2 – high execution priority

url string direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
se_id integer search engine id
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
also, when the information about set task is returned, you will get the se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_name by making a separate request to the List of Search Engines
example: “google.co.uk”
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with se_language by making a separate request to the List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
key_id integer keyword id
optional field if you specify key
when you set a task for the first time you won’t be able to know this field. But if you plan to collect rankings for this keyword, we recommend saving the key_id returned after the task was set, and use this field to get the results later on.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”if this field contains ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’ then the charge per task will be multiplied by 10.
se_param_add string additional parameters of the search query
optional field
for example, if you want to disable auto-correction of the search query misspelling for Google, you should use the “&nfpr=1” parameter
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify the postback URL there will be no need to use Get SERP HTML Task Results for obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$task_id’ string as a $task_id variable and ‘$post_id’ as $post_id variable. We will set the necessary values before sending the request. For example:
http://your-server.com/pingscript?taskId=$task_id
http://your-server.com/pingscript?taskId=$task_id&postId=$post_id


When setting a task, you send its data in the array using data fields. The index of the task in this array ($my_unq_id variable in examples) can be used at any time after that, as the post_id field. It will be returned to you with all server responses as well as our unique task_id field. Thanks to this feature, you can use this field to associate the set tasks with identifiers in your system.

Here are some examples:

  1. There is an identifier in your system that corresponds to a task that you set to collect data, for example, 100500. When you set the task you send it in the data array with 100500 index, e.g.: "{"data":{"100500":{"priority":1,"se_name":"google.co.uk","se_language":"English","loc_name_canonical":"London,England,United Kingdom","key":"online rank tracker"}}}"
    When you get a result of this task, 100500 will be returned in the post_id field, and you will be able to associate the received result with the task specified in your system.
  2. You may also want to associate other kinds of data in your system. For instance:
    • a keyword has id=1238 at your system,
    • a search engine has id=43289,
    • a location id=97435,
    • a language id=2,
    • a user for whom you want to complete this task has id=9999.

    Since the index of a task in the data array can be specified as a string, you can create this index using any symbol as a delimiter that fits you the most to send the information mentioned above as a post_id. For instance, let’s see how it will look like if we use # as a delimiter. The index that includes all the necessary data will have this value 1238#43289#97435#2#9999. As a result, the request for setting a task will look like this: "{"data":{"1238#43289#97435#2#9999":{"priority":1,"se_name":"google.co.uk","se_language":"English","loc_name_canonical":"London,England,United Kingdom","key":"online rank tracker"}}}"
    When you get the result of this task, you will be able to put in order the string to get the values you need. It will make the integration with our service easier for you.

As a response of the API server, you will receive JSON array in the results field  of which there will be an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
      status string results of this task setting
“ok” – success
“error” – error
if status=“error”, check the error array for more details
      error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
         code integer error code
         message string text description of the error
      post_id string the index in the array received in the POST request
      post_key string key received in the POST request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      se_id integer search engine id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task

‌‌
Possible error codes:

Error Code Meaning
404 “not found or not enough data: search engine” – you’ve specified a nonexistent se_id or a search engine according to the specified se_name wasn’t found
404 “not found or not enough data: location” – you’ve specified a nonexistent loc_id or the location of the search engine according to the specified loc_name_canonical wasn’t found
404 “not enough data: keyword” – you didn’t specify a keyword in the task
501 “invalid ‘data’ field” – probably you haven’t passed data for the tasks in the data field. POST data should be represented as an array and added to the data field: array(‘data’ => $post_array_for_tasks)
501 “invalid data” – data in the data field isn’t an array with the required structure.
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get SERP HTML Completed Tasks

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com', null, 'login', 'password');

    // #1 - get task_id list of ALL ready results
    //GET /v2/srp_html_tasks_get
    $tasks_get_result = $client->get('v2/srp_html_tasks_get');
    print_r($tasks_get_result);

    //get tasks one by one

} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1104 sec.",
    "results_count": 1,
    "results": [
        {
            "status": "ok",
            "post_id": "2365896",
            "task_id": 353729730,
            "post_key": "online ranksonic",
            "key_id": 67600559,
            "se_domain": "google.co.uk",
            "se_id": 22,
            "loc_id": 1006886
        }
    ]
}

You will get the list of completed tasks, the results of which haven’t been collected yet. Note that after you make a new call to this endpoint, all task_id received as a result of the previous call will be permanently removed from this list of completed tasks in order to avoid duplication.

If you specify pingback_url or postback_url you don’t have to use srp_html_tasks_get to get the list of completed tasks. Our system will send a GET request to the pingback_url or a POST request with the results to the postback_url.

Please note that if you specify the postback_url or pingback_url field, the task will not be in the list of completed tasks. The task can only be found in the list only if your server returned HTTP code response less than 200 or higher than 300.

As a response of the API server, you will receive an array in the results field containing a list of completed results.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      post_id string the index in the array received in the POST request
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 7 days to request the results of the task at any time
      post_key string key received in the POST request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
      se_domain string search engine domain
      se_id integer search engine id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines

Get SERP HTML Results by task_id

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com', null, 'login', 'password');

    // #1 - get task_id list of ALL ready results
    //GET /v2/srp_html_tasks_get
    $tasks_get_result = $client->get('v2/srp_html_tasks_get');
    print_r($tasks_get_result);
    if ($tasks_get_result["status"] == "ok") {
        foreach($tasks_get_result["results"] as $tasks_get_row) {
            // #2 - get result by task_id
            //GET /v2/srp_html_tasks_get/$task_id
            $serp_result = $client->get('v2/srp_html_tasks_get/'.$tasks_get_row["task_id"]);
            print_r($serp_result);

            //do something with results
        }
    }
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1766 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "2365896",
            "task_id": 348909840,
            "keyword": "online rank checker",
            "se_domain": "google.co.uk",
            "country": "GB",
            "device": "desktop",
            "html": [
                [
                    "<!doctype html> ... </html>"
                ]
            ]
        }
    ]
}

Description of the fields for sending a request:

Field name Type Description
task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 7 days to request the results of this task at any time.
param string additional parameter
allowed values:
normalized in this case an html page will be retrieved without any styles and scripts
if this parameter is not specified, you will receive a complete html page


You will receive an array from the API server in the results field where you will find SERP API results.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more information
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the array of results
results array results array of tasks setting
      post_id string the index of the array received in the POST array
      task_id integer unique task identifier in our system(UInt64)
in the future you will be able to use it within 7 days to request results of this task any time. You are charged for each GET request for results receiving.
      keyword string keyreceived in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      se_domain string search engine domain
      country string ISO country code
      device string device
      html array results array
result array containing the html page

‌‌
Possible error codes:

Error Code Meaning
102 “task in queue” – the task is being enqueued to handling, please, try again later
201 “task handed” – the task has been received and sent to handling, please, try again later
202 “in progress” – the task is in the handling process, please, try again later
404 “search engine did not return results” – SERP is empty. Check if you have added key correctly
404 “top results not found” – there is no SERP with the specified parameters

Live Extra SERP

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com/', null, 'login', 'password');
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
    exit();
}

$post_array = array();

$my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "se_name" => "google.co.uk",
    "se_language" => "English",
    "loc_name_canonical"=> "London,England,United Kingdom",
    "key" =>  mb_convert_encoding("online rank checker", "UTF-8")
);

try {
    // POST /v2/live/srp_extra_tasks_post/$data
    // $tasks_data must by array with key 'data'
    $result = $client->post('v2/live/srp_extra_tasks_post', array('data' => $post_array));
    print_r($result);

    //do something with post results

    $post_array = array();
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1376 sec.",
    "results_count": 104,
    "results": [
        {
            "task_id": 629265414,
            "se_id": 14,
            "loc_id": 2840,
            "key_id": 4342117,
            "post_id": "here is supposed to be your post ID 1",
            "post_key": "bill gates",
            "result_se_check_url": "https:\/\/google.com\/search?q=bill%20gates&hl=en&gl=US&gws_rd=cr&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
            "result_datetime": "2018-05-22 12:27:21 +00:00",
            "result_spell": "",
            "result_spell_type": "",
            "result_extra": "top_stories,twitter,people_also_ask,knowledge_graph,videos",
            "result_serp_count": 450000000,
            "result": {
                "left": [
                    {
                        "type": "top_stories",
                        "position": 1,
                        "items": [
                            {
                                "url": "http:\/\/www.businessinsider.com\/bill-gates-summer-reading-recommendations-2018-5",
                                "title": "These are the 5 books Bill Gates recommends you read this summer",
                                "date": "47 mins ago",
                                "source": "CNBC.com"
                            },
                            {
                                "url": "https:\/\/qz.com\/1282604\/your-summer-reading-list-provided-by-bill-gates-2\/",
                                "title": "Your summer reading list, provided by Bill Gates",
                                "date": "47 mins ago",
                                "source": ""
                            },
                            {
                                "url": "https:\/\/www.cnbc.com\/2018\/05\/22\/bill-gates-is-betting-on-this-synthetic-biology-start-up.html",
                                "title": "Why Bill Gates is betting on a start-up that prints synthetic DNA",
                                "date": "",
                                "source": "CNBC.com"
                            }
                        ]
                    },
                    {
                        "type": "organic",
                        "position": 2,
                        "featured_snippet": false,
                        "image": false,
                        "video": false,
                        "url": "https:\/\/en.wikipedia.org\/wiki\/Bill_Gates",
                        "breadcrumb": "https:\/\/en.wikipedia.org\/wiki\/Bill_Gates",
                        "title": "Bill Gates - Wikipedia",
                        "snippet": "William Henry Gates III (born October 28, 1955) is an American business magnate, investor, author, philanthropist, humanitarian, and principal founder of ...",
                        "snippet_extra": "",
                        "links": [],
                        "stat": {
                            "rating": 4.5,
                            "rating_max": 5
                        },
                        "highlighted": [
                            "William",
                            "Gates"
                        ]
                    },
                    {
                        "type": "twitter",
                        "position": 3,
                        "url": "https://twitter.com/BillGates",
                        "title": "Bill Gates (@BillGates) · Twitter",
                        "items": [
                            {
                                "url": "https:\/\/twitter.com\/BillGates\/status\/998593941762199552",
                                "tweet": "From Lincoln to Leonardo, I hope you enjoy my summer reading list. b-gat.es\/2s4hobZ",
                                "date": "20 hours ago"
                            },
                            {
                                "url": "https:\/\/twitter.com\/BillGates\/status\/997168620802199552",
                                "tweet": "At @MDCollege, smarter advising is helping students go further faster. pic.twitter.com\/iWuEG8B…",
                                "date": "5 days ago"
                            },
                            {
                                "url": "https:\/\/twitter.com\/BillGates\/status\/997084318982901760",
                                "tweet": "Glad to see this story told. I’m always inspired by the local leaders and health workers involved in the fight to #endpolio. b-gat.es\/2rLwl29",
                                "date": "5 days ago"
                            },
                            {
                                "url": "https:\/\/twitter.com\/BillGates\/status\/996862856883826690",
                                "tweet": "In the early days of Microsoft, I felt pretty confident about my coding skills, but I had a lot to learn about management. I wish I had @johndoerr’s new book back then. b-gat.es\/2GoSeZQ",
                                "date": "6 days ago"
                            },
                            {
                                "url": "https:\/\/twitter.com\/BillGates\/status\/996793962793848832",
                                "tweet": "France has been a leading champion in the fight against HIV\/AIDS, TB, and malaria.  Their generosity has helped us make terrific progress. twitter.com\/EmmanuelMac…",
                                "date": "6 days ago"
                            }
                        ]
                    },
                    {
                        "type": "local_pack",
                        "position": 4,                        
                        "title": "Pizza Express",
                        "snippet": "Longtime pizza chain known for delivery",
                        "phone": "586-235-584",
                        "rating": 3.8,
                        "rating_type": "stars",
                        "rating_max": 5,
                        "url": "",
                        "paid": true
                    },
                    {
                        "type": "local_pack",
                        "position": 5,
                        "title": "Pizza Pilgrims",
                        "snippet": "Retro-style slice & pie joint",
                        "phone": "",
                        "rating": 4,
                        "rating_type": "stars",
                        "rating_max": 5,
                        "url": "",
                        "paid": false
                    },
                    {
                        "type": "local_pack",
                        "position": 6,
                        "title": "Pizza Hut Restaurants",
                        "snippet": "Thin-crust pizzas & Stone Street seating",
                        "phone": "",
                        "rating": 4.3,
                        "rating_type": "stars",
                        "rating_max": 5,
                        "url": "",
                        "paid": false
                    },                    
                    {
                        "type": "images",
                        "position": 7,
                        "url": "https://www.google.com/search?q=search+volume&num=100&hl=en&gl=US&tbm=isch&tbo=u&source=univ&sa=X&ved=2ahUKEwjnl5PpgL_cAhVBElAKHTOYB_cQsAR6BAhSEAE",
                        "title": "Images for search volume",
                        "items": [
                            {
                                "url": "https://www.wordstream.com/blog/ws/2017/01/23/keyword-search-volume",
                                "alt": "Image result for search volume"
                            },
                            {
                                "url": "https://searchengineland.com/importance-monthly-versus-rolling-average-search-volume-225179",
                                "alt": "Image result for search volume"
                            },
                            {
                                "url": "https://ahrefs.com/blog/keyword-search-volume/",
                                "alt": "Image result for search volume"
                            }
                        ]
                    },
                    {
                        "type": "organic",
                        "position": 8,
                        "featured_snippet": false,
                        "image": false,
                        "video": false,
                        "url": "https:\/\/www.entrepreneur.com\/article\/197526",
                        "breadcrumb": "https:\/\/www.entrepreneur.com\/article\/197526",
                        "title": "Bill Gates Biography - Entrepreneur",
                        "snippet": "Bill Gates. Co-founder of Microsoft Corp. Founded: 1975. \"Ultimately, the PC will be a window to everything people are interested in-and everything we need to ...",
                        "snippet_extra": "",
                        "links": [],
                        "stat": {
                            "rating": 4.5,
                            "rating_max": 5
                        },
                        "highlighted": [
                            "Bill Gates"
                        ]
                    },
                    {
                        "type": "organic",
                        "position": 9,
                        "featured_snippet": false,
                        "image": false,
                        "video": false,
                        "url": "https:\/\/www.forbes.com\/profile\/bill-gates\/",
                        "breadcrumb": "https:\/\/www.forbes.com\/profile\/bill-gates\/",
                        "title": "Bill Gates - Forbes",
                        "snippet": "With his wife Melinda, Bill Gates chairs the Bill & Melinda Gates Foundation, the world's largest private charitable foundation. The foundation works to save lives ...",
                        "snippet_extra": "",
                        "links": [],
                        "stat": [],
                        "highlighted": [
                              "Bill Gates"
                        ]
                    },
                    {
                        "type": "featured_snippet",
                        "position": 10,
                        "url": "https://www.myprotein.com/thezone/nutrition/pre-workout-foods/",
                        "title": "Top 10 Pre Workout Foods - Myprotein",
                        "snippet": "Eating a banana pre-workout is the perfect way to boost your glycogen stores and increase blood sugar levels.Chicken, Rice &amp; Vegetables. ... Greek Yogurt and Dried Fruit. ... Porridge and Oatmeal.Fruit Smoothies.Wholegrain Bread, Sweet Potato and Brown Rice. ... Apple Wedges and Peanut Butter.Omelette.Homemade Protein Bars.More items...",
                        "table": {
                            "table_header": [
                              "Rank",
                              "Country",
                              "GDP (US$MM)"
                            ],
                            "table_data": [
                                [
                                "1",
                                "United States",
                                "19,390,600"
                                ],
                                [
                                "—",
                                "European Union",
                                "17,308,862"
                                ],
                                [
                                "2",
                                "China",
                                "12,014,610"
                                ],
                                [
                                "3",
                                "Japan",
                                "4,872,135"
                                ]
                            ]
                        }
                    },
                    {
                        "type": "people_also_ask",
                        "position": 11,
                        "items": [
                            {
                                "title": "How much does Bill Gates make in a day?",
                                "snippet_definition": "Search for: How much does Bill Gates make in a day?",
                                "snippet_title": "What Warren Buffett Makes Per Hour - Business Insider",
                                "snippet_url": "https://www.businessinsider.com/what-warren-buffett-makes-per-hour-2013-12",
                                "snippet_domain": "www.businessinsider.com"
                            },
                            {
                                "title": "How did Bill Gates get rich?",
                                "snippet_definition": "Search for: How did Bill Gates get rich?",
                                "snippet_title": "How did Bill Gates become so rich? - Quora",
                                "snippet_url": "https://www.quora.com/How-did-Bill-Gates-become-so-rich",
                                "snippet_domain": "www.quora.com"
                            },
                            {
                                "title": "What did Bill Gates invent?",
                                "snippet_definition": "Search for: What did Bill Gates invent?",
                                "snippet_title": "Bill Gates - Microsoft, Family, Quotes &amp; Philanthropy - Biography",
                                "snippet_url": "https://www.biography.com/business-figure/bill-gates",
                                "snippet_domain": "www.biography.com"
                            },
                            {
                                 "title": "What religion is Bill Gates?",
                                 "snippet_definition": "Search for: What religion is Bill Gates?",
                                 "snippet_title": "Bill Gates - Wikipedia",
                                 "snippet_url": "https://en.m.wikipedia.org/wiki/Bill_Gates",
                                 "snippet_domain": "en.m.wikipedia.org"
                            }
                        ]
                    },
                    {
                        "type": "organic",
                        "position": 12,
                        "featured_snippet": false,
                        "image": false,                        
                        "video": false,
                        "url": "https:\/\/www.gatesfoundation.org\/",
                        "breadcrumb": "https:\/\/www.gatesfoundation.org\/",
                        "title": "Bill & Melinda Gates Foundation",
                        "snippet": "We seek to unlock the possibility inside every individual. We see equal value in all lives. And so we are dedicated to improving the quality of life for individuals ...",
                        "snippet_extra": "",
                        "links": [],
                        "stat": [],
                        "highlighted": [
                            "Bill Gates"
                        ]
                    },
                    {
                        "type": "app",
                        "position": 13,
                        "items": [
                            {
                                "url": "https://play.google.com/store/apps/details?id=com.rovio.angrybirds&amp;hl=en_US&amp;referrer=utm_source%3Dgoogle%26utm_medium%3Dorganic%26utm_term%3Dangry+birds&amp;pcampaignid=APPU_1_8dheW9-JG4T85gLY05XgBw",
                                "title": "Angry Birds Classic",
                                "snippet": "",
                                "price": "Free"
                            },
                            {
                                "url": "https://play.google.com/store/apps/details?id=com.rovio.baba&amp;hl=en_US&amp;referrer=utm_source%3Dgoogle%26utm_medium%3Dorganic%26utm_term%3Dangry+birds&amp;pcampaignid=APPU_1_8dheW9-JG4T85gLY05XgBw",
                                "title": "Angry Birds 2",
                                "snippet": "",
                                "price": "Free"
                            },
                            {
                                "url": "https://play.google.com/store/apps/details?id=com.rovio.angrybirds&amp;hl=en&amp;referrer=utm_source%3Dgoogle%26utm_medium%3Dorganic%26utm_term%3Dangry+birds&amp;pcampaignid=APPU_1_8dheW9-JG4T85gLY05XgBw",
                                "title": "Angry Birds Classic",
                                "snippet": "",
                                "price": "Free"
                            }
                        ]
                    },
                    {
                        "type": "shopping",
                        "position": 14,
                        "title": "See DJI drones Phantom 4",
                        "items": [
                            {
                                "title": "DJI - Phantom 4 Pro Quadcopter - White",
                                "url": "https://www.googleadservices.com/pagead/aclk?sa=L&ai=DChcSEwit-a_ZrsncAhWBRIYKHVqdDC8YABADGgJ2dQ&ohost=www.google.com&cid=CAESEeD2TJLZEEFtglErOeHihIjI&sig=AOD64_2fMvHZkISwzvLaq0IzQ9as_Rr9lQ&ctype=5&q=&ved=0ahUKEwiywqjZrsncAhXImVkKHSp5DH4Q9aACCDI&adurl=",
                                "price": "$1,499.99",
                                "source": "Best Buy"
                            },
                            {
                                "title": "Case Club DJI Phantom 4 Compact Drone Case",
                                "url": "https://www.googleadservices.com/pagead/aclk?sa=L&ai=DChcSEwit-a_ZrsncAhWBRIYKHVqdDC8YABAFGgJ2dQ&ohost=www.google.com&cid=CAESEeD2TJLZEEFtglErOeHihIjI&sig=AOD64_06CGFLjkrAKAIsMsLXMubmtkaO3A&ctype=5&q=&ved=0ahUKEwiywqjZrsncAhXImVkKHSp5DH4Qww8INw&adurl=",
                                "price": "$129.95",
                                "source": "Case Club"
                            },
                            {
                                "title": "DJI Phantom 4 Quadcopter Drone FPV Virtual Reality Experience w/ Hardshell Backpack",
                                "url": "https://www.googleadservices.com/pagead/aclk?sa=L&ai=DChcSEwit-a_ZrsncAhWBRIYKHVqdDC8YABAHGgJ2dQ&ohost=www.google.com&cid=CAESEeD2TJLZEEFtglErOeHihIjI&sig=AOD64_15G0VZmDqYvzfro9BiC08HEzSQMQ&ctype=5&q=&ved=0ahUKEwiywqjZrsncAhXImVkKHSp5DH4Qww8IPA&adurl=",
                                "price": "$899.00",
                                "source": "BeachCamera...."
                            }
                        ]
                    },
                    {
                        "type": "answer_box",
                        "position": 15,
                        "text": [
                            "https://www.youtube.com/watch?v=-d7eYGLaiFk",
                            "OJO NGUBER WELAS - NELLA KHARISMA - YouTube",
                            "Artis",
                            "Nella Kharisma",
                            "Album",
                            "Melon Best Nella - Rupo Lan Dunyo",
                            "Dirilis",
                            "2016"
                        ],
                        "links": [
                            {
                                "url": "https://www.youtube.com/watch?v=-d7eYGLaiFk",
                                "anchor": "OJO NGUBER WELAS - NELLA KHARISMA - YouTube"
                            }
                        ]
                    },
                    {
                        "type": "map",
                        "position": 16,
                        "url": "https://www.google.com/maps/place/Andes/data=!4m2!3m1!1s0x968792fc5a4e9d2f:0x8b16530d02147954?hl=en&sa=X&ved=2ahUKEwjhw_q_sMncAhXGqFkKHY3cCDYQ8gEwAHoECAQQAQ",
                        "title": "Andes"
                    },
                    {
                        "type": "video",
                        "position": 17,
                        "items": [
                            {
                                "url": "https://www.noticiasagricolas.com.br/videos/boi/218168-entrevista-com-frederico-borges-stella-presidente-do-sindicato-rural-de-aquidauana-ms.html",
                                "title": "Preços da arroba do boi em Aquidauana-MS reagem com recuo da oferta, mas \nainda estão abaixo das necessidades dos pecuaristas",
                                "source": "Notícias Agrícolas"
                            },
                            {
                                "url": "http://g1.globo.com/mato-grosso-do-sul/mstv-1edicao/videos/t/edicoes/v/jovem-confessa-que-matou-e-congelou-corpo-de-idoso-em-aquidauana/6853090/",
                                "title": "Jovem confessa que matou e congelou corpo de idoso em ...",
                                "source": "G1 - Globo.com"
                            },
                            {
                                "url": "http://g1.globo.com/mato-grosso-do-sul/mstv-1edicao/videos/v/aquidauana-tem-casas-alagadas-e-rodovia-interditada/6517826/",
                                "title": "Aquidauana tem casas alagadas e rodovia interditada - G1 Mato ...",
                                "source": "G1 - Globo.com"
                            }
                        ]
                    },
                    {
                        "type": "google_flights",
                        "position": 18,
                        "title": "Flights from London, United Kingdom (all airports) to Berlin, Germany (all airports)",
                        "url": "https://www.google.com/flights?num=100&hl=en&source=flun&lite=0&uitype=cuAA&tfs=CAEQAhooEgoyMDE4LTA5LTIwagwIAhIIL20vMDRqcGxyDAgCEggvbS8wMTU2cRooEgoyMDE4LTA5LTIzagwIAhIIL20vMDE1NnFyDAgCEggvbS8wNGpwbA&sa=X&ved=2ahUKEwjigrv43MncAhWLxKYKHbGMB7sQuRUwAHoECAYQAw",
                        "items": [
                            {
                                "url": "https://www.google.com/flights?num=100&amp;hl=en&amp;source=flun&amp;lite=0&amp;uitype=cuAA&amp;tfs=CAEQAhouEgoyMDE4LTA5LTIwKAAyAkZSagwIAhIIL20vMDRqcGxyDAgCEggvbS8wMTU2cRouEgoyMDE4LTA5LTI0KAAyAkZSagwIAhIIL20vMDE1NnFyDAgCEggvbS8wNGpwbA&amp;sa=X&amp;ved=2ahUKEwjXwufGzr_cAhUK66QKHcaOBboQ1RUoADAAegQIBBAQ",
                                "description": "Ryanair     1h 50m  Non-stop     from €66"
                            },
                            {
                                "url": "https://www.google.com/flights?num=100&amp;hl=en&amp;source=flun&amp;lite=0&amp;uitype=cuAA&amp;tfs=CAEQAhouEgoyMDE4LTA5LTIwKAAyAlUyagwIAhIIL20vMDRqcGxyDAgCEggvbS8wMTU2cRouEgoyMDE4LTA5LTI0KAAyAlUyagwIAhIIL20vMDE1NnFyDAgCEggvbS8wNGpwbA&amp;sa=X&amp;ved=2ahUKEwjXwufGzr_cAhUK66QKHcaOBboQ1RUoATAAegQIBBAR",
                                "description": "easyJet     1h 50m  Non-stop     from €74"
                            },
                            {
                                "url": "https://www.google.com/flights?num=100&amp;hl=en&amp;source=flun&amp;lite=0&amp;uitype=cuAA&amp;tfs=CAEQAhouEgoyMDE4LTA5LTIwKAAyAkVXagwIAhIIL20vMDRqcGxyDAgCEggvbS8wMTU2cRouEgoyMDE4LTA5LTI0KAAyAkVXagwIAhIIL20vMDE1NnFyDAgCEggvbS8wNGpwbA&amp;sa=X&amp;ved=2ahUKEwjXwufGzr_cAhUK66QKHcaOBboQ1RUoAjAAegQIBBAS",
                                "description": "Eurowings     1h 50m  Non-stop     from €119"
                            }
                        ]
                    },
                   {
                        "type": "jobs",
                        "position": 19,
                        "title": "Jobs Near Philadelphia, PA",
                        "url": "",
                        "items": [
                            {
                                "title": "Cleaner",
                                "url": "https://www.google.com.ua/search?hl=en&ei=zOxVW8m8F6rM6ATM4YaACw&q=philadelphia+department+of+health+jobs++++++++++++++++++++++++&oq=philadelphia+department+of+health+jobs++++++++++++++++++++++++&gs_l=psy-ab.12..0i22i30k1l3.13420.13420.0.14496.1.1.0.0.0.0.96.96.1.1.0....0...1c.1.64.psy-ab..0.1.95....0.fnNOCW1bsw4&ibp=htl;jobs#htidocid=CPe0N2zxBNIkWYd4AAAAAA%3D%3D",
                                "snippet": "Public Health Management Corporation",
                                "author": "via ZipRecruiter",
                                "date": "Over 1 month ago",
                                "type": "Contractor"
                            },
                            {
                                "title": "Morning Cleaner",
                                "url": "https://www.google.com.ua/search?hl=en&ei=zOxVW8m8F6rM6ATM4YaACw&q=philadelphia+department+of+health+jobs++++++++++++++++++++++++&oq=philadelphia+department+of+health+jobs++++++++++++++++++++++++&gs_l=psy-ab.12..0i22i30k1l3.13420.13420.0.14496.1.1.0.0.0.0.96.96.1.1.0....0...1c.1.64.psy-ab..0.1.95....0.fnNOCW1bsw4&ibp=htl;jobs#htidocid=oR8qq-x07ejC09RFAAAAAA%3D%3D",
                                "snippet": "Temple University College of Public Health",
                                "author": "via ChronicleVitae",
                                "date": "4 days ago",
                                "type": "Full-time"
                            },
                            {
                                "title": "Full-time Cleaner",
                                "url": "https://www.google.com.ua/search?hl=en&ei=zOxVW8m8F6rM6ATM4YaACw&q=philadelphia+department+of+health+jobs++++++++++++++++++++++++&oq=philadelphia+department+of+health+jobs++++++++++++++++++++++++&gs_l=psy-ab.12..0i22i30k1l3.13420.13420.0.14496.1.1.0.0.0.0.96.96.1.1.0....0...1c.1.64.psy-ab..0.1.95....0.fnNOCW1bsw4&ibp=htl;jobs#htidocid=ijfp0BQIh6eWdTolAAAAAA%3D%3D",
                                "snippet": "Pepper Hamilton",
                                "author": "via Glassdoor",
                                "date": "27 days ago",
                                "type": "Full-time"
                            }
                        ]
                    },
                    {
                        "type": "carousel",
                        "position": 20,
                        "title": "Backup Software",
                        "items": [
                            {
                                "title": "Backup and RestoreProprietary software",
                                "sub_title": "Cambridge"
                            },
                            {
                                "title": "Acronis True ImageProprietary software",
                                "sub_title": "Los Angeles"
                            },
                            {
                                "title": "Macrium ReflectFreeware",
                                "sub_title": "New York"
                            },
                            {
                                "title": "System Restore",
                                "sub_title": "New York"
                            }
                        ]
                    },
                    {
                        "type": "organic",
                        "position": 99,
                        "featured_snippet": false,
                        "image": true,
                        "video": false,
                        "url": "https://www.microsoft.com/en-us/store/b/home",
                        "breadcrumb": "https://www.microsoft.com/en-us/store/b/home",
                        "title": "Microsoft Store Online",
                        "snippet": "At Microsoft our mission and values are to help people and businesses throughout the world realize their full potential.",
                        "snippet_extra": "",
                        "links": [
                            {
                                "title": "Microsoft Store Online",
                                "url": "https://www.microsoft.com/en-us/store/b/home",
                                "snippet": "Microsoft Store OnlinePCs - Xbox - Xbox Games - Download Windows 10 - ..."
                            },
                            {
                                "title": "Windows 10",
                                "url": "https://www.microsoft.com/en-us/windows",
                                "snippet": "Windows 10Windows 10 unveils new innovations & is better than ever ..."
                            }
                        ],
                        "stat": [],
                        "highlighted": []
                    },
                    {
                        "type": "paid",
                        "position": 100,
                        "url": "https://www.booking.com/city/gb/london.html",
                        "title": "2880 Hotels in London | Lowest Price Guarantee | booking.com",
                        "snippet_row1": "Book for Tomorrow",
                        "snippet_row2": "",
                        "links": [],
                        "stat": [],
                        "highlighted": [
                             "Bill",
                             "Gates"
                        ]
                    },
                    {
                        "type": "organic",
                        "position": 101,
                        "featured_snippet": false,
                        "image": false,                        
                        "video": false,
                        "url": "https:\/\/blogs.scientificamerican.com\/observations\/bill-gates-in-search-of-nuclear-nirvana\/",
                        "breadcrumb": "https:\/\/blogs.scientificamerican.com\/observations\/bill-gates-in-search-of-nuclear-nirvana\/",
                        "title": "Bill Gates in Search of Nuclear Nirvana - Scientific American Blog ...",
                        "snippet": "May 2, 2018 - Bill Gates originally became famous (and rich) for co-founding Microsoft; more recently, he's become better known, through the Bill and Melinda ...",
                        "snippet_extra": "",
                        "links": [],
                        "stat": [],
                        "highlighted": []
                    },
                    {
                        "type": "organic",
                        "position": 102,
                        "featured_snippet": false,
                        "image": false,                        
                        "video": false,
                        "url": "https:\/\/www.recode.net\/2018\/5\/14\/17350538\/john-doerr-measure-what-matters-book-kleiner-perkins-okrs-kara-swisher-teddy-schleifer-podcast",
                        "breadcrumb": "https:\/\/www.recode.net\/2018\/5\/14\/17350538\/john-doerr-measure-what-matters-book-kleiner-perkins-okrs-kara-swisher-teddy-schleifer-podcast",
                        "title": "Kleiner Perkins' John Doerr explains how to run your company like Bill ...",
                        "snippet": "May 14, 2018 - ... (in which he was an early investor), the Bill & Melinda Gates Foundation and the One Campaign, a nonprofit founded by U2 frontman Bono.",
                        "snippet_extra": "",
                        "links": [],
                        "stat": [],
                        "highlighted": []
                    },
                    {
                        "type": "related_search",
                        "position": 103,
                        "title": "airports in berlin",
                        "items": [
                            "Berlin Schönefeld Airport",
                            "Berlin Brandenburg Airport",
                            "Berlin Tegel Airport",
                            "Berlin Tempelhof Airport",
                            "Berlin Hauptbahnhof",
                            "RAF Gatow",
                            "Johannisthal Air Field"
                        ]
                    },
                    {
                        "type": "related_search",
                        "position": 104,
                        "title": "european airports",
                        "items": [
                            "London Stansted Airport",
                            "Manchester Airport",
                            "London City Airport",
                            "Luton Airport",
                            "Keflavík International Airport",
                            "Berlin Schönefeld Airport",
                            "Berlin Tegel Airport"
                        ]
                    },
                    {
                        "type": "related",
                        "position": 105,
                        "items": [
                            "london to berlin flight time",
                            "cheapest time to fly to berlin",
                            "easyjet flights to berlin",
                            "flight to berlin germany",
                            "london to berlin train",
                            "direct flights to berlin",
                            "london to berlin flight duration",
                            "best time to book flights to berlin"
                        ]
                    },
                    {
                        "type": "mention",
                        "position": 106,
                        "title": "Best Headphones &amp; Headsets",
                        "items": [
                            {
                                "title": "Apple EarPods",
                                "price": "$21+",
                                "rating": 4.3,
                                "rating_type": "max_5",
                                "count_ratings": 37817,
                                "mentioned_in": [
                                    {
                                        "title": "Best earbuds 2019: the best earbuds, earphones and in-ear headphones for any budget",
                                        "url": "https://www.techradar.com/news/audio/best-in-ear-headphones-1276925"
                                    },
                                    {
                                        "title": "Best headphones 2019: Your definitive guide to the latest and greatest audio",
                                        "url": "https://www.techradar.com/news/audio/portable-audio/best-headphones-1280340"
                                    }
                                ]
                            },
                            {
                                "title": "Sony WH-1000XM3",
                                "price": "$300+",
                                "rating": 4.7,
                                "rating_type": "max_5",
                                "count_ratings": 4115,
                                "mentioned_in": [
                                    {
                                        "title": "Best Headphones for 2019",
                                        "url": "https://www.cnet.com/topics/headphones/best-headphones/"
                                    },
                                    {
                                        "title": "Best over-ear headphones 2019: the best-sounding, most comfortable cans",
                                        "url": "https://www.techradar.com/news/audio/portable-audio/best-over-ear-headphones-1280342"
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "right": [
                    {
                        "type": "knowledge_graph",
                        "position": 1,
                        "url": "https:\/\/en.wikipedia.org\/wiki\/Bill_Gates",
                        "title": "Bill Gates",
                        "subtitle": "",
                        "description": "William Henry Gates III is an American business magnate, investor, author, philanthropist, humanitarian, and principal founder of Microsoft Corporation.",
                        "parts": [
                              {
                                  "text": "gatesnotes.com",
                                  "url": "https://www.gatesnotes.com/",
                                  "anchor": "gatesnotes.com"
                              },
                              {
                                  "text": "Description William Henry Gates III is an American business magnate, investor, author, philanthropist, and humanitarian. He is best known as the principal founder of Microsoft Corporation.   Wikipedia",
                                  "url": "https://en.wikipedia.org/wiki/Bill_Gates",
                                  "anchor": "Wikipedia"
                              },
                              {
                                  "text": "Born :  October 28, 1955 (age 63 years),  Seattle, WA",
                                  "url": "https://www.google.com/search?num=100&hl=en&gl=US&q=bill+gates+born&stick=H4sIAAAAAAAAAOPgE-LQz9U3MDTPK9ESy0620i9IzS_ISQVSRcX5eVZJ-UV5i1j5kzJzchTSE0tSixVAIgB7lxuyNgAAAA&sa=X&ved=2ahUKEwjykMulpp3hAhVPAHIKHT0EAlgQ6BMoADCKAXoECGMQBg",
                                  "anchor": "Born"
                              },
                              {
                                  "text": "Born :  October 28, 1955 (age 63 years),  Seattle, WA",
                                  "url": "https://www.google.com/search?num=100&hl=en&gl=US&q=Seattle&stick=H4sIAAAAAAAAAOPgE-LQz9U3MDTPK1ECs1Iss4q0xLKTrfQLUvMLclKBVFFxfp5VUn5R3iJW9uDUxJKSnFQA3EAC8jgAAAA&sa=X&ved=2ahUKEwjykMulpp3hAhVPAHIKHT0EAlgQmxMoATCKAXoECGMQBw",
                                  "anchor": "Seattle, WA"
                              },
                              {
                                  "text": "Net worth :  98.3 billion USD (2019)",
                                  "url": "https://www.google.com/search?num=100&hl=en&gl=US&q=bill+gates+net+worth&stick=H4sIAAAAAAAAAOPgE-LQz9U3MDTPK9GSzk620i9IzS_ISQVSRcX5eVZ5qSUK5flFJRmLWEWSMnNyFNITS1KLFeDCAM9_Xi1AAAAA&sa=X&ved=2ahUKEwjykMulpp3hAhVPAHIKHT0EAlgQ6BMoADCMAXoECGMQCg",
                                  "anchor": "Net worth"
                              },
                              {
                                  "text": "Spouse :  Melinda Gates  (m. 1994)",
                                  "url": "https://www.google.com/search?num=100&hl=en&gl=US&q=bill+gates+spouse&stick=H4sIAAAAAAAAAOPgE-LQz9U3MDTPK9GSyE620i9IzS_ISQVSRcX5eVbFBfmlxamLWAWTMnNyFNITS1KLFSBiAGKiWBc6AAAA&sa=X&ved=2ahUKEwjykMulpp3hAhVPAHIKHT0EAlgQ6BMoADCNAXoECGMQDQ",
                                  "anchor": "Spouse"
                              },
                              {
                                  "text": "Spouse :  Melinda Gates  (m. 1994)",
                                  "url": "https://www.google.com/search?num=100&hl=en&gl=US&q=Melinda+Gates&stick=H4sIAAAAAAAAAOPgE-LQz9U3MDTPK1ECs1JyC0y0JLKTrfQLUvMLclKBVFFxfp5VcUF-aXHqIlZe39SczLyURAX3xJLUYgAPK94WQAAAAA&sa=X&ved=2ahUKEwjykMulpp3hAhVPAHIKHT0EAlgQmxMoATCNAXoECGMQDg",
                                  "anchor": "Melinda Gates"
                              }
                        ],
                        "card_id": "/m/01zczs"
                    },
                    {
                        "type": "google_review",
                        "position": 2,
                        "reviews_count": 2657,
                        "place_id": "ChIJ6UCP2tygJ0ERRJmMWID1zMA"
                    }
                ]
            }
        }
    ]
}

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. You can set only one task at a time. If you use the url field, then the processing of each task will take more time. If you use our system identifiers (se_id, loc_id, key_id), the processing of tasks will be faster.

Below you will find a detailed description of the fields you can use for setting a task.

Description of the fields for setting a task:

Field name Type Description
se_id integer search engine id
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
also, when the information about set task is returned, you will get the se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_name by making a separate request to the List of Search Engines
example: “google.co.uk”
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with se_language by making a separate request to the List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
key_id integer keyword id
optional field if you specify key
when you set a task for the first time you won’t be able to know this field. But if you plan to collect rankings for this keyword, we recommend saving the key_id returned after the task was set, and use this field to get the results later on.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”if this field contains ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’ then the charge per task will be multiplied by 10.
se_param_add string additional parameters of the search query
optional field
for example, if you want to disable auto-correction of the search query misspelling for Google, you should use the “&nfpr=1” parameter
Get the list of available parameters and additional details here.
url string direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS


When setting a task, you send its data in the array using data fields. The index of the task in this array ($my_unq_id variable in examples) can be used at any time after that, as the post_id field. It will be returned to you with all server responses as well as our unique task_id field. Thanks to this feature, you can use this field to associate the set tasks with identifiers in your system.

As a response of the API server, you will receive JSON array in the results field of which there will be an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
      post_id string the index in the array received in the POST request
      se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines
      loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
      post_key string keyreceived in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      result_se_check_url string direct URL to search engine results
You can use it to make sure that we provided exact results
      result_datetime string date and time when the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
      result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
      result_spell_type string type of auto-correction
types of hints: did_you_mean, showing_results_for, no_results_found_for
      result_extra string additional (extra) elements in SERP
all extra elements in the string are separated by commas, e.g.: top_stories, featured_snippet, people_also_ask, local_pack, carousel, images, map, video, twitter, app, shopping, google_flights, jobs, answer_box, related_search, knowledge_graph, google_review, mention
      result_serp_count integer total number of results in SERP
      left array results array from the main body of the SERP with extra elements
you can find the following elements here: organicpaidtop_storiespeople_also_asklocal_packcarouselimagesvideomaptwitterappshoppinggoogle_flightsjobsanswer_boxrelated_searchrelatedmention
            ‘paid’ element in SERP
            type string type of element = ‘paid’
            position integer position in SERP
            url string relevant URL of the Ad element
            breadcrumb string breadcrumb of the Ad element
            title string snippet header of the Ad element
            snippet_row1 string first snippet row in the element
            snippet_row2 string second snippet row in the element
            links array links which are included in the SERP element snippet
                  url string relevant URL
                  title string snippet header
                  snippet string snippet
            stat array statistics
                  rating integer/float rating
the popularity rate based on reviews and displayed in SERPs
                  rating_max integer the maximum value for a rating
            highlighted array words highlighted in bold within the results snippet
            ‘organic’ element in SERP
            type string type of element = ‘organic’
            position integer position in SERP
            featured_snippet boolean indicates whether the element is a featured_snippet
            image boolean indicates whether the element has an image
            video boolean indicates whether the element has a video
            url string relevant URL in SERP
            breadcrumb string breadcrumb in SERP
            title string snippet header in SERP
            snippet string snippet in SERP
            snippet_extra string the enhanced snippet in SERP
For example: ratings, price, author, etc
            links array links which are included in the SERP element snippet
                  url string relevant URL
                  title string snippet header
                  snippet string snippet
            stat array statistics
                  rating integer/float rating
the popularity rate based on reviews and displayed in SERPs
                  rating_max integer the maximum value for a rating
            highlighted array words highlighted in bold within the results snippet
            ‘featured snippet’ element in SERP
            type string type of element = ‘featured_snippet’
            position integer position in SERP
            url string relevant URL in SERP
            title string snippet header in SERP
            snippet string snippet in SERP
            table array array of elements
                  table_header array array of table header strings
                  table_data array array of table row strings
            ‘top stories’ element in SERP
            type string type of element = ‘top_stories’
            position integer position in SERP
            items array items array
                  url string relevant URL of the element
                  title string title of the element
                  date string date of the element
                  source string source of the element
            ‘answer box’ element in SERP
            type string type of element = ‘answer_box’
            position integer position in SERP
            text array array of the string with text elements
            links array array of URLs
                  url string relevant URL
                  anchor string anchor for the URL
            ‘people also ask’ element in SERP
            type string type of element = ‘people_also_ask’
            position integer position in SERP
            items array array of ‘people also ask’ elements
                  title string ‘people also ask’ element title
                  snippet_definition string snippet definition of the element
                  snippet_title string snippet title of the element
                  snippet_url string snippet URL of the element
                  snippet_domain string snippet domain of the element
            ‘app’ element in SERP
            type string type of element = ‘app’
            position integer position in SERP
            items array applications array
                  url string relevant URL of the application
                  title string application title
                  snippet string application snippet
                  price string application price
            ‘carousel’ element in SERP
            type string type of element = ‘carousel’
            position integer position in SERP
            title string carousel title
            items array items array
                  title string title of the element
                  sub_title string subtitle of the element
            ‘local pack’ element in SERP
            type string type of element = ‘local_pack’
            position integer position in SERP
            url string relevant URL of the element
            title string snippet header of the element
            snippet string snippet of the element
            phone string phone in the element
            rating integer/float rating
the popularity rate based on reviews and displayed in SERPs
            rating_type string measurement units
shows which measurement units are used in the rating field
there are two possible options: starspercents
            rating_max integer the maximum value for a rating
            paid boolean paid advertisement
            ‘map’ element in SERP
            type string type of element = ‘map’
            position integer position in SERP
            url string relevant URL
            title string snippet header in SERP
            ‘twitter’ element in SERP
            type string type of element = ‘twitter’
            position integer position in SERP
            url string twitter homepage URL
            title string title from twitter
            items array items array
                  url string tweet’s URL
                  tweet string tweet message
                  date string tweet message date
            ‘shopping’ element in SERP
            type string type of element = ‘shopping’
            position integer position in SERP
            title string title of the product in Google Shopping
            items array items array
                  title string product title
                  url string product URL
                  price string product price
                  source string source
            ‘video’ element in SERP
            type string type of element = ‘video’
            position integer position in SERP
            items array array of the URL videos
                  url string URL of the video
                  title string video title
                  source string video source
            ‘images’ element in SERP
            type string type of element = ‘images’
            position integer position in SERP
            url string image URL
            title string image title
            items array array of the URL images
                  url string image URL
                  alt string  alt attribute
            ‘google flights’ element in SERP
            type string type of element = ‘google_flights’
            position integer position in SERP
            url string URL of current tickets
            title string title
            items array array of URLs
                  url string URL of this ticket
                  description string description
            ‘jobs’ element in SERP
            type string type of element = ‘jobs’
            position integer position in the SERP
            url string URL of current jobs
            title string title
            items array vacancies array
                  title string title of this vacancy
                  url string URL of this vacancy
                  snippet string snippet
                  author string author
                  date string date of this vacancy
                  type string work type
            ‘related search’ element in SERP
            type string type of element = ‘related_search’
            position integer position in SERP
            title string title of the related search element
            items array related keywords array
            ‘related’ element in SERP
            type string type of element = ‘related’
            position integer position in SERP
            items array related keywords array
            ‘mention’ element in SERP
            type string type of element = ‘mention’
            position integer position in SERP
            title string title
            items array array of mention items
                  title string item title
                  price string item price
                  rating float rating
the popularity rate based on reviews and displayed in SERPs
                  rating_type string measurement units
shows which measurement units are used in the rating field
                  count_ratings integer rating count
                  mentioned_in array array that contains a list of resources that mentioned the item
                        title string title
                        url string url
      right array results array on the right side of SERP with extra elements
you can find the following elements here: knowledge_graphgoogle review
            ‘knowledge graph’ element in SERP
            type string type of element = ‘knowledge_graph’
            position integer position in SERP
            url string relevant URL in SERP
            title string header in SERP
            subtitle string subtitle in SERP
            description string text of knowledge graph
            parts array array of knowledge graph text items
                  text string item text
                  url string relevant URL
                  anchor string anchor for the URL
            card_id string the knowledge graph id
            ‘google review’ element in SERP
            type string type of element = ‘google_review’
            position integer position in SERP
            reviews_count integer number of results in the reviews list
            place_id string place ID

‌‌
Possible error codes:

Error Code Meaning
404 “not found or not enough data: search engine” – you’ve specified a nonexistent se_id or a search engine according to the specified se_name wasn’t found
404 “not found or not enough data: location” – you’ve specified a nonexistent loc_id or a location of a search engine according to the specified loc_name_canonical wasn’t found
404 “not enough data: keyword” – you didn’t specify a keyword in the task
404 “search engine did not return results” – SERP is empty. Check if you have added key correctly
404 “top results not found” – there is no SERP with the specified parameters
501 “invalid ‘data’ field” – probably you haven’t passed data for the tasks in the data field. POST data should be represented as an array and added to the data field: array(‘data’ => $post_array_for_tasks)
501 “invalid data” – data in the data field isn’t an array with the required structure.
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Setting Extra SERP Tasks

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

$api_url = 'https://api.dataforseo.com/';
try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient($api_url, null, 'login', 'password');
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
    exit();
}

$post_array = array();

// example #1 - simplest
// you set only a website URL and a search engine URL.
// This search engine URL string will be searched, compared to our internal parameters
// and used as:
// "se_id", "loc_id", "key_id" ( actual and fresh list can be found here: "se_id":
// https://api.dataforseo.com/v2/cmn_se , "loc_id": https://api.dataforseo.com/v2/cmn_locations ) (see example #3 for details)
// If a task was set successfully, this *_id will be returned in results: 'v2/srp_extra_tasks_post' so you can use it.
// The setting of a task can fail, if you set not-existent search engine, for example.
// Disadvantages: You cannot work with "map pack", "maps", "mobile"
$my_unq_id = mt_rand(0, 30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "url" => "https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
);

// example #2 - will return results faster than #1, but is simpler than example #3
// All parameters should be set in the text format.
// All data will be will be searched, compared to our internal parameters
// and used as:
// "se_id", "loc_id", "key_id" ( actual and
// fresh list can be found here: "se_id": https://api.dataforseo.com/v2/cmn_se ,
// "loc_id": https://api.dataforseo.com/v2/cmn_locations )
// If a task was set successfully, this *_id will be returned in results: 'v2/srp_extra_tasks_post' so you can use it.
// The setting of a task can fail, if you set not-existent search engine, for example.
// Disadvantages: The process of search and comparison of provided data to our internal parameters may take some time.
$my_unq_id = mt_rand(0, 30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "se_name" => "google.co.uk",
    "se_language" => "English",
    "loc_name_canonical" => "London,England,United Kingdom",
    "key" => mb_convert_encoding("online rank checker", "UTF-8")
);

// example #3 - the fastest one. All parameters should be set in our internal format.
// Actual and fresh list can be found here: "se_id": https://api.dataforseo.com/v2/cmn_se ,
// "loc_id": https://api.dataforseo.com/v2/cmn_locations
$my_unq_id = mt_rand(0, 30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "se_id" => 22,
    "loc_id" => 1006886,
    "key_id" => 1095202
);

// This example has a 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
if (count($post_array) > 0) {
    try {
        // POST /v2/srp_extra_tasks_post/$tasks_data
        // $tasks_data must by array with key 'data'
        $task_post_result = $client->post('v2/srp_extra_tasks_post', array('data' => $post_array));
        print_r($task_post_result);

        //do something with post results

        $post_array = array();
    } catch (RestClientException $e) {
        echo "\n";
        print "HTTP code: {$e->getHttpCode()}\n";
        print "Error code: {$e->getCode()}\n";
        print "Message: {$e->getMessage()}\n";
        print  $e->getTraceAsString();
        echo "\n";
    }
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 9,
    "results": {
        "11913049": {
            "post_id": 11913049,
            "post_key": "online rank checker",
            "task_id": 404227822,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "20469414": {
            "post_id": 20469414,
            "post_key": "online rank checker",
            "task_id": 404227823,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "6273173": {
            "post_id": 6273173,
            "post_key": "online rank checker",
            "task_id": 404227824,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "27408598": {
            "post_id": 27408598,
            "post_key": "online rank checker",
            "task_id": 404227825,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "19840083": {
            "post_id": 19840083,
            "post_key": "online rank checker",
            "task_id": 404227826,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "6054604": {
            "post_id": 6054604,
            "post_key": "online rank checker",
            "task_id": 404227827,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "8626195": {
            "post_id": 8626195,
            "post_key": "",
            "task_id": 404227828,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "18786140": {
            "post_id": 18786140,
            "post_key": "online rank checker",
            "task_id": 404227829,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "13056693": {
            "post_id": 13056693,
            "post_key": "online rank checker",
            "task_id": 404227830,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        }
    }
}

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. We recommend to set up to 100 tasks at a time. Such limits were set due to the variations of task setting methods that you may use.

If you use the url field, then the processing of each task will take more time. If you use our system identifiers (se_id, loc_id, key_id), the processing of tasks will be faster.

You can also retrieve the results of completed tasks using the unique task identifier task_id. Alternatively, we can send them to you as soon as they are ready if you specify the postback_url or pingback_url when setting a task. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

Below you will find a detailed description of the fields you can use for setting a task.

Description of the fields for setting a task:

Field name Type Description
priority integer execution priority
optional field
can have the following values:
1 – normal execution priority (set by default)
2 – high execution priority

url string direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
se_id integer search engine id
optional field, if you specify se_name
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
also, when the information about set task is returned, you will get the se_id
currently available only for “google desktop” and “google mobile” . to get se_id for “google desktop” and “google mobile”, you must choose a search engine without any additional words (like “ maps”, “ map pack”, “ shopping”) included in the se_name
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_name by making a separate request to the List of Search Engines
example: “google.co.uk”
currently available only for “google desktop” and “google mobile” . to get se_id for “google desktop” and “google mobile”, you must choose a search engine without any additional words (like “ maps”, “ map pack”, “ shopping”) included in the se_name
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with se_language by making a separate request to the List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
key_id integer keyword id
optional field if you specify key
when you set a task for the first time you won’t be able to know this field. But if you plan to collect rankings for this keyword, we recommend saving the key_id returned after the task was set, and use this field to get the results later on.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”if this field contains ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’ then the charge per task will be multiplied by 10.
se_param_add string additional parameters of the search query
optional field
for example, if you want to disable auto-correction of the search query misspelling for google, you should use the “&nfpr=1” parameter
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify the postback URL there will be no need to use Get Extra SERP Results for obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$task_id’ string as a $task_id variable and ‘$post_id’ as $post_id variable. We will set the necessary values before sending the request. For example:
http://your-server.com/pingscript?taskId=$task_id
http://your-server.com/pingscript?taskId=$task_id&postId=$post_id


When setting a task, you send its data in the array using data fields. The index of the task in this array ($my_unq_id variable in examples) can be used at any time after that, as the post_id field. It will be returned to you with all server responses as well as our unique task_id field. Thanks to this feature, you can use this field to associate the set tasks with identifiers in your system.

As a response of the API server, you will receive JSON array in the results field of which there will be an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string number of elements in the array of results
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
      status string results of this task setting
“ok” – success
“error” – error
if status=“error”, check the error array for more details
      error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
         code integer error code
         message string text description of the error
      post_id string the index in the array received in the POST request
      post_key string key received in the POST request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines
      loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task


Possible error codes:

Error Code Meaning
404 “not found or not enough data: search engine” – you’ve specified a nonexistent se_id or a search engine according to the specified se_name wasn’t found
404 “not found or not enough data: location” – you’ve specified a nonexistent loc_id or a location of a search engine according to the specified loc_name_canonical wasn’t found
404 “not enough data: keyword” – you didn’t specify a keyword in the task
501 “invalid ‘data’ field” – probably you haven’t passed data for the tasks in the data field. POST data should be represented as an array and added to the data field: array(‘data’ => $post_array_for_tasks)
501 “invalid data” – data in the data field isn’t an array with the required structure.
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get Extra SERP Completed Tasks

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com', null, 'login', 'password');

    // #1 - get task_id list of ALL ready results
    //GET /v2/srp_extra_tasks_get
    $tasks_get_result = $client->get('v2/srp_extra_tasks_get');
    print_r($tasks_get_result);

    //get tasks one by one

} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0120 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 107,
            "post_id": 11577837,
            "post_key": "online rank checker",
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "results_count": 4690000,
            "result_extra": "videos",
            "result_spell": "",
            "result_spell_type": "",
            "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
        }
    ]
}

You will get the list of completed tasks, the results of which haven’t been collected yet. Note that after you make a new call to this endpoint, all task_id received as a result of the previous call will be permanently removed from this list of completed tasks in order to avoid duplication.

If you specify pingback_url or postback_url you don’t have to use srp_extra_tasks_get to get the list of completed tasks. Our system will send a GET request to the pingback_url or a POST request with the results to the postback_url.

Please note that if you specify the postback_url or pingback_url field, the task will not be in the list of completed tasks. The task can only be found in the list only if your server returned HTTP code response less than 200 or higher than 300.

As a response of the API server, you will receive an array in the results field containing a list of completed results.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
      post_id string the index in the array received in the POST request
      post_key string key received in the POST request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      se_id integersearch engine id if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
      results_count integer total number of results in SERP
      result_extra string additional (extra) elements in SERP
all extra elements in the string are separated by commas, e.g.: top_stories, featured_snippet, people_also_ask, local_pack, carousel, images, map, video, twitter, app, shopping, google_flights, jobs, answer_box, related_search, knowledge_graph, google_review, mention
      result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
      result_spell_type string type of auto-correction
types of hints: did_you_mean, showing_results_for, no_results_found_for
      result_se_check_url string direct URL to search engine results
You can use it to make sure that we provided exact results

Get Extra SERP Results by task_id

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com', null, 'login', 'password');

    // #1 - get task_id list of ALL ready results
    //GET /v2/srp_extra_tasks_get
    $tasks_get_result = $client->get('v2/srp_extra_tasks_get');
    print_r($tasks_get_result);
    if ($tasks_get_result["status"] == "ok") {
        foreach($tasks_get_result["results"] as $tasks_get_row) {
            // #2 - get result by task_id
            //GET /v2/srp_extra_tasks_get/$task_id
            $serp_result = $client->get('v2/srp_extra_tasks_get/'.$tasks_get_row["task_id"]);
            print_r($serp_result);

            //do something with results
        }
    }
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1376 sec.",
    "results_count": 104,
    "results": [
        {
            "task_id": 629265414,
            "se_id": 14,
            "loc_id": 2840,
            "key_id": 4342117,
            "post_id": "here is supposed to be your post ID 1",
            "post_key": "bill gates",
            "result_se_check_url": "https:\/\/google.com\/search?q=bill%20gates&hl=en&gl=US&gws_rd=cr&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
            "result_datetime": "2018-05-22 12:27:21 +00:00",
            "result_spell": "",
            "result_spell_type": "",
            "result_extra": "top_stories,twitter,people_also_ask,knowledge_graph,videos",
            "result_serp_count": 450000000,
            "result": {
                "left": [
                    {
                        "type": "top_stories",
                        "position": 1,
                        "items": [
                            {
                                "url": "http:\/\/www.businessinsider.com\/bill-gates-summer-reading-recommendations-2018-5",
                                "title": "These are the 5 books Bill Gates recommends you read this summer",
                                "date": "47 mins ago",
                                "source": "CNBC.com"
                            },
                            {
                                "url": "https:\/\/qz.com\/1282604\/your-summer-reading-list-provided-by-bill-gates-2\/",
                                "title": "Your summer reading list, provided by Bill Gates",
                                "date": "47 mins ago",
                                "source": ""
                            },
                            {
                                "url": "https:\/\/www.cnbc.com\/2018\/05\/22\/bill-gates-is-betting-on-this-synthetic-biology-start-up.html",
                                "title": "Why Bill Gates is betting on a start-up that prints synthetic DNA",
                                "date": "",
                                "source": "CNBC.com"
                            }
                        ]
                    },
                    {
                        "type": "organic",
                        "position": 2,
                        "featured_snippet": false,
                        "image": false,
                        "video": false,
                        "url": "https:\/\/en.wikipedia.org\/wiki\/Bill_Gates",
                        "breadcrumb": "https:\/\/en.wikipedia.org\/wiki\/Bill_Gates",
                        "title": "Bill Gates - Wikipedia",
                        "snippet": "William Henry Gates III (born October 28, 1955) is an American business magnate, investor, author, philanthropist, humanitarian, and principal founder of ...",
                        "snippet_extra": "",
                        "links": [],
                        "stat": {
                            "rating": 4.5,
                            "rating_max": 5
                        },
                        "highlighted": [
                            "William",
                            "Gates"
                        ]
                    },
                    {
                        "type": "twitter",
                        "position": 3,
                        "url": "https://twitter.com/BillGates",
                        "title": "Bill Gates (@BillGates) · Twitter",
                        "items": [
                            {
                                "url": "https:\/\/twitter.com\/BillGates\/status\/998593941762199552",
                                "tweet": "From Lincoln to Leonardo, I hope you enjoy my summer reading list. b-gat.es\/2s4hobZ",
                                "date": "20 hours ago"
                            },
                            {
                                "url": "https:\/\/twitter.com\/BillGates\/status\/997168620802199552",
                                "tweet": "At @MDCollege, smarter advising is helping students go further faster. pic.twitter.com\/iWuEG8B…",
                                "date": "5 days ago"
                            },
                            {
                                "url": "https:\/\/twitter.com\/BillGates\/status\/997084318982901760",
                                "tweet": "Glad to see this story told. I’m always inspired by the local leaders and health workers involved in the fight to #endpolio. b-gat.es\/2rLwl29",
                                "date": "5 days ago"
                            },
                            {
                                "url": "https:\/\/twitter.com\/BillGates\/status\/996862856883826690",
                                "tweet": "In the early days of Microsoft, I felt pretty confident about my coding skills, but I had a lot to learn about management. I wish I had @johndoerr’s new book back then. b-gat.es\/2GoSeZQ",
                                "date": "6 days ago"
                            },
                            {
                                "url": "https:\/\/twitter.com\/BillGates\/status\/996793962793848832",
                                "tweet": "France has been a leading champion in the fight against HIV\/AIDS, TB, and malaria.  Their generosity has helped us make terrific progress. twitter.com\/EmmanuelMac…",
                                "date": "6 days ago"
                            }
                        ]
                    },
                    {
                        "type": "local_pack",
                        "position": 4,                        
                        "title": "Pizza Express",
                        "snippet": "Longtime pizza chain known for delivery",
                        "phone": "586-235-584",
                        "rating": 3.8,
                        "rating_type": "stars",
                        "rating_max": 5,
                        "url": "",
                        "paid": true
                    },
                    {
                        "type": "local_pack",
                        "position": 5,
                        "title": "Pizza Pilgrims",
                        "snippet": "Retro-style slice & pie joint",
                        "phone": "",
                        "rating": 4,
                        "rating_type": "stars",
                        "rating_max": 5,
                        "url": "",
                        "paid": false
                    },
                    {
                        "type": "local_pack",
                        "position": 6,
                        "title": "Pizza Hut Restaurants",
                        "snippet": "Thin-crust pizzas & Stone Street seating",
                        "phone": "",
                        "rating": 4.3,
                        "rating_type": "stars",
                        "rating_max": 5,
                        "url": "",
                        "paid": false
                    },                    
                    {
                        "type": "images",
                        "position": 7,
                        "url": "https://www.google.com/search?q=search+volume&num=100&hl=en&gl=US&tbm=isch&tbo=u&source=univ&sa=X&ved=2ahUKEwjnl5PpgL_cAhVBElAKHTOYB_cQsAR6BAhSEAE",
                        "title": "Images for search volume",
                        "items": [
                            {
                                "url": "https://www.wordstream.com/blog/ws/2017/01/23/keyword-search-volume",
                                "alt": "Image result for search volume"
                            },
                            {
                                "url": "https://searchengineland.com/importance-monthly-versus-rolling-average-search-volume-225179",
                                "alt": "Image result for search volume"
                            },
                            {
                                "url": "https://ahrefs.com/blog/keyword-search-volume/",
                                "alt": "Image result for search volume"
                            }
                        ]
                    },
                    {
                        "type": "organic",
                        "position": 8,
                        "featured_snippet": false,
                        "image": false,
                        "video": false,
                        "url": "https:\/\/www.entrepreneur.com\/article\/197526",
                        "breadcrumb": "https:\/\/www.entrepreneur.com\/article\/197526",
                        "title": "Bill Gates Biography - Entrepreneur",
                        "snippet": "Bill Gates. Co-founder of Microsoft Corp. Founded: 1975. \"Ultimately, the PC will be a window to everything people are interested in-and everything we need to ...",
                        "snippet_extra": "",
                        "links": [],
                        "stat": {
                            "rating": 4.5,
                            "rating_max": 5
                        },
                        "highlighted": [
                            "Bill Gates"
                        ]
                    },
                    {
                        "type": "organic",
                        "position": 9,
                        "featured_snippet": false,
                        "image": false,
                        "video": false,
                        "url": "https:\/\/www.forbes.com\/profile\/bill-gates\/",
                        "breadcrumb": "https:\/\/www.forbes.com\/profile\/bill-gates\/",
                        "title": "Bill Gates - Forbes",
                        "snippet": "With his wife Melinda, Bill Gates chairs the Bill & Melinda Gates Foundation, the world's largest private charitable foundation. The foundation works to save lives ...",
                        "snippet_extra": "",
                        "links": [],
                        "stat": [],
                        "highlighted": [
                              "Bill Gates"
                        ]
                    },
                    {
                        "type": "featured_snippet",
                        "position": 10,
                        "url": "https://www.myprotein.com/thezone/nutrition/pre-workout-foods/",
                        "title": "Top 10 Pre Workout Foods - Myprotein",
                        "snippet": "Eating a banana pre-workout is the perfect way to boost your glycogen stores and increase blood sugar levels.Chicken, Rice &amp; Vegetables. ... Greek Yogurt and Dried Fruit. ... Porridge and Oatmeal.Fruit Smoothies.Wholegrain Bread, Sweet Potato and Brown Rice. ... Apple Wedges and Peanut Butter.Omelette.Homemade Protein Bars.More items...",
                        "table": {
                            "table_header": [
                              "Rank",
                              "Country",
                              "GDP (US$MM)"
                            ],
                            "table_data": [
                                [
                                "1",
                                "United States",
                                "19,390,600"
                                ],
                                [
                                "—",
                                "European Union",
                                "17,308,862"
                                ],
                                [
                                "2",
                                "China",
                                "12,014,610"
                                ],
                                [
                                "3",
                                "Japan",
                                "4,872,135"
                                ]
                            ]
                        }
                    },
                    {
                        "type": "people_also_ask",
                        "position": 11,
                        "items": [
                            {
                                "title": "How much does Bill Gates make in a day?",
                                "snippet_definition": "Search for: How much does Bill Gates make in a day?",
                                "snippet_title": "What Warren Buffett Makes Per Hour - Business Insider",
                                "snippet_url": "https://www.businessinsider.com/what-warren-buffett-makes-per-hour-2013-12",
                                "snippet_domain": "www.businessinsider.com"
                            },
                            {
                                "title": "How did Bill Gates get rich?",
                                "snippet_definition": "Search for: How did Bill Gates get rich?",
                                "snippet_title": "How did Bill Gates become so rich? - Quora",
                                "snippet_url": "https://www.quora.com/How-did-Bill-Gates-become-so-rich",
                                "snippet_domain": "www.quora.com"
                            },
                            {
                                "title": "What did Bill Gates invent?",
                                "snippet_definition": "Search for: What did Bill Gates invent?",
                                "snippet_title": "Bill Gates - Microsoft, Family, Quotes &amp; Philanthropy - Biography",
                                "snippet_url": "https://www.biography.com/business-figure/bill-gates",
                                "snippet_domain": "www.biography.com"
                            },
                            {
                                 "title": "What religion is Bill Gates?",
                                 "snippet_definition": "Search for: What religion is Bill Gates?",
                                 "snippet_title": "Bill Gates - Wikipedia",
                                 "snippet_url": "https://en.m.wikipedia.org/wiki/Bill_Gates",
                                 "snippet_domain": "en.m.wikipedia.org"
                            }
                        ]
                    },
                    {
                        "type": "organic",
                        "position": 12,
                        "featured_snippet": false,
                        "image": false,                        
                        "video": false,
                        "url": "https:\/\/www.gatesfoundation.org\/",
                        "breadcrumb": "https:\/\/www.gatesfoundation.org\/",
                        "title": "Bill & Melinda Gates Foundation",
                        "snippet": "We seek to unlock the possibility inside every individual. We see equal value in all lives. And so we are dedicated to improving the quality of life for individuals ...",
                        "snippet_extra": "",
                        "links": [],
                        "stat": [],
                        "highlighted": [
                            "Bill Gates"
                        ]
                    },
                    {
                        "type": "app",
                        "position": 13,
                        "items": [
                            {
                                "url": "https://play.google.com/store/apps/details?id=com.rovio.angrybirds&amp;hl=en_US&amp;referrer=utm_source%3Dgoogle%26utm_medium%3Dorganic%26utm_term%3Dangry+birds&amp;pcampaignid=APPU_1_8dheW9-JG4T85gLY05XgBw",
                                "title": "Angry Birds Classic",
                                "snippet": "",
                                "price": "Free"
                            },
                            {
                                "url": "https://play.google.com/store/apps/details?id=com.rovio.baba&amp;hl=en_US&amp;referrer=utm_source%3Dgoogle%26utm_medium%3Dorganic%26utm_term%3Dangry+birds&amp;pcampaignid=APPU_1_8dheW9-JG4T85gLY05XgBw",
                                "title": "Angry Birds 2",
                                "snippet": "",
                                "price": "Free"
                            },
                            {
                                "url": "https://play.google.com/store/apps/details?id=com.rovio.angrybirds&amp;hl=en&amp;referrer=utm_source%3Dgoogle%26utm_medium%3Dorganic%26utm_term%3Dangry+birds&amp;pcampaignid=APPU_1_8dheW9-JG4T85gLY05XgBw",
                                "title": "Angry Birds Classic",
                                "snippet": "",
                                "price": "Free"
                            }
                        ]
                    },
                    {
                        "type": "shopping",
                        "position": 14,
                        "title": "See DJI drones Phantom 4",
                        "items": [
                            {
                                "title": "DJI - Phantom 4 Pro Quadcopter - White",
                                "url": "https://www.googleadservices.com/pagead/aclk?sa=L&ai=DChcSEwit-a_ZrsncAhWBRIYKHVqdDC8YABADGgJ2dQ&ohost=www.google.com&cid=CAESEeD2TJLZEEFtglErOeHihIjI&sig=AOD64_2fMvHZkISwzvLaq0IzQ9as_Rr9lQ&ctype=5&q=&ved=0ahUKEwiywqjZrsncAhXImVkKHSp5DH4Q9aACCDI&adurl=",
                                "price": "$1,499.99",
                                "source": "Best Buy"
                            },
                            {
                                "title": "Case Club DJI Phantom 4 Compact Drone Case",
                                "url": "https://www.googleadservices.com/pagead/aclk?sa=L&ai=DChcSEwit-a_ZrsncAhWBRIYKHVqdDC8YABAFGgJ2dQ&ohost=www.google.com&cid=CAESEeD2TJLZEEFtglErOeHihIjI&sig=AOD64_06CGFLjkrAKAIsMsLXMubmtkaO3A&ctype=5&q=&ved=0ahUKEwiywqjZrsncAhXImVkKHSp5DH4Qww8INw&adurl=",
                                "price": "$129.95",
                                "source": "Case Club"
                            },
                            {
                                "title": "DJI Phantom 4 Quadcopter Drone FPV Virtual Reality Experience w/ Hardshell Backpack",
                                "url": "https://www.googleadservices.com/pagead/aclk?sa=L&ai=DChcSEwit-a_ZrsncAhWBRIYKHVqdDC8YABAHGgJ2dQ&ohost=www.google.com&cid=CAESEeD2TJLZEEFtglErOeHihIjI&sig=AOD64_15G0VZmDqYvzfro9BiC08HEzSQMQ&ctype=5&q=&ved=0ahUKEwiywqjZrsncAhXImVkKHSp5DH4Qww8IPA&adurl=",
                                "price": "$899.00",
                                "source": "BeachCamera...."
                            }
                        ]
                    },
                    {
                        "type": "answer_box",
                        "position": 15,
                        "text": [
                            "https://www.youtube.com/watch?v=-d7eYGLaiFk",
                            "OJO NGUBER WELAS - NELLA KHARISMA - YouTube",
                            "Artis",
                            "Nella Kharisma",
                            "Album",
                            "Melon Best Nella - Rupo Lan Dunyo",
                            "Dirilis",
                            "2016"
                        ],
                        "links": [
                            {
                                "url": "https://www.youtube.com/watch?v=-d7eYGLaiFk",
                                "anchor": "OJO NGUBER WELAS - NELLA KHARISMA - YouTube"
                            }
                        ]
                    },
                    {
                        "type": "map",
                        "position": 16,
                        "url": "https://www.google.com/maps/place/Andes/data=!4m2!3m1!1s0x968792fc5a4e9d2f:0x8b16530d02147954?hl=en&sa=X&ved=2ahUKEwjhw_q_sMncAhXGqFkKHY3cCDYQ8gEwAHoECAQQAQ",
                        "title": "Andes"
                    },
                    {
                        "type": "video",
                        "position": 17,
                        "items": [
                            {
                                "url": "https://www.noticiasagricolas.com.br/videos/boi/218168-entrevista-com-frederico-borges-stella-presidente-do-sindicato-rural-de-aquidauana-ms.html",
                                "title": "Preços da arroba do boi em Aquidauana-MS reagem com recuo da oferta, mas \nainda estão abaixo das necessidades dos pecuaristas",
                                "source": "Notícias Agrícolas"
                            },
                            {
                                "url": "http://g1.globo.com/mato-grosso-do-sul/mstv-1edicao/videos/t/edicoes/v/jovem-confessa-que-matou-e-congelou-corpo-de-idoso-em-aquidauana/6853090/",
                                "title": "Jovem confessa que matou e congelou corpo de idoso em ...",
                                "source": "G1 - Globo.com"
                            },
                            {
                                "url": "http://g1.globo.com/mato-grosso-do-sul/mstv-1edicao/videos/v/aquidauana-tem-casas-alagadas-e-rodovia-interditada/6517826/",
                                "title": "Aquidauana tem casas alagadas e rodovia interditada - G1 Mato ...",
                                "source": "G1 - Globo.com"
                            }
                        ]
                    },
                    {
                        "type": "google_flights",
                        "position": 18,
                        "title": "Flights from London, United Kingdom (all airports) to Berlin, Germany (all airports)",
                        "url": "https://www.google.com/flights?num=100&hl=en&source=flun&lite=0&uitype=cuAA&tfs=CAEQAhooEgoyMDE4LTA5LTIwagwIAhIIL20vMDRqcGxyDAgCEggvbS8wMTU2cRooEgoyMDE4LTA5LTIzagwIAhIIL20vMDE1NnFyDAgCEggvbS8wNGpwbA&sa=X&ved=2ahUKEwjigrv43MncAhWLxKYKHbGMB7sQuRUwAHoECAYQAw",
                        "items": [
                            {
                                "url": "https://www.google.com/flights?num=100&amp;hl=en&amp;source=flun&amp;lite=0&amp;uitype=cuAA&amp;tfs=CAEQAhouEgoyMDE4LTA5LTIwKAAyAkZSagwIAhIIL20vMDRqcGxyDAgCEggvbS8wMTU2cRouEgoyMDE4LTA5LTI0KAAyAkZSagwIAhIIL20vMDE1NnFyDAgCEggvbS8wNGpwbA&amp;sa=X&amp;ved=2ahUKEwjXwufGzr_cAhUK66QKHcaOBboQ1RUoADAAegQIBBAQ",
                                "description": "Ryanair     1h 50m  Non-stop     from €66"
                            },
                            {
                                "url": "https://www.google.com/flights?num=100&amp;hl=en&amp;source=flun&amp;lite=0&amp;uitype=cuAA&amp;tfs=CAEQAhouEgoyMDE4LTA5LTIwKAAyAlUyagwIAhIIL20vMDRqcGxyDAgCEggvbS8wMTU2cRouEgoyMDE4LTA5LTI0KAAyAlUyagwIAhIIL20vMDE1NnFyDAgCEggvbS8wNGpwbA&amp;sa=X&amp;ved=2ahUKEwjXwufGzr_cAhUK66QKHcaOBboQ1RUoATAAegQIBBAR",
                                "description": "easyJet     1h 50m  Non-stop     from €74"
                            },
                            {
                                "url": "https://www.google.com/flights?num=100&amp;hl=en&amp;source=flun&amp;lite=0&amp;uitype=cuAA&amp;tfs=CAEQAhouEgoyMDE4LTA5LTIwKAAyAkVXagwIAhIIL20vMDRqcGxyDAgCEggvbS8wMTU2cRouEgoyMDE4LTA5LTI0KAAyAkVXagwIAhIIL20vMDE1NnFyDAgCEggvbS8wNGpwbA&amp;sa=X&amp;ved=2ahUKEwjXwufGzr_cAhUK66QKHcaOBboQ1RUoAjAAegQIBBAS",
                                "description": "Eurowings     1h 50m  Non-stop     from €119"
                            }
                        ]
                    },
                   {
                        "type": "jobs",
                        "position": 19,
                        "title": "Jobs Near Philadelphia, PA",
                        "url": "",
                        "items": [
                            {
                                "title": "Cleaner",
                                "url": "https://www.google.com.ua/search?hl=en&ei=zOxVW8m8F6rM6ATM4YaACw&q=philadelphia+department+of+health+jobs++++++++++++++++++++++++&oq=philadelphia+department+of+health+jobs++++++++++++++++++++++++&gs_l=psy-ab.12..0i22i30k1l3.13420.13420.0.14496.1.1.0.0.0.0.96.96.1.1.0....0...1c.1.64.psy-ab..0.1.95....0.fnNOCW1bsw4&ibp=htl;jobs#htidocid=CPe0N2zxBNIkWYd4AAAAAA%3D%3D",
                                "snippet": "Public Health Management Corporation",
                                "author": "via ZipRecruiter",
                                "date": "Over 1 month ago",
                                "type": "Contractor"
                            },
                            {
                                "title": "Morning Cleaner",
                                "url": "https://www.google.com.ua/search?hl=en&ei=zOxVW8m8F6rM6ATM4YaACw&q=philadelphia+department+of+health+jobs++++++++++++++++++++++++&oq=philadelphia+department+of+health+jobs++++++++++++++++++++++++&gs_l=psy-ab.12..0i22i30k1l3.13420.13420.0.14496.1.1.0.0.0.0.96.96.1.1.0....0...1c.1.64.psy-ab..0.1.95....0.fnNOCW1bsw4&ibp=htl;jobs#htidocid=oR8qq-x07ejC09RFAAAAAA%3D%3D",
                                "snippet": "Temple University College of Public Health",
                                "author": "via ChronicleVitae",
                                "date": "4 days ago",
                                "type": "Full-time"
                            },
                            {
                                "title": "Full-time Cleaner",
                                "url": "https://www.google.com.ua/search?hl=en&ei=zOxVW8m8F6rM6ATM4YaACw&q=philadelphia+department+of+health+jobs++++++++++++++++++++++++&oq=philadelphia+department+of+health+jobs++++++++++++++++++++++++&gs_l=psy-ab.12..0i22i30k1l3.13420.13420.0.14496.1.1.0.0.0.0.96.96.1.1.0....0...1c.1.64.psy-ab..0.1.95....0.fnNOCW1bsw4&ibp=htl;jobs#htidocid=ijfp0BQIh6eWdTolAAAAAA%3D%3D",
                                "snippet": "Pepper Hamilton",
                                "author": "via Glassdoor",
                                "date": "27 days ago",
                                "type": "Full-time"
                            }
                        ]
                    },
                    {
                        "type": "carousel",
                        "position": 20,
                        "title": "Backup Software",
                        "items": [
                            {
                                "title": "Backup and RestoreProprietary software",
                                "sub_title": "Cambridge"
                            },
                            {
                                "title": "Acronis True ImageProprietary software",
                                "sub_title": "Los Angeles"
                            },
                            {
                                "title": "Macrium ReflectFreeware",
                                "sub_title": "New York"
                            },
                            {
                                "title": "System Restore",
                                "sub_title": "New York"
                            }
                        ]
                    },
                    {
                        "type": "organic",
                        "position": 99,
                        "featured_snippet": false,
                        "image": true,
                        "video": false,
                        "url": "https://www.microsoft.com/en-us/store/b/home",
                        "breadcrumb": "https://www.microsoft.com/en-us/store/b/home",
                        "title": "Microsoft Store Online",
                        "snippet": "At Microsoft our mission and values are to help people and businesses throughout the world realize their full potential.",
                        "snippet_extra": "",
                        "links": [
                            {
                                "title": "Microsoft Store Online",
                                "url": "https://www.microsoft.com/en-us/store/b/home",
                                "snippet": "Microsoft Store OnlinePCs - Xbox - Xbox Games - Download Windows 10 - ..."
                            },
                            {
                                "title": "Windows 10",
                                "url": "https://www.microsoft.com/en-us/windows",
                                "snippet": "Windows 10Windows 10 unveils new innovations & is better than ever ..."
                            }
                        ],
                        "stat": [],
                        "highlighted": []
                    },
                    {
                        "type": "paid",
                        "position": 100,
                        "url": "https://www.booking.com/city/gb/london.html",
                        "title": "2880 Hotels in London | Lowest Price Guarantee | booking.com",
                        "snippet_row1": "Book for Tomorrow",
                        "snippet_row2": "",
                        "links": [],
                        "stat": [],
                        "highlighted": [
                             "Bill",
                             "Gates"
                        ]
                    },
                    {
                        "type": "organic",
                        "position": 101,
                        "featured_snippet": false,
                        "image": false,                        
                        "video": false,
                        "url": "https:\/\/blogs.scientificamerican.com\/observations\/bill-gates-in-search-of-nuclear-nirvana\/",
                        "breadcrumb": "https:\/\/blogs.scientificamerican.com\/observations\/bill-gates-in-search-of-nuclear-nirvana\/",
                        "title": "Bill Gates in Search of Nuclear Nirvana - Scientific American Blog ...",
                        "snippet": "May 2, 2018 - Bill Gates originally became famous (and rich) for co-founding Microsoft; more recently, he's become better known, through the Bill and Melinda ...",
                        "snippet_extra": "",
                        "links": [],
                        "stat": [],
                        "highlighted": []
                    },
                    {
                        "type": "organic",
                        "position": 102,
                        "featured_snippet": false,
                        "image": false,                        
                        "video": false,
                        "url": "https:\/\/www.recode.net\/2018\/5\/14\/17350538\/john-doerr-measure-what-matters-book-kleiner-perkins-okrs-kara-swisher-teddy-schleifer-podcast",
                        "breadcrumb": "https:\/\/www.recode.net\/2018\/5\/14\/17350538\/john-doerr-measure-what-matters-book-kleiner-perkins-okrs-kara-swisher-teddy-schleifer-podcast",
                        "title": "Kleiner Perkins' John Doerr explains how to run your company like Bill ...",
                        "snippet": "May 14, 2018 - ... (in which he was an early investor), the Bill & Melinda Gates Foundation and the One Campaign, a nonprofit founded by U2 frontman Bono.",
                        "snippet_extra": "",
                        "links": [],
                        "stat": [],
                        "highlighted": []
                    },
                    {
                        "type": "related_search",
                        "position": 103,
                        "title": "airports in berlin",
                        "items": [
                            "Berlin Schönefeld Airport",
                            "Berlin Brandenburg Airport",
                            "Berlin Tegel Airport",
                            "Berlin Tempelhof Airport",
                            "Berlin Hauptbahnhof",
                            "RAF Gatow",
                            "Johannisthal Air Field"
                        ]
                    },
                    {
                        "type": "related_search",
                        "position": 104,
                        "title": "european airports",
                        "items": [
                            "London Stansted Airport",
                            "Manchester Airport",
                            "London City Airport",
                            "Luton Airport",
                            "Keflavík International Airport",
                            "Berlin Schönefeld Airport",
                            "Berlin Tegel Airport"
                        ]
                    },
                    {
                        "type": "related",
                        "position": 105,
                        "items": [
                            "london to berlin flight time",
                            "cheapest time to fly to berlin",
                            "easyjet flights to berlin",
                            "flight to berlin germany",
                            "london to berlin train",
                            "direct flights to berlin",
                            "london to berlin flight duration",
                            "best time to book flights to berlin"
                        ]
                    },
                    {
                        "type": "mention",
                        "position": 106,
                        "title": "Best Headphones &amp; Headsets",
                        "items": [
                            {
                                "title": "Apple EarPods",
                                "price": "$21+",
                                "rating": 4.3,
                                "rating_type": "max_5",
                                "count_ratings": 37817,
                                "mentioned_in": [
                                    {
                                        "title": "Best earbuds 2019: the best earbuds, earphones and in-ear headphones for any budget",
                                        "url": "https://www.techradar.com/news/audio/best-in-ear-headphones-1276925"
                                    },
                                    {
                                        "title": "Best headphones 2019: Your definitive guide to the latest and greatest audio",
                                        "url": "https://www.techradar.com/news/audio/portable-audio/best-headphones-1280340"
                                    }
                                ]
                            },
                            {
                                "title": "Sony WH-1000XM3",
                                "price": "$300+",
                                "rating": 4.7,
                                "rating_type": "max_5",
                                "count_ratings": 4115,
                                "mentioned_in": [
                                    {
                                        "title": "Best Headphones for 2019",
                                        "url": "https://www.cnet.com/topics/headphones/best-headphones/"
                                    },
                                    {
                                        "title": "Best over-ear headphones 2019: the best-sounding, most comfortable cans",
                                        "url": "https://www.techradar.com/news/audio/portable-audio/best-over-ear-headphones-1280342"
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "right": [
                    {
                        "type": "knowledge_graph",
                        "position": 1,
                        "url": "https:\/\/en.wikipedia.org\/wiki\/Bill_Gates",
                        "title": "Bill Gates",
                        "subtitle": "",
                        "description": "William Henry Gates III is an American business magnate, investor, author, philanthropist, humanitarian, and principal founder of Microsoft Corporation.",
                        "parts": [
                              {
                                  "text": "gatesnotes.com",
                                  "url": "https://www.gatesnotes.com/",
                                  "anchor": "gatesnotes.com"
                              },
                              {
                                  "text": "Description William Henry Gates III is an American business magnate, investor, author, philanthropist, and humanitarian. He is best known as the principal founder of Microsoft Corporation.   Wikipedia",
                                  "url": "https://en.wikipedia.org/wiki/Bill_Gates",
                                  "anchor": "Wikipedia"
                              },
                              {
                                  "text": "Born :  October 28, 1955 (age 63 years),  Seattle, WA",
                                  "url": "https://www.google.com/search?num=100&hl=en&gl=US&q=bill+gates+born&stick=H4sIAAAAAAAAAOPgE-LQz9U3MDTPK9ESy0620i9IzS_ISQVSRcX5eVZJ-UV5i1j5kzJzchTSE0tSixVAIgB7lxuyNgAAAA&sa=X&ved=2ahUKEwjykMulpp3hAhVPAHIKHT0EAlgQ6BMoADCKAXoECGMQBg",
                                  "anchor": "Born"
                              },
                              {
                                  "text": "Born :  October 28, 1955 (age 63 years),  Seattle, WA",
                                  "url": "https://www.google.com/search?num=100&hl=en&gl=US&q=Seattle&stick=H4sIAAAAAAAAAOPgE-LQz9U3MDTPK1ECs1Iss4q0xLKTrfQLUvMLclKBVFFxfp5VUn5R3iJW9uDUxJKSnFQA3EAC8jgAAAA&sa=X&ved=2ahUKEwjykMulpp3hAhVPAHIKHT0EAlgQmxMoATCKAXoECGMQBw",
                                  "anchor": "Seattle, WA"
                              },
                              {
                                  "text": "Net worth :  98.3 billion USD (2019)",
                                  "url": "https://www.google.com/search?num=100&hl=en&gl=US&q=bill+gates+net+worth&stick=H4sIAAAAAAAAAOPgE-LQz9U3MDTPK9GSzk620i9IzS_ISQVSRcX5eVZ5qSUK5flFJRmLWEWSMnNyFNITS1KLFeDCAM9_Xi1AAAAA&sa=X&ved=2ahUKEwjykMulpp3hAhVPAHIKHT0EAlgQ6BMoADCMAXoECGMQCg",
                                  "anchor": "Net worth"
                              },
                              {
                                  "text": "Spouse :  Melinda Gates  (m. 1994)",
                                  "url": "https://www.google.com/search?num=100&hl=en&gl=US&q=bill+gates+spouse&stick=H4sIAAAAAAAAAOPgE-LQz9U3MDTPK9GSyE620i9IzS_ISQVSRcX5eVbFBfmlxamLWAWTMnNyFNITS1KLFSBiAGKiWBc6AAAA&sa=X&ved=2ahUKEwjykMulpp3hAhVPAHIKHT0EAlgQ6BMoADCNAXoECGMQDQ",
                                  "anchor": "Spouse"
                              },
                              {
                                  "text": "Spouse :  Melinda Gates  (m. 1994)",
                                  "url": "https://www.google.com/search?num=100&hl=en&gl=US&q=Melinda+Gates&stick=H4sIAAAAAAAAAOPgE-LQz9U3MDTPK1ECs1JyC0y0JLKTrfQLUvMLclKBVFFxfp5VcUF-aXHqIlZe39SczLyURAX3xJLUYgAPK94WQAAAAA&sa=X&ved=2ahUKEwjykMulpp3hAhVPAHIKHT0EAlgQmxMoATCNAXoECGMQDg",
                                  "anchor": "Melinda Gates"
                              }
                        ],
                        "card_id": "/m/01zczs"
                    },
                    {
                        "type": "google_review",
                        "position": 2,
                        "reviews_count": 2657,
                        "place_id": "ChIJ6UCP2tygJ0ERRJmMWID1zMA"
                    }
                ]
            }
        }
    ]
}

Description of the fields for sending a request:

Field name Type Description
task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time


As a response of the API server, you will receive an array in the results field containing a list of completed results.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time. You are charged for each GET request for receiving the results.
      post_id string the index of the array received in the POST array
      se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines
      loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
      post_key string key received in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      result_se_check_url string direct URL to search engine results
You can use it to make sure that we provided exact results
      result_datetime string date and time when the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
      result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
      result_spell_type string type of auto-correction
types of hints: did_you_mean, showing_results_for, no_results_found_for
      result_extra string additional (extra) elements in SERP
all extra elements in the string are separated by commas, e.g.: top_stories, featured_snippet, people_also_ask, local_pack, carousel, images, map, video, twitter, app, shopping, google_flights, jobs, answer_box, related_search, knowledge_graph, google_review, mention
      result_serp_count integer total number of results in SERP
      left array results array from the main body of the SERP with extra elements
you can find the following elements here: organic, paid, top_stories, people_also_ask, local_pack, carousel, images, video, map, twitter, app, shopping, google_flights, jobs, answer_box, related_search, related, mention
         ‘paid’ element in SERP
             type string type of element = ‘paid’
             position integer position in SERP
             url string relevant URL of the Ad element
             breadcrumb string breadcrumb of the Ad element
             title string snippet header of the Ad element
             snippet_row1 string first snippet row in the element
             snippet_row2 string second snippet row in the element
             links array links which are included in the SERP element snippet
             url string relevant URL
             title string snippet header
             snippet string snippet
             stat array statistics
             rating integer/float rating
the popularity rate based on reviews and displayed in SERPs
             rating_max integer the maximum value for a rating
             highlighted array words highlighted in bold within the results snippet
         ‘organic’ element in SERP
             type string type of element = ‘organic’
             position integer position in SERP
             featured_snippet boolean indicates whether the element is a featured_snippet
             image boolean indicates whether the element has an image
             video boolean indicates whether the element has a video
             url string relevant URL in SERP
             breadcrumb string breadcrumb in SERP
             title string snippet header in SERP
             snippet string snippet in SERP
             snippet_extra string the enhanced snippet in SERP
For example: ratings, price, author, etc
             links array links which are included in the SERP element snippet
             url string relevant URL
             title string snippet header
             snippet string snippet
             stat array statistics
             rating integer/float rating
the popularity rate based on reviews and displayed in SERPs
             rating_max integer the maximum value for a rating
             highlighted array words highlighted in bold within the results snippet
             ‘featured snippet’ element in SERP
             type string type of element = ‘featured_snippet’
             position integer position in SERP
             url string relevant URL in SERP
             title string snippet header in SERP
             snippet string snippet in SERP
             table array array of elements
             table_header array array of table header strings
             table_data array array of table row strings
             ‘top stories’ element in SERP
             type string type of element = ‘top_stories’
             position integer position in SERP
             items array items array
             url string relevant URL of the element
             title string title of the element
             date string date of the element
             source string source of the element
             ‘answer box’ element in SERP
             type string type of element = ‘answer_box’
             position integer position in SERP
             text array array of the string with text elements
             links array array of URLs
             url string relevant URL
             anchor string anchor for the URL
             ‘people also ask’ element in SERP
             type string type of element = ‘people_also_ask’
             position integer position in SERP
             items array array of ‘people also ask’ elements
             title string ‘people also ask’ element title
             snippet_definition string snippet definition of the element
             snippet_title string snippet title of the element
             snippet_url string snippet URL of the element
             snippet_domain string snippet domain of the element
             ‘app’ element in SERP
             type string type of element = ‘app’
             position integer position in SERP
             items array applications array
             url string relevant URL of the application
             title string application title
             snippet string application snippet
             price string application price
             ‘carousel’ element in SERP
             type string type of element = ‘carousel’
             position integer position in SERP
             title string carousel title
             items array items array
             title string title of the element
             sub_title string subtitle of the element
             ‘local pack’ element in SERP
             type string type of element = ‘local_pack’
             position integer position in SERP
             url string relevant URL of the element
             title string snippet header of the element
             snippet string snippet of the element
             phone string phone in the element
             rating integer/float rating
the popularity rate based on reviews and displayed in SERPs
             rating_type string measurement units
shows which measurement units are used in the rating field
there are two possible options: stars, percents
             rating_max integer the maximum value for a rating
             paid boolean paid advertisement
             ‘map’ element in SERP
             type string type of element = ‘map’
             position integer position in SERP
             url string relevant URL
             title string snippet header in SERP
             ‘twitter’ element in SERP
             type string type of element = ‘twitter’
             position integer position in SERP
             url string twitter homepage URL
             title string title from twitter
             items array items array
             url string tweet’s URL
             tweet string tweet message
             date string tweet message date
             ‘shopping’ element in SERP
             type string type of element = ‘shopping’
             position integer position in SERP
             title string title of the product in google shopping
             items array items array
             title string product title
             url string product URL
             price string product price
             source string source
             ‘video’ element in SERP
             type string type of element = ‘video’
             position integer position in SERP
             items array array of the URL videos
             url string URL of the video
             title string video title
             source string video source
             ‘images’ element in SERP
             type string type of element = ‘images’
             position integer position in SERP
             url string image URL
             title string image title
             items array array of the URL images
             url string image URL
             alt string alt attribute
             ‘google flights’ element in SERP
             type string type of element = ‘google_flights’
             position integer position in SERP
             url string URL of current tickets
             title string title
             items array array of URLs
             url string URL of this ticket
             description string description
             ‘jobs’ element in SERP
             type string type of element = ‘jobs’
             position integer position in the SERP
             url string URL of current jobs
             title string title
             items array vacancies array
             title string title of this vacancy
             url string URL of this vacancy
             snippet string snippet
             author string author
             date string date of this vacancy
             type string work type
             ‘related search’ element in SERP
             type string type of element = ‘related_search’
             position integer position in SERP
             title string title of the related search element
             items array related keywords array
             ‘related’ element in SERP
             type string type of element = ‘related’
             position integer position in SERP
             items array related keywords array
             ‘mention’ element in SERP
             type string type of element = ‘mention’
             position integer position in SERP
             title string title
             items array array of mention items
             title string item title
             price string item price
             rating float rating
the popularity rate based on reviews and displayed in SERPs
             rating_type string measurement units
shows which measurement units are used in the rating field
             count_ratings integer rating count
             mentioned_in array array that contains a list of resources that mentioned the item
             title string title
             url string url
      right array results array on the right side of SERP with extra elements
you can find the following elements here: knowledge_graph, google review
      ‘knowledge graph’ element in SERP
        type string type of element = ‘knowledge_graph’
        position integer position in SERP
        url string relevant URL in SERP
        title string header in SERP
        subtitle string subtitle in SERP
        description string text of knowledge graph
        parts array array of knowledge graph text items
        text string item text
        url string relevant URL
        anchor string anchor for the URL
        card_id string the knowledge graph id
      ‘google review’ element in SERP
        type string type of element = ‘google_review’
        position integer position in SERP
        reviews_count integer number of results in the reviews list
        place_id string place ID

‌‌
Possible error codes:

Error Code Meaning
102 “task in queue” – the task is being enqueued to handling, please, try again later
201 “task handed” – the task has been received and sent to handling, please, try again later
202 “in progress” – the task is in the handling process, please, try again later
404 “search engine did not return results” – SERP is empty. Check if you have added key correctly
404 “top results not found” – there is no SERP with the specified parameters

Setting Google Reviews Tasks

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com/', null, 'login', 'password');
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
    exit();
}

$post_array = array();

$my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "se_language" => "English",
    "loc_name_canonical"=> "London,England,United Kingdom",
    "se_deep" => 50,
    "sort_by" => "highest_rating",
    "key" =>  mb_convert_encoding("hedonism wines", "UTF-8")
);

$my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "se_language" => "English",
    "loc_id" => 1006886,
    "se_deep" => 50,
    "sort_by" => "highest_rating",
    "key_id" => 30778900
);

if (count($post_array) > 0) {
    try {
        // POST /v2/srp_google_reviews_tasks_post/$data
        // $tasks_data must by array with key 'data'
        $task_post_result = $client->post('v2/srp_google_reviews_tasks_post', array('data' => $post_array));
        print_r($task_post_result);

        //do something with post results

    } catch (RestClientException $e) {
        echo "\n";
        print "HTTP code: {$e->getHttpCode()}\n";
        print "Error code: {$e->getCode()}\n";
        print "Message: {$e->getMessage()}\n";
        print  $e->getTraceAsString();
        echo "\n";
    }
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 2,
    "results": {
        "11913049": {
            "post_id": 11913049,
            "post_key": "hedonism wines",
            "task_id": 404227822,
            "loc_id": 1006886,
            "key_id": 30778900,
            "status": "ok"
        },
        "20469414": {
            "post_id": 20469414,
            "post_key": "hedonism wines",
            "task_id": 404227823,
            "loc_id": 1006886,
            "key_id": 30778900,
            "status": "ok"
        }
    }
}

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. We recommend to set up to 100 tasks at a time. Such limits were set due to the variations of task setting methods that you may use.

If you use the url field, then the processing of each task will take more time. If you use our system identifiers (se_id, loc_id, key_id), the processing of tasks will be faster.

You can also retrieve the results of completed tasks using the unique task identifier task_id. Alternatively, we can send them to you as soon as they are ready if you specify the postback_url or pingback_url when setting a task. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

Below you will find a detailed description of the fields you can use for setting a task.

Description of the fields for setting a task:

Field name Type Description
priority integer execution priority
optional field
can have the following values:
1 – normal execution priority (set by default)
2 – high execution priority

se_language string search engine language
available languages: “English”, “German”, “French”, “Spanish”, “Espanol (Latinoamerica)”, “Swedish”, “Norwegian”, “Danish”, “Dutch”, “Vietnamese”, “Portuguese (Portugal)”, “Chinese (Traditional)”, “Chinese (Simplified)”, “Russian”
default value: “English”
se_deep integer crawling depth
required field
you should specify the crawling depth
we strongly recommend setting a crawling depth in the multiples of ten, because our crawler processes ten reviews in a row
please note that Google returns 4490 results maximum
default value: 10
max value: 4490
loc_id integer location id
optional field if you specify loc_name_canonical
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
key_id integer keyword id
optional field if you specify key
when you set a task for the first time you won’t be able to know this field. But if you plan to collect rankings for this keyword, we recommend saving the key_id returned after the task was set, and use this field to get the results later on.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”if this field contains ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’ then the charge per task will be multiplied by 10.
sort_by string type of sorting
optional field
search results filter type
you can specify:
newest – sort by newest first
highest_rating – sort by highest rating
lowest_rating – sort by lowest rating
relevant – sort by relevance
default value: relevant
se_param_add string additional parameters of the search query
optional field
for example, if you want to disable auto-correction of the search query misspelling for google, you should use the “&nfpr=1” parameter
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify the postback URL there will be no need to use Get Google Reviews Results for obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$task_id’ string as a $task_id variable and ‘$post_id’ as $post_id variable. We will set the necessary values before sending the request. For example:
http://your-server.com/pingscript?taskId=$task_id
http://your-server.com/pingscript?taskId=$task_id&postId=$post_id


When setting a task, you send its data in the array using data fields. The index of the task in this array ($my_unq_id variable in examples) can be used at any time after that, as the post_id field. It will be returned to you with all server responses as well as our unique task_id field. Thanks to this feature, you can use this field to associate the set tasks with identifiers in your system.

As a response of the API server, you will receive JSON array in the results field of which there will be an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
      status string results of this task setting
“ok” – success
“error” – error
if status=“error”, check the error array for more details
      error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
      post_id string the index in the array received in the POST request
      post_key string key received in the POST request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task

‌‌
Possible error codes:

Error Code Meaning
404 “not found or not enough data: location” – you’ve specified a nonexistent loc_id or a location of a search engine according to the specified loc_name_canonical wasn’t found
404 “not found or not enough data: language” – you’ve specified a nonexistent language
404 “not enough data: keyword” – you didn’t specify a keyword in the task
501 “invalid ‘data’ field” – probably you haven’t passed data for the tasks in the data field. POST data should be represented as an array and added to the data field: array(‘data’ => $post_array_for_tasks)
501 “invalid data” – data in the data field isn’t an array with the required structure.
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get Google Reviews Completed Tasks

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com', null, 'login', 'password');

    // #1 - get task_id list of ALL ready results
    //GET /v2/srp_google_reviews_tasks_get
    $tasks_get_result = $client->get('v2/srp_google_reviews_tasks_get');
    print_r($tasks_get_result);

    //get tasks one by one

} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0120 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": 11577837,
            "post_key": "hedonism wines",
            "task_id": 25536431,
            "loc_id": 1006886,
            "key_id": 30778900,
            "result_se_check_url": "https://google.com/search?q=hedonism%20wines&hl=en&gl=US&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
            "results_count": 378
        }
    ]
}

You will get the list of completed tasks, the results of which haven’t been collected yet. Note that after you make a new call to this endpoint, all task_id received as a result of the previous call will be permanently removed from this list of completed tasks in order to avoid duplication.

If you specify pingback_url or postback_url you don’t have to use srp_google_reviews_tasks_get to get the list of completed tasks. Our system will send a GET request to the pingback_url or a POST request with the results to the postback_url.

Please note that if you specify the postback_url or pingback_url field, the task will not be in the list of completed tasks. The task can only be found in the list only if your server returned HTTP code response less than 200 or higher than 300.

As a response of the API server, you will receive an array in the results field containing a list of completed results.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
      post_id string the index in the array received in the POST request
      post_key string key received in the POST request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      loc_id integer location id
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
      results_count string the number of elements in the results array
      result_se_check_url string direct URL to search engine results
You can use it to make sure that we provided exact results

Get Google Reviews Results by task_id

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com', null, 'login', 'password');

    // #1 - get task_id list of ALL ready results
    //GET /v2/srp_google_reviews_tasks_get
    $tasks_get_result = $client->get('v2/srp_google_reviews_tasks_get');
    print_r($tasks_get_result);
    if ($tasks_get_result["status"] == "ok") {
        foreach($tasks_get_result["results"] as $tasks_get_row) {
            // #2 - get result by task_id
            //GET /v2/srp_google_reviews_tasks_get/$task_id
            $reviews_result = $client->get('v2/srp_google_reviews_tasks_get/'.$tasks_get_row["task_id"]);
            print_r($reviews_result);

            //do something with results
        }
    }
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1376 sec.",
    "results_count": 100,
    "results": [
          {
              "task_id": 2467424648,
              "loc_id": 1006886,
              "key_id": 30778900,
              "post_id": 11577837,
              "post_key": "hedonism wines",
              "result_se_check_url": "https://google.com/search?q=hedonism%20wines&hl=en&gl=US&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
              "result_datetime": "2018-11-01 16:11:04 +00:00",
              "result_title": "Hedonism Wines",
              "result_sub_title": "3-7 Davies St, London, UK",
              "result_stat": {
                  "rating": 4.8,
                  "rating_max": 5
              },
              "result_reviews_count": 377,
              "result_place_id": "ChIJDxnC6SwFdkgRTYAlUwkFFU4",
              "result": [
                  {
                      "position": 1,
                      "review_text": "I would say this is a unique place in London for what it is. It's not only the shop you can buy pretty much any type of alcohol and get brilliant service from knowledgeable staff but also some sort of a creative place with always unique front displays and a very interesting owner, who you can meet there sometimes.Great Russian businessman who saw the potential, the need on the market and made this all a reality!I would advise anyone to come in and have a look for themselves, it's a true gem in the heart of London!",
                      "time_ago": "a month ago",
                      "stat": {
                          "rating": 5,
                          "rating_max": 5
                      },
                      "reviews_count": 19,
                      "photos_count": 11,
                      "local_guide": true,
                      "profile_name": "Cho Lujas",
                      "profile_url": null,
                      "profile_image_url": "https://lh5.googleusercontent.com/-ScIRqgD8ARM/AAAAAAAAAAI/AAAAAAAABD4/2WECAm1k4_o/s40-ba2-c0x00000000-cc-rp-mo/photo.jpg",
                      "owner_answer": null,
                      "owner_time_ago": null
                  },
                  {
                      "position": 2,
                      "review_text": "The best...what more can be said..wines from everywhere..israel...sardinia..oz..etc",
                      "time_ago": "4 days ago",
                      "stat": [],
                      "reviews_count": 1,
                      "photos_count": null,
                      "local_guide": false,
                      "profile_name": "A Google User",
                      "profile_url": null,
                      "profile_image_url": "https://lh3.googleusercontent.com/-veRGrSi7dcE/AAAAAAAAAAI/AAAAAAAAAAA/iRdrhnwCCLI/s40-c0x00000000-cc-rp-mo/photo.jpg",
                      "owner_answer": null,
                      "owner_time_ago": null
                  },
                  {
                      "position": 3,
                      "review_text": "Aparr from a great selection of wines, they have a self service wine counter in the basement. You can top up your card and enjoy on of the most interesting wines. Well done!",
                      "time_ago": "3 months ago",
                      "stat": {
                          "rating": 4,
                          "rating_max": 5
                      },
                      "reviews_count": 17,
                      "photos_count": 4,
                      "local_guide": true,
                      "profile_name": "Maria Kovalevskaya",
                      "profile_url": null,
                      "profile_image_url": "https://lh5.googleusercontent.com/-EnTNVhiiOmk/AAAAAAAAAAI/AAAAAAAABBE/0WHlT4cJtZ4/s40-ba2-c0x00000000-cc-rp-mo/photo.jpg",
                      "owner_answer": null,
                      "owner_time_ago": null
                  }
              ]
          }
    ]
}

Please note that Google returns 4490 results maximum.

Description of the fields for sending a request:

Field name Type Description
task_id integer task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time


As a response of the API server, you will receive an array in the results field containing a list of completed results.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
      post_id string the index of the array received in the POST array
      loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
      post_key string key received in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      result_se_check_url string direct URL to search engine results
You can use it to make sure that we provided exact results
      result_datetime string date and time when the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
      result_title string title in the reviews list
      result_subtitle string subtitle in the reviews list
      result_stat array rating information about the reviews element of the result
empty array if result does not have a rating
            rating integer/float rating
the popularity rate based on reviews and displayed in the reviews list
            rating_max integer the maximum value for a rating
      result_reviews_count integer total number of results in the reviews list
      result_place_id string place ID
      result array the list of reviews
            position integer position in the reviews list
            review_text string text of the review
            time_ago string indicates when the review was written and the review’s source
            stat array rating information about the reviews element of the result
empty array if result does not have a rating
                  rating integer/float rating
the popularity rate based on reviews and displayed in the reviews list
                  rating_max integer the maximum value for a rating
            reviews_count integer number of reviews written by a user
            photos_count integer number of images posted by a user
            local_guide boolean indicates if a user is a “local guide”
            profile_name string name of the user who wrote the review
            profile_url string profile URL of the user who wrote the review
            profile_image_url string profile image URL of the user who wrote the review
            owner_answer string owner’s answer to the review
            owner_time_ago string indicates when the answer was written

‌‌
Possible error codes:

Error Code Meaning
102 “task in queue” – the task is being enqueued to handling, please, try again later
201 “task handed” – the task has been received and sent to handling, please, try again later
202 “in progress” – the task is in the handling process, please, try again later
404 “search engine did not return results” – the reviews list is empty. Check if you have added key correctly
404 “top results not found” – there is no reviews list with the specified parameters

Setting Google Images Tasks

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip
require('RestClient.php');

$api_url = 'https://api.dataforseo.com/';
try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/
    $client = new RestClient($api_url, null, 'login', 'password');
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
    exit();
}

$post_array = array();

// example #1 - simplest
// you set only a website URL and a search engine URL.
// This search engine URL string will be searched, compared to our internal parameters
// and used as:
// "se_id", "loc_id", "key_id" ( actual and fresh list can be found here: "se_id":
// https://api.dataforseo.com/v2/cmn_se , "loc_id": https://api.dataforseo.com/v2/cmn_locations ) (see example #3 for details)
// If a task was set successfully, this *_id will be returned in results: 'v2/srp_google_images_tasks_post' so you can use it.
// The setting of a task can fail, if you set not-existent search engine, for example.
$my_unq_id = mt_rand(0, 30000000); // your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "url" => "https://www.google.co.uk/search?q=seo%20data%20api&tbm=isch&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
);

// example #2 - will return results faster than #1, but is simpler than example #3
// All parameters should be set in the text format.
// All data will be will be searched, compared to our internal parameters
// and used as:
// "se_id", "loc_id", "key_id" ( actual and
// fresh list can be found here: "se_id": https://api.dataforseo.com/v2/cmn_se ,
// "loc_id": https://api.dataforseo.com/v2/cmn_locations )
// If a task was set successfully, this *_id will be returned in results: 'v2/srp_google_images_tasks_post' so you can use it.
// The setting of a task can fail, if you set not-existent search engine, for example.
// Disadvantages: The process of search and comparison of provided data to our internal parameters may take some time.
$my_unq_id = mt_rand(0, 30000000); // your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "se_name" => "google.co.uk",
    "se_language" => "English",
    "loc_name_canonical" => "London,England,United Kingdom",
    "key" => mb_convert_encoding("green", "UTF-8")
    //,"pingback_url" => "http://your-domain.com/pingback_url_example.php?task_id=$task_id" //see pingback_url_example.php script
);

// example #3 - the fastest one. All parameters should be set in our internal format.
// Actual and fresh list can be found here: "se_id": https://api.dataforseo.com/v2/cmn_se ,
// "loc_id": https://api.dataforseo.com/v2/cmn_locations
$my_unq_id = mt_rand(0, 30000000); // your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "se_id" => 22,
    "loc_id" => 1006886,
    "key_id" => 2396119
    //,"postback_url" => "http://your-domain.com/postback_url_example.php" //see postback_url_example.php script
);

// This example has a 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
if (count($post_array) > 0) {
    try {
        // POST /v2/srp_google_images_tasks_post/$tasks_data
        // $tasks_data must by array with key 'data'
        $task_post_result = $client->post('/v2/srp_google_images_tasks_post', array('data' => $post_array));
        print_r($task_post_result);

        //do something with post results

        $post_array = array();
    } catch (RestClientException $e) {
        echo "\n";
        print "HTTP code: {$e->getHttpCode()}\n";
        print "Error code: {$e->getCode()}\n";
        print "Message: {$e->getMessage()}\n";
        print  $e->getTraceAsString();
        echo "\n";
    }
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.2434 sec.",
    "results_count": 3,
    "results": {
        "325488": {
            "status": "ok",
            "post_id": 325488,
            "post_key": "red apple",
            "task_id": 4467891911,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 12490968
        },
        "4475123": {
            "status": "ok",
            "post_id": 4475123,
            "post_key": "green",
            "task_id": 4467891915,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1211604
        },
        "85446210": {
            "status": "ok",
            "post_id": 85446210,
            "post_key": "wallpapers",
            "task_id": 4467891917,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 2396119
        }
    }
}

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. We recommend to set up to 100 tasks at a time. Such limits were set due to the variations of task setting methods that you may use.

If you use the url field, then the processing of each task will take more time. If you use our system identifiers (se_id, loc_id, key_id), the processing of tasks will be faster.

You can also retrieve the results of completed tasks using the unique task identifier task_id. Alternatively, we can send them to you as soon as they are ready if you specify the postback_url or pingback_url when setting a task. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

Below you will find a detailed description of the fields you can use for setting a task.

Description of the fields for setting a task:

Field name Type Description
priority integer execution priority
optional field
can have the following values:
1 – normal execution priority (set by default)
2 – high execution priority

url string direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
se_id integer search engine id
optional field, if you specify se_name
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
also, when the information about set task is returned, you will get the se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_name by making a separate request to the List of Search Engines
example: “google.co.uk”
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with se_language by making a separate request to the List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
key_id integer keyword id
optional field if you specify key
when you set a task for the first time you won’t be able to know this field. But if you plan to collect rankings for this keyword, we recommend saving the key_id returned after the task was set, and use this field to get the results later on.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”if this field contains ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’ then the charge per task will be multiplied by 10.
se_param_add string additional parameters of the search query
optional field
for example, if you want to disable auto-correction of the search query misspelling for Google, you should use the “&nfpr=1” parameter
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify the postback URL there will be no need to use Get Google Images Results for obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$task_id’ string as a $task_id variable and ‘$post_id’ as $post_id variable. We will set the necessary values before sending the request. For example:
http://your-server.com/pingscript?taskId=$task_id
http://your-server.com/pingscript?taskId=$task_id&postId=$post_id


When setting a task, you send its data in the array using data fields. The index of the task in this array ($my_unq_id variable in examples) can be used at any time after that, as the post_id field. It will be returned to you with all server responses as well as our unique task_id field. Thanks to this feature, you can use this field to associate the set tasks with identifiers in your system.

As a response of the API server, you will receive JSON array in the results field of which there will be an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
      status string results of this task setting
“ok” – success
“error” – error
if status=“error”, check the error array for more details
      error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
         code integer error code
         message string text description of the error
      post_id string the index in the array received in the POST request
      post_key string key received in the POST request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines
      loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task


Possible error codes:

Error Code Meaning
404 “not found or not enough data: search engine” – you’ve specified a nonexistent se_id or a search engine according to the specified se_name wasn’t found
404 “not found or not enough data: location” – you’ve specified a nonexistent loc_id or a location of a search engine according to the specified loc_name_canonical wasn’t found
404 “not enough data: keyword” – you didn’t specify a keyword in the task
501 “invalid ‘data’ field” – probably you haven’t passed data for the tasks in the data field. POST data should be represented as an array and added to the data field: array(‘data’ => $post_array_for_tasks)
501 “invalid data” – data in the data field isn’t an array with the required structure.
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get Google Images Completed Tasks

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com', null, 'login', 'password');

    // get task_id list of ALL ready results
    //GET /v2/srp_google_images_tasks_get
    $tasks_get_result = $client->get('v2/srp_google_images_tasks_get');
    print_r($tasks_get_result);

    } catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0624 sec.",
    "results_count": 3,
    "results": [
        {
            "post_id": "4475123",
            "post_key": "green",
            "task_id": 4467899385,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1211604,
            "result_spell": "",
            "result_spell_type": "",
            "result_se_check_url": "https://www.google.co.uk/search?q=green&tbm=isch&&num=100&hl=en&gl=GB&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
        },
        {
            "post_id": "85446210",
            "post_key": "wallpapers",
            "task_id": 4467899386,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 2396119,
            "result_spell": "",
            "result_spell_type": "",
            "result_se_check_url": "https://www.google.co.uk/search?q=wallpapers&tbm=isch&&num=100&hl=en&gl=GB&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
        },
        {
            "post_id": "325488",
            "post_key": "red apple",
            "task_id": 4467899384,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 12490968,
            "result_spell": "",
            "result_spell_type": "",
            "result_se_check_url": "https://www.google.co.uk/search?q=red apple&tbm=isch&&num=100&gl=GB&hl=en&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
        }
    ]
}

You will get the list of completed tasks, the results of which haven’t been collected yet. Note that after you make a new call to this endpoint, all task_id received as a result of the previous call will be permanently removed from this list of completed tasks in order to avoid duplication.

If you specify pingback_url or postback_url you don’t have to use srp_google_images_tasks_get to get the list of completed tasks. Our system will send a GET request to the pingback_url or a POST request with the results to the postback_url.

Please note that if you specify the postback_url or pingback_url field, the task will not be in the list of completed tasks. The task can only be found in the list only if your server returned HTTP code response less than 200 or higher than 300.

As a response of the API server, you will receive an array in the results field containing a list of completed results.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
      post_id string the index in the array received in the POST request
      post_key string key received in the POST request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      se_id integer search engine id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
      result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
      result_spell_type string type of auto-correction
types of hints: did_you_mean, showing_results_for, no_results_found_for
      result_se_check_url string direct URL to search engine results
You can use it to make sure that we provided exact results

Get Google Images Results by task_id

Instead of ‘login’ and ‘password’ use your credentials from https://my.dataforseo.com/#api_dashboard

<?php
require('RestClient.php');
//You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

try {
    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com', null, 'login', 'password');

    // #1 - get task_id list of ALL ready results
    //GET /v2/srp_tasks_get
    $tasks_get_result = $client->get('v2/srp_google_images_tasks_get');
    print_r($tasks_get_result);
    if ($tasks_get_result["status"] == "ok") {
        foreach($tasks_get_result["results"] as $tasks_get_row) {
            // #2 - get result by task_id
            //GET /v2/srp_tasks_get/$task_id
            $serp_result = $client->get('v2/srp_google_images_tasks_get/'.$tasks_get_row["task_id"]);
            print_r($serp_result);

            //do something with results
        }
    }
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.2715 sec.",
    "results_count": 100,
    "results": [
        {
            "post_id": "85446210",
            "task_id": 4467899386,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 2396119,
            "post_key": "wallpapers",
            "result_spell": "",
            "result_spell_type": "",
            "result_se_check_url": "https://www.google.co.uk/search?q=wallpapers&tbm=isch&&num=100&hl=en&gl=GB&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
            "result": [
                {
                    "position": 1,
                    "datetime": "2019-06-14 08:53:39 +00:00",
                    "original_url": "https://images.unsplash.com/photo-1535370976884-f4376736ab06?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1000&q=80",
                    "page_url": "https://unsplash.com/photos/Sewc0TdvV-o",
                    "encrypted_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSfP_DLgVgDwvzeu3szhl0fMKEtdeUh97aHiev6pb86G6s-s0TT",
                    "alt": "Image result for wallpapers",
                    "title": "Wallpapers, abstract, backgrounds and tumblr backgrounds | HD photo ...",
                    "sub_title": "unsplash.com"
                },
                {
                    "position": 2,
                    "datetime": "2019-06-14 08:53:39 +00:00",
                    "original_url": "https://images.pexels.com/photos/1212487/pexels-photo-1212487.jpeg?auto=format%2Ccompress&cs=tinysrgb&dpr=1&w=500",
                    "page_url": "https://www.pexels.com/search/mobile%20wallpaper/",
                    "encrypted_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQiCl-HjYA9f_8A5RD5dlrwQDRy7Ahj05aYDCEpb6z8KLlzw1tKpg",
                    "alt": "Image result for wallpapers",
                    "title": "Mobile Wallpapers · Pexels · Free Stock Photos",
                    "sub_title": "pexels.com"
                },
                {
                    "position": 3,
                    "datetime": "2019-06-14 08:53:39 +00:00",
                    "original_url": "https://images.pexels.com/photos/799443/pexels-photo-799443.jpeg?auto=format%2Ccompress&cs=tinysrgb&dpr=1&w=500",
                    "page_url": "https://www.pexels.com/search/lock%20screen%20wallpaper/",
                    "encrypted_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRi4ho0Lrdz59_ioIY-5z1FHUiC8GGnoXritMd4NAsXNHHqyO4s5w",
                    "alt": "Image result for wallpapers",
                    "title": "Lock Screen Wallpapers · Pexels · Free Stock Photos",
                    "sub_title": "pexels.com"
                }
            ]
        }
    ]
}

Description of the fields for sending a request:

Field name Type Description
task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time


As a response of the API server, you will receive an array in the results field containing a list of completed results.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      post_id string the index in the array received in the POST request
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
      se_id integer search engine id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
      post_key string key received in the POST request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
      result_spell_type string type of auto-correction
types of hints: did_you_mean, showing_results_for, no_results_found_for
      result_se_check_url string direct URL to search engine results
You can use it to make sure that we provided exact results
      result array results array of SERP images
         position integer position in SERP
         result_datetime string date and time when the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
         original_url string image URL in the original source
         page_url string URL of the source page containing the image
         encrypted_url string URL of the image saved and compressed by Google Images
         alt string image alt attribute
         title string image title displayed in Google Images
         source string source domain displayed in Google Images


Possible error codes:

Error Code Meaning
102 “task in queue” – the task is being enqueued to handling, please, try again later
201 “task handed” – the task has been received and sent to handling, please, try again later
202 “in progress” – the task is in the handling process, please, try again later
404 “search engine did not return results” – SERP is empty. Check if you have added key correctly
404 “top results not found” – there is no SERP with the specified parameters