Introduction

Welcome to DataForSEO API!

DataForSEO API uses REST technology for interchanging data between your application and our service. The data exchange is made by the HTTP protocol. The benefit of this method is widespread occurrence of the HTTP protocol that’s why REST API can be used almost for all programming languages.

You can create REST class by yourself or find ready to use ones to use this technology.
We can provide you with ready to use classes:

Also, all responses of our service are returned in the JSON format by default. We also support responses in the XML format. For this, in the end of the request you should specify .xml. Also, you can compress retrieved data in the gzip format, for this you need to specify .gzip in the request.

For example, https://api.dataforseo.com/v2/cmn_user.xmlhttps://api.dataforseo.com/v2/cmn_user.gziphttps://api.dataforseo.com/v2/cmn_user.xml.gzip instead of the standard https://api.dataforseo.com/v2/cmn_user

fromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")#do something

usingSystem;usingSystem.Net.Http;usingSystem.Net.Http.Headers;usingSystem.Text;usingSystem.Threading.Tasks;usingNewtonsoft.Json;namespaceDataForSeoDemos{publicstaticpartialclassDemos{publicstaticasyncTaskcmn_key_id(){varhttpClient=newHttpClient{BaseAddress=newUri("https://api.dataforseo.com/"),//Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginDefaultRequestHeaders={Authorization=newAuthenticationHeaderValue("Basic",Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}};// do something}}}

importorg.apache.http.HttpResponse;importorg.apache.http.client.HttpClient;importorg.apache.http.client.methods.HttpGet;importorg.apache.http.client.methods.HttpPost;importorg.apache.http.entity.StringEntity;importorg.apache.http.impl.client.HttpClientBuilder;importorg.apache.http.util.EntityUtils;importorg.json.JSONArray;importorg.json.JSONException;importorg.json.JSONObject;importjava.io.IOException;importjava.net.URI;importjava.net.URISyntaxException;importjava.net.URLEncoder;importjava.util.*;publicclassDemos{publicstaticvoidcmn_key_id_first_method_in_api()throwsException{URIurl=newURI("https://api.dataforseo.com/");HttpClientclient=HttpClientBuilder.create().build();//Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginStringbasicAuth=Base64.getEncoder().encodeToString(("login:password").getBytes("UTF-8"));//do something}}

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

First of all, you should register at our service and then you will be able to use your login and password to start using our API service.

It provides you with a possibility to use our API almost for all programming languages.

After registration you will get 1000 credits for free to test our API before purchase!

Rank Tracker API

Rank Tracker API helps to find rankings of a website in the result pages of the search engines that were specified.

The data will look like:

The tasks setting is made by few clients streams. At the same time few other clients streams constantly request our service to pick completed tasks from queue.

It is the most simplified and widespread method of work with Rank Tracker API.

You also can receive results of completed tasks using task_id or we can send them by ourselves as soon as they are ready if you specify postback_url or pingback_url when setting a task.

The time of results delivery is less for those tasks which priority is high.

Setting Rank Tasks

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

<?phprequire('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/login
$client=newRestClient('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();//for example, some data selection cycle for tasks
for($i=0;$i<3;$i++){// example #1 - the simplest one
// 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/rnk_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
$post_array[$my_unq_id]=array("priority"=>1,"site"=>"dataforseo.com","url"=>"https://www.google.co.uk/search?q=seo%20data%20api&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 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/rnk_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. will be returned with all results
$post_array[$my_unq_id]=array("priority"=>1,"site"=>"dataforseo.com","se_name"=>"google.co.uk","se_language"=>"English","loc_name_canonical"=>"London,England,United Kingdom","key"=>mb_convert_encoding("seo data api","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
$post_array[$my_unq_id]=array("priority"=>1,"site"=>"dataforseo.com","se_id"=>22,"loc_id"=>1006886,"key_id"=>62845222);//This example has a cycle of up to 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
if(count($post_array)>99){try{// POST /v2/rnk_tasks_post/$data
// $tasks_data must by array with key 'data'
$task_post_result=$client->post('v2/rnk_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";}}}if(count($post_array)>0){try{// POST /v2/rnk_tasks_post/$data
// $tasks_data must by array with key 'data'
$task_post_result=$client->post('v2/rnk_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;?>

POST https://api.dataforseo.com/v2/rnk_tasks_postThe credits are charged for the task that was successfully completed.The cost can be calculated on the Home Page Rank Tracker API.

When we were developing the mechanism of tasks setting we tried to foresee many variations for your convenience. That’s why the range of fields is wide even though some of them are optional. Because of such flexibility for tasks settings it may seem that the process is difficult, but the things are simpler than you think.

We are sure that you will be able to pick the way of task setting that fits you the most.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using POST method when array of tasks is sent in data field. We recommend to set up to 100 tasks at a time. Such limit was set because of the variations of tasks settings that you will use. If you use the field url then the processing of each task will take more time. If you use our identifiers (se_id, loc_id, key_id) then the processing of tasks will be made faster and you can set more than 100 elements at a time.

Description of the fields for a task setting:

Name of a field

Type

Description

priority

integer

execution priorityoptional fieldcan have such values:1 - normal execution priority (set by default)2 - high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Home Page Rank Tracker API.

site

string

a website domain which rankings should be searched for in the SERPrequired fieldyou can use wildcard (‘*’) to specify the search mask in the SERP. But if you decide to use a wildcard and want to include subdomains to the search then you should also specify it using wildcard.examples: “example.com” (standard search) “example.com/” (search of exact URL) “example.com/eng/*” (search example.com and URLs which start with ‘/eng/’ in the SERP, such as ‘example.com/eng/index.html’ and ‘example.com/eng/help/’ etc) “*.example.com/eng/*” (search example.com and all its subdomain with URLs which start with ‘/eng/’ in the SERP such as ‘m.example.com/eng/index.html’ and ‘m.example.com/eng/some_url/’ etc.)

url

string

direct URL of a search queryoptional fieldyou can specify a direct URL and we will sort it out to the necessary fields. Such method is the most difficult for our API processing and you should exactly specify language and location in the URL. We don’t recommend to use 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 idoptional field, if you specify se_nameyou must choose one of the fields se_id or se_namethe list of available search engines with their se_id you can get by separate request List of Search Enginesalso, when the information about set task is returned you will get se_id

se_name

string

search engine domainoptional field if you specify se_idyou must choose one of the fields se_id or se_namethe list of available search engines with se_name you can get by separate request List of Search Enginesexample: “google.co.uk”

se_language

string

search engine languagerequired field if se_id is not specifiedthe list of available search engines with their se_language you can get by separate request List of Search Enginesexample: “English”

loc_id

integer

search engine location idoptional field if you specify loc_name_canonicalyou must choose one of the fields loc_id or loc_name_canonicalthe list of available locations of search engines with their loc_id you can receive by separate request List of Locationswhen the information about set task is returned you will get loc_idplease notice that we use Google Geographical Targeting including such types of locations as CountryStateRegionMunicipalityCity, that’s why you can specify in the field loc_id appropriate Criteria ID

loc_name_canonical

string

full name of search engine locationoptional field if you specify loc_idyou must choose one of the fields loc_id or loc_name_canonicalthe list of available locations of search engines with their loc_name_canonical you can receive by separate request List of Locationsplease notice that we use Google Geographical Targeting including such types of locations as CountryStateRegionMunicipalityCity, that’s why you can specify in the field loc_name_canonical approriate to Canonical Nameexample: “London,England,United Kingdom”

key_id

integer

keyword idoptional field if you specify keywhen 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 you to save key_id returned after the task was set and use this field in the future.

key

string

keywordoptional field if you specify key_idUTF-8 encodingall %## 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”.

additional parameters of search queryoptional fieldfor example, if you want to disable auto correction of misspelling in the search query for google, you can specify “&nfpr=1”

postback_url

string

return URL for sending task resultsoptional fieldif you specify this URL there will be no need to pick up tasks using Get Rank Tasks Results. We will send a result of a completed task by POST request for URL as soon as a task is completed.

pingback_url

string

notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use string ‘$task_id’ as $task_id variable and ‘$post_id’ as $post_id variable. we will set necessary values before sending of a request. for example: http://your-server.com/pingscript?taskId=$task_id http://your-server.com/pingscript?taskId=$task_id&postId=$post_id

When setting tasks, you send tasks data in the array using data field. 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 such feature, you can use this field to associate the set tasks with identifiers at your system.

Here are some examples:

There is an identifier at your system of a task that you set to collect data, let it be 100500. When you set the task you send it in the data array with 100500 index like here: "{"data":{"100500":{"priority":1,"site":"ranksonic.com","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 at your system.

You want to associate other kinds of data at your system. For instance:

a keyword has id=1238 at your system,

a search engine 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 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 necessary data will have this value 1238#43289#97435#2#9999. As a result, the request for setting of a task will look like this:
"{"data":{"1238#43289#97435#2#9999":{"priority":1,"site":"ranksonic.com","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 API server you will receive JSONarray in the field results of which there will be an information appropriate to the set tasks.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly 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 resultsresults

results

array

results array of tasks setting

task_id

integer

unique task identifier in our systemin the future you will be able to use it within 30 days to request results of this task any time.

status

string

results of this task setting“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly if status=“error”the list of possible errors can be found below.

code

integer

error code

message

string

text description of an error

post_id

string

index in the array received in a POST request

post_site

string

site received in a POST request

post_key

string

key received in a POST requestkeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

se_id

integer

search engine idif status=“ok”, then this field will be always filledYou can use it for finding relations between your and our search engines.

loc_id

integer

search engine location idif status=“ok”, then this field will always be filledYou can use it for finding relations between your and our search engines.

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

Possible errors codes

Error Code

Meaning

404

“not found or not enough data: site” - you didn’t specify a website in the task

404

“not found or not enough data: search engine” - you’ve specified nonexistent se_id or a search engine wasn’t found by specified se_name

404

“not found or not enough data: location” - you’ve specified nonexistent loc_id or a location of a search engine wasn’t found by specified loc_name_canonical

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 field data. POST data should be represented as an array and added to the field data: array(‘data’ => $post_array_for_tasks)

501

“invalid data” - Data in the field data isn’t an array with the required structure.

500

“internal error” - some internal error. We did our best to not let this type of error ever happen.

Get Rank Tasks Results

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

<?phprequire('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/login
$client=newRestClient('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";}/*
#1 - get ALL ready results
recommended use of getting results:
run this script by cron with 10-60 streams, every minute with random delay 0-30 sec.
usleep(mt_rand(0,30000000));
*/try{//GET /v2/rnk_tasks_get
$task_get_result=$client->get('v2/rnk_tasks_get');print_r($task_get_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";}/*
#2 - get one result by task_id
*/try{// GET /api/v1/tasks_get/$task_id
$task_get_result=$client->get('v2/rnk_tasks_get/123456789');print_r($task_get_result);//do something with 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;?>

fromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")response=client.get("/v2/rnk_tasks_get")ifresponse["status"]=="error":print("error. Code: %d Message: %s"%(response["error"]["code"],response["error"]["message"]))else:print(response["results"])

GET https://api.dataforseo.com/v2/rnk_tasks_getGET https://api.dataforseo.com/v2/rnk_tasks_get/$task_idYou are not charged when receiving results. It means, for instance, you can request results few times for a certain task for free.

You can receive results in three different ways:

GET https://api.dataforseo.com/v2/rnk_tasks_getyou will receive all complete results that have not been picked up.

GET https://api.dataforseo.com/v2/rnk_tasks_get/$task_idafter you’ve set a task there will be unique identifier returned to you in the response of our service. It is specified in the field task_id. You will be able to use it within 30 days to pick the results of the task.

When setting a task (Setting Rank Tasks) you’ve specified pingback_url or postback_url. As soon as the task is completed we will send GET request to the URL you’ve specified as pingback_url or POST request with its results to the URL you specified as postback_url when the task was set.

Description of the fields for a request setting:

Name of a field

Type

Description

task_id

string

unique task identifier in our systemin the future you will be able to use it within 30 days to request results of this task any time.

You will receive array from the API server in the field results where you will find rank tracker results.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly 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 resultsresults

results

array

results array of tasks

organic

array

results array oforganicSERP

task_id

integer

unique task identifier in our systemin the future you will be able to use it within 30 days to request results of this task any time.

post_id

string

index in the array received in a POST array

post_site

string

site received in a POST array

post_key

string

keyreceived in a POST arraykeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

se_id

integer

search engine idYou can use it for finding relations between your and our search engines.

loc_id

integer

search engine location idYou can use it for finding relations between your and our search engines.

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

result_position

integer

position in the SERP

result_datetime

string

date and time when a result was receivedin the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”for example: “2016-12-13 15:30:34 +02:00”time zone specified at your profile settings is used

auto correction of a search engineif a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engine

result_se_check_url

string

direct URL to search engine results You can use it to make sure that we provide exact results

paid

array

results array ofpaidSERPIt will be available in the future, for now all the data in this field will always have empty array.

task_id

integer

unique task identifier in our systemin the future you will be able to use it within 30 days to request results of this task any time.

post_id

string

index in the array received in a POST array

post_site

string

site received in a POST array

post_key

string

keyreceived in a POST arraykeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

se_id

integer

search engine idYou can use it for finding relations between your and our search engines.

loc_id

integer

search engine location idYou can use it for finding relations between your and our search engines.

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

result_position

integer

position in the SERP

result_datetime

string

date and time when a result was receivedin the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”for example: “2016-12-13 15:30:34 +02:00”time zone specified at your profile settings is used

auto correction of a search engineif a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engine

result_se_check_url

string

direct URL to search engine results You can use it to make sure that we provide exact results

SERP API

SERP API provides you with a possibility to receive SERP (Top 100) results of specified search engines according to a certain keyword. Also, in the SERP html section you can find out how to get html page of the SERP based on a specified search engine. SERP reviews provides you with users’ reviews of a specific place (restaurant, shop, etc.).

The operating principle of SERP API is similar to Rank Tracker API. The main difference is that you don’t receive all complete results at once - you receive a list of task_id which results are complete, after you can receive each result separately. This is due to the fact that each of tasks has huge data amount.

The time of results delivery is less for those tasks which priority is high.

Setting SERP Tasks

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

<?phprequire('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/login
$client=newRestClient('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();//for example, some data selection cycle for tasks
for($i=0;$i<3;$i++){// 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("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 cycle of up to 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
if(count($post_array)>99){try{// POST /v2/srp_tasks_post/$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";}}}if(count($post_array)>0){try{// POST /v2/srp_tasks_post/$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
}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;?>

fromrandomimportRandomfromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")rnd=Random()#you can set as "index of post_data" your ID, string, etc. we will return it with all results.post_data=dict()post_data[rnd.randint(1,30000000)]=dict(priority=1,url="https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS")post_data[rnd.randint(1,30000000)]=dict(priority=1,se_name="google.co.uk",se_language="English",loc_name_canonical="London,England,United Kingdom",key="online rank checker")post_data[rnd.randint(1,30000000)]=dict(priority=1,se_id=22,loc_id=1006886,key_id=1095202)response=client.post("/v2/srp_tasks_post",dict(data=post_data))ifresponse["status"]=="error":print("error. Code: %d Message: %s"%(response["error"]["code"],response["error"]["message"]))else:print(response["results"])

usingSystem;usingSystem.Collections.Generic;usingSystem.Linq;usingSystem.Net.Http;usingSystem.Net.Http.Headers;usingSystem.Text;usingSystem.Threading.Tasks;usingNewtonsoft.Json;namespaceDataForSeoDemos{publicstaticpartialclassDemos{publicstaticasyncTasksrp_tasks_post(){varhttpClient=newHttpClient{BaseAddress=newUri("https://api.dataforseo.com/"),//Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginDefaultRequestHeaders={Authorization=newAuthenticationHeaderValue("Basic",Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}};varrnd=newRandom();//you can set as "index of post_data" your ID, string, etc. we will return it with all results.varpostObject=newDictionary<int,object>{[rnd.Next(1,30000000)]=new{priority=1,url="https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"},[rnd.Next(1,30000000)]=new{priority=1,se_name="google.co.uk",se_language="English",loc_name_canonical="London,England,United Kingdom",key="online rank checker"},[rnd.Next(1,30000000)]=new{priority=1,se_id=22,loc_id=1006886,key_id=1095202}};vartaskPostResponse=awaithttpClient.PostAsync("v2/srp_tasks_post",newStringContent(JsonConvert.SerializeObject(new{data=postObject})));varobj=JsonConvert.DeserializeObject<dynamic>(awaittaskPostResponse.Content.ReadAsStringAsync());if(obj.status=="error")Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");else{foreach(varresultinobj.results){vartaskState=((IEnumerable<dynamic>)result).First();if(taskState.status=="error")Console.WriteLine($"Error in task with post_id {taskState.post_id}. Code: {taskState.error.code} Message: {taskState.error.message}");Console.WriteLine(taskState);}}}}}

POST https://api.dataforseo.com/v2/srp_tasks_postThe credits are charged both for the setting of a task and getting of its results.The cost can be calculated on the Home Page SERP API.

All POST data should be sent in the JSON format (UTF-8 encoding). Task setting is made by the POST method, passing array of tasks in data field. We recommend to set up to 100 tasks at a time. Such limit was set because of the variations of tasks settings that you will use. If you use the field url then the processing of each task will take more time. If you use our identifiers (se_id, loc_id, key_id), then the processing of tasks will be made faster and you can set more than 100 elements at a time.

You also can receive results of completed tasks using task_id or we can send them by ourselves as soon as they are ready if you specify postback_url or pingback_url when setting a task.

Description of the fields for a task setting:

Name of a field

Type

Description

priority

integer

execution priorityoptional fieldcan have such values:1 - normal execution priority (set by default)2 - high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Home Page SERP API.

url

string

direct URL of a search queryoptional fieldyou can specify a direct URL and we will sort it out to the necessary fields. Such method is the most difficult for our API processing and you should exactly specify language and location in the URL. We don’t recommend to use 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 idoptional field, if you specify se_nameyou must choose one of the fields se_id or se_namethe list of available search engines with se_id you can get by separate request List of Search Enginesalso, when the information about set task is returned you will get se_id

se_name

string

search engine domainoptional field if you specify se_idyou must choose one of the fields se_id or se_namethe list of available search engines with se_name you can get by separate request List of Search Enginesexample: “google.co.uk”

se_language

string

search engine languagerequired field if se_id is not specifiedthe list of available search engines with se_language you can get by separate request List of Search Enginesexample: “English”

loc_id

integer

search engine location idoptional field if you specify loc_name_canonicalyou must choose one of the fields loc_id or loc_name_canonicalthe list of available locations of search engines with loc_id you can get by separate request List of Locationsalso when the information about set task is returned you will get loc_idplease notice that we use Google Geographical Targeting including such types of locations as CountryStateRegionMunicipalityCity, that’s why you can specify loc_id appropriate Criteria ID

loc_name_canonical

string

full name of search engine locationoptional field if you specify loc_idyou must choose one of the fields loc_id or loc_name_canonicalthe list of available locations of search engines with loc_name_canonical you can get by separate List of Locationsplease notice that we use Google Geographical Targeting including such types of locations as CountryStateRegionMunicipalityCity, that’s why you can specify loc_name_canonical appropriate Canonical Nameexample: “London,England,United Kingdom”

key_id

integer

keyword idoptional field if you specify keywhen 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 you to save key_id returned after the task was set and use this field in the future.

key

string

keywordoptional field if you specify key_idUTF-8 encodingall %## 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:’, ‘cache:’, ‘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 search queryoptional fieldfor instance, if you want to disable auto correction of misspelling in the search query for google, you can specify “&nfpr=1”

postback_url

string

return URL for sending task resultsoptional fieldif you specify this URL there will be no need to pick up tasks using Get SERP Tasks Results. We will send a result of a completed task by POST request for URL as soon as a task is completed.

pingback_url

string

notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use string ‘$task_id’ as $task_id variable and ‘$post_id’ as $post_id variable. we will set necessary values before sending of a request. for example: http://your-server.com/pingscript?taskId=$task_id http://your-server.com/pingscript?taskId=$task_id&postId=$post_id

When setting tasks, you send tasks data in the array using data field. 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 such feature, you can use this field to associate the set tasks with identifiers at your system.

Here are some examples:

There is an identifier at your system of a task that you set to collect data, let it be 100500. When you set the task you send it in the data array with 100500 index like here: "{"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 at your system.

You want to associate other kinds of data at your system. For instance:

a keyword has id=1238 at your system,

a search engine 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 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 necessary data will have this value 1238#43289#97435#2#9999. As a result, the request for setting of 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 API server you will receive JSONarray in the field results of which there will be an information appropriate to the set tasks.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly if status=“error”the list of possible errors can be found below.

code

integer

error code

message

string

text description of error

results_time

string

execution time, seconds

results_count

string

number of elements in the array ofresults

results

array

results array of tasks setting

task_id

integer

unique task identifier in our systemin the future you will be able to use it within 30 days to request results of this task any time.

status

string

results of this task setting“ok” - success“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly if status=“error”the list of possible errors can be found below.

code

integer

error code

message

string

text description of error

post_id

string

index in the array received in a POST request

post_key

string

key received in a POST requestkeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

se_id

integer

search engine idif status=“ok”, then this field will be always filledYou can use it for finding relations between your and our search engines.

loc_id

integer

search engine location idif status=“ok”, then this field will be always filledYou can use it for finding relations between your and our search engines.

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

Possible errors codes

Error Code

Meaning

404

“not found or not enough data: site” - you didn’t specify a website in the task

404

“not found or not enough data: search engine” - you’ve specified nonexistent se_id or a search engine wasn’t found by specified se_name

404

“not found or not enough data: location” - you’ve specified nonexistent loc_id or a location of a search engine wasn’t found by specified loc_name_canonical

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 fielddata. POST data should be represented as an array and added to the field data: array(‘data’ => $post_array_for_tasks)

501

“invalid data” - data in the field data isn’t an array with the required structure.

500

“internal error” - some internal error. We did our best to not let this type of error ever happen.

Get SERP Completed Tasks

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

<?phprequire('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/login
$client=newRestClient('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;?>

fromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")response=client.get("/v2/srp_tasks_get")ifresponse["status"]=="error":print("error. Code: %d Message: %s"%(response["error"]["code"],response["error"]["message"]))else:print(response["results"])

GET https://api.dataforseo.com/v2/srp_tasks_getYou are not charged when receiving results

You will get the list of complete results, that you haven’t collected yet. After you collect a result the task will be removed from this list.

If you specify pingback_url or postback_url you can skip usage of srp_tasks_get to get the list of completed tasks. Our system send you GET request to the pingback_url or send POST request with results to the postback_url.

As a response of API server you will receive array in the field resultsof which there will be a list of complete results.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly 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 ofresults

results

array

results array of tasks

task_id

integer

unique task identifier in our systemin the future you will be able to use it within 30 days to request results of this task any time

post_id

string

index in the array received in a POST array

post_key

string

key received in a POST arraykeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

se_id

integer

search engine idYou can use it for finding relations between your and our search engines

loc_id

integer

search engine location idYou can use it for finding relations between your and our search engines.

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

GET https://api.dataforseo.com/v2/srp_tasks_get/$task_idYou are charged for each GET request for results receiving.The cost can be calculated on the Home Page SERP API.

Description of the fields for a request setting:

Name of a field

Type

Description

task_id

string

unique task identifier in our systemin the future you will be able to use it within 30 days to request results of this task any time.

As a response of API server you will receive array in the field resultsof which there will be a list of complete results.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly 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 ofresults

results

array

results array of tasks setting

organic

array

results array oforganicSERP

task_id

integer

unique task identifier in our systemin the future you will be able to use it within 30 days to request results of this task any time. You are charged for each GET request for results receiving.

post_id

string

index in the array received in a POST array

se_id

integer

search engine id

loc_id

integer

search engine location idYou can use it for finding relations between your and our search engines.

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

post_key

string

keyreceived in a POST arraykeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

result_position

integer

position in the SERP

result_datetime

string

date and time when a result was receivedin 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 at your profile settings is used

result_url

string

relevant URL in the SERP

result_title

string

snippet header in the SERP

result_snippet_extra

string

additional snippet in the SERPratings, price, author, etc

result_snippet

string

snippet in the SERP

results_count

integer

total number of results in the SERP

result_stat

array

information about the reviews element of a resultempty array if result does not have a reviews element

rating

integer/float

ratingthe popularity rate based on reviews and displayed in the SERPs

rating_type

string

measurement unitsshows which measurement units are used in the rating fieldthere are two possible options: stars, percents

auto correction of a search engineif a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engine

result_se_check_url

string

direct URL to search engine results You can use it to make sure that we provide exact results

paid

array

results array ofpaidSERP

task_id

integer

unique task identifier in our systemin the future you will be able to use it within 30 days to request results of this task any time.

post_id

string

index in the array received in a POST array

se_id

integer

search engine id

loc_id

integer

search engine location idYou can use it for finding relations between your and our search engines.

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

post_key

string

keyreceived in a POST arraykeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

result_position

integer

position in the SERP

result_datetime

string

date and time when a result was receivedin 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 at your profile settings is used

result_url

string

relevant URL in the SERP

result_title

string

snippet header in the SERP

result_snippet_extra

string

additional snippet in the SERPratings, price, author, etc

result_snippet

string

snippet in the SERP

results_count

integer

total number of results in the SERP

result_stat

array

information about the reviews element of a resultempty array if result does not have a reviews element

rating

integer/float

ratingthe popularity rate based on reviews and displayed in the SERPs

rating_type

string

measurement unitsshows which measurement units are used in the rating fieldthere are two possible options: stars, percents

auto correction of a search engineif a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engine

result_se_check_url

string

direct URL to search engine results You can use it to make sure that we provide exact results

extra

array

results array ofextraSERP elementsextra SERP elements are available only for google search engine

related

array

array of ‘related search queries’ stringsthis array will be present if the element is in the SERP

Possible errors 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 specified parameters

Setting SERP HTML Tasks

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

<?phprequire('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/login
$client=newRestClient('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();//for example, some data selection cycle for tasks
for($i=0;$i<3;$i++){// 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 cycle of up to 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
if(count($post_array)>99){try{// POST /v2/srp_tasks_post/$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";}}}if(count($post_array)>0){try{// POST /v2/srp_tasks_post/$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
}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;?>

fromrandomimportRandomfromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")rnd=Random()#you can set as "index of post_data" your ID, string, etc. we will return it with all results.post_data=dict()post_data[rnd.randint(1,30000000)]=dict(priority=1,url="https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS")post_data[rnd.randint(1,30000000)]=dict(priority=1,se_name="google.co.uk",se_language="English",loc_name_canonical="London,England,United Kingdom",key="online rank checker")post_data[rnd.randint(1,30000000)]=dict(priority=1,se_id=22,loc_id=1006886,key_id=1095202)response=client.post("/v2/srp_html_tasks_post",dict(data=post_data))ifresponse["status"]=="error":print("error. Code: %d Message: %s"%(response["error"]["code"],response["error"]["message"]))else:print(response["results"])

usingSystem;usingSystem.Collections.Generic;usingSystem.Linq;usingSystem.Net.Http;usingSystem.Net.Http.Headers;usingSystem.Text;usingSystem.Threading.Tasks;usingNewtonsoft.Json;namespaceDataForSeoDemos{publicstaticpartialclassDemos{publicstaticasyncTasksrp_html_tasks_post(){varhttpClient=newHttpClient{BaseAddress=newUri("https://api.dataforseo.com/"),//Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginDefaultRequestHeaders={Authorization=newAuthenticationHeaderValue("Basic",Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}};varrnd=newRandom();//you can set as "index of post_data" your ID, string, etc. we will return it with all results.varpostObject=newDictionary<int,object>{[rnd.Next(1,30000000)]=new{priority=1,url="https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"},[rnd.Next(1,30000000)]=new{priority=1,se_name="google.co.uk",se_language="English",loc_name_canonical="London,England,United Kingdom",key="online rank checker"},[rnd.Next(1,30000000)]=new{priority=1,se_id=22,loc_id=1006886,key_id=1095202}};vartaskPostResponse=awaithttpClient.PostAsync("v2/srp_html_tasks_post",newStringContent(JsonConvert.SerializeObject(new{data=postObject})));varobj=JsonConvert.DeserializeObject<dynamic>(awaittaskPostResponse.Content.ReadAsStringAsync());if(obj.status=="error")Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");else{foreach(varresultinobj.results){vartaskState=((IEnumerable<dynamic>)result).First();if(taskState.status=="error")Console.WriteLine($"Error in task with post_id {taskState.post_id}. Code: {taskState.error.code} Message: {taskState.error.message}");Console.WriteLine(taskState);}}}}}

POST https://api.dataforseo.com/v2/srp_html_tasks_postThe credits are charged for each task that you set.The cost can be calculated on the Home Page SERP API.

All POST data should be sent in the JSON format (UTF-8 encoding). Task setting is made by the POST method, passing array of tasks in data field. We recommend to set up to 100 tasks at a time. Such limit was set because of the variations of tasks settings that you will use. If you use the field url then the processing of each task will take more time. If you use our identifiers (se_id, loc_id, key_id), then the processing of tasks will be made faster and you can set more than 100 elements at a time.

You also can receive results of completed tasks using task_id or we can send them by ourselves as soon as they are ready if you specify postback_url or pingback_url when setting a task.

Description of the fields for a task setting:

Name of a field

Type

Description

priority

integer

execution priorityoptional fieldcan have such values:1 - normal execution priority (set by default)2 - high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Home Page SERP API.

url

string

direct URL of a search queryoptional fieldyou can specify a direct URL and we will sort it out to the necessary fields. Such method is the most difficult for our API processing and you should exactly specify language and location in the URL. We don’t recommend to use 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 idoptional field, if you specify se_nameyou must choose one of the fields se_id or se_namethe list of available search engines with se_id you can get by separate request List of Search Enginesalso, when the information about set task is returned you will get se_id

se_name

string

search engine domainoptional field if you specify se_idyou must choose one of the fields se_id or se_namethe list of available search engines with se_name you can get by separate request List of Search Enginesexample: “google.co.uk”

se_language

string

search engine languagerequired field if se_id is not specifiedthe list of available search engines with se_language you can get by separate request List of Search Enginesexample: “English”

loc_id

integer

search engine location idoptional field if you specify loc_name_canonicalyou must choose one of the fields loc_id or loc_name_canonicalthe list of available locations of search engines with loc_id you can get by separate request List of Locationsalso when the information about set task is returned you will get loc_idplease notice that we use Google Geographical Targeting including such types of locations as CountryStateRegionMunicipalityCity, that’s why you can specify loc_id appropriate Criteria ID

loc_name_canonical

string

full name of search engine locationoptional field if you specify loc_idyou must choose one of the fields loc_id or loc_name_canonicalthe list of available locations of search engines with loc_name_canonical you can get by separate List of Locationsplease notice that we use Google Geographical Targeting including such types of locations as CountryStateRegionMunicipalityCity, that’s why you can specify loc_name_canonical appropriate Canonical Nameexample: “London,England,United Kingdom”

key_id

integer

keyword idoptional field if you specify keywhen 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 you to save key_id returned after the task was set and use this field in the future.

key

string

keywordoptional field if you specify key_idUTF-8 encodingall %## 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:’, ‘cache:’, ‘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 search queryoptional fieldfor instance, if you want to disable auto correction of misspelling in the search query for google, you can specify “&nfpr=1”

postback_url

string

return URL for sending task resultsoptional fieldif you specify this URL there will be no need to pick up tasks using Get SERP HTML Tasks Results. We will send a result of a completed task by POST request for URL as soon as a task is completed.The data that is sent to you will be in ZIP archive and you will need to decode it.

pingback_url

string

notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use string ‘$task_id’ as $task_id variable and ‘$post_id’ as $post_id variable. we will set necessary values before sending of a request. for example: http://your-server.com/pingscript?taskId=$task_id http://your-server.com/pingscript?taskId=$task_id&postId=$post_id

When setting tasks, you send tasks data in the array using data field. 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 such feature, you can use this field to associate the set tasks with identifiers at your system.

Here are some examples:

There is an identifier at your system of a task that you set to collect data, let it be 100500. When you set the task you send it in the data array with 100500 index like here: "{"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 at your system.

You want to associate other kinds of data at your system. For instance:

a keyword has id=1238 at your system,

a search engine 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 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 necessary data will have this value 1238#43289#97435#2#9999. As a result, the request for setting of 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 API server you will receive JSONarray in the field results of which there will be an information appropriate to the set tasks.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly if status=“error”the list of possible errors can be found below.

code

integer

error code

message

string

text description of error

results_time

string

execution time, seconds

results_count

string

*number of elements in the array ofresults

results

array

results array of tasks setting

task_id

integer

unique task identifier in our systemin the future you will be able to use it within 7 days to request results of this task any time.

status

string

results of this task setting“ok” - success“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly if status=“error”the list of possible errors can be found below.

code

integer

error code

message

string

text description of error

post_id

string

index in the array received in a POST request

post_key

string

key received in a POST requestkeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

se_id

integer

search engine idif status=“ok”, then this field will be always filledYou can use it for finding relations between your and our search engines.

loc_id

integer

search engine location idif status=“ok”, then this field will be always filledYou can use it for finding relations between your and our search engines.

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

Possible errors codes

Error Code

Meaning

404

“not found or not enough data: site” - you didn’t specify a website in the task

404

“not found or not enough data: search engine” - you’ve specified nonexistent se_id or a search engine wasn’t found by specified se_name

404

“not found or not enough data: location” - you’ve specified nonexistent loc_id or a location of a search engine wasn’t found by specified loc_name_canonical

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 fielddata. POST data should be represented as an array and added to the field data: array(‘data’ => $post_array_for_tasks)

501

“invalid data” - data in the field data isn’t an array with the required structure.

500

“internal error” - some internal error. We did our best to not 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/login

<?phprequire('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/login
$client=newRestClient('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;?>

fromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")response=client.get("/v2/srp_html_tasks_get")ifresponse["status"]=="error":print("error. Code: %d Message: %s"%(response["error"]["code"],response["error"]["message"]))else:print(response["results"])

GET https://api.dataforseo.com/v2/srp_html_tasks_getYou are not charged when receiving results

You will get the list of complete results, that you haven’t collected yet. After you collect a result the task will be removed from this list.

If you specify pingback_url or postback_url you can skip usage of srp_tasks_get to get the list of completed tasks. Our system send you GET request to the pingback_url or send POST request with results to the postback_url.

As a response of API server you will receive array in the field resultsof which there will be a list of complete results.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly 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 ofresults

results

array

results array of tasks

post_id

string

index in the array received in a POST array

task_id

integer

unique task identifier in our systemin the future you will be able to use it within 7 days to request results of this task any time

post_key

string

key received in a POST arraykeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

se_domain

string

search engine domain

se_id

integer

search engine idYou can use it for finding relations between your and our search engines

loc_id

integer

search engine location idYou can use it for finding relations between your and our search engines.

Get SERP HTML Results by task_id

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

GET https://api.dataforseo.com/v2/srp_html_tasks_get/$task_idGET https://api.dataforseo.com/v2/srp_html_tasks_get/$task_id/$paramYou are not charged when receiving results. It means, for instance, you can request results few times for a certain task for free.

Description of the fields for a request setting:

Name of a field

Type

Description

task_id

string

unique task identifier in our systemin the future you will be able to use it within 7 days to request results of this task any time.

param

string

additional parameterallowable values:normalized in this case an html page will be retrieved without any styles and scriptsif this parameter is not specified, you will receive a complete html page

As a response of API server you will receive array in the field resultsof which there will be a list of complete results.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly 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 ofresults

results

array

results array of tasks setting

post_id

string

index in the array received in a POST array

task_id

integer

unique task identifier in our systemin 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 a POST arraykeyword 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 arrayresult array with html page

Possible errors 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 specified parameters

Setting Extra SERP Tasks

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

<?phprequire('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/login
$client=newRestClient('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();//for example, some data selection cycle for tasks
for($i=0;$i<3;$i++){// 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 cycle of up to 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
if(count($post_array)>99){try{// POST /v2/srp_extra_tasks_post/$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";}}}if(count($post_array)>0){try{// POST /v2/srp_extra_tasks_post/$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
}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;?>

fromrandomimportRandomfromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")rnd=Random()#you can set as "index of post_data" your ID, string, etc. we will return it with all results.post_data=dict()post_data[rnd.randint(1,30000000)]=dict(priority=1,url="https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS")post_data[rnd.randint(1,30000000)]=dict(priority=1,se_name="google.co.uk",se_language="English",loc_name_canonical="London,England,United Kingdom",key="online rank checker")post_data[rnd.randint(1,30000000)]=dict(priority=1,se_id=22,loc_id=1006886,key_id=1095202)response=client.post("/v2/srp_extra_tasks_post",dict(data=post_data))ifresponse["status"]=="error":print("error. Code: %d Message: %s"%(response["error"]["code"],response["error"]["message"]))else:print(response["results"])

usingSystem;usingSystem.Collections.Generic;usingSystem.Linq;usingSystem.Net.Http;usingSystem.Net.Http.Headers;usingSystem.Text;usingSystem.Threading.Tasks;usingNewtonsoft.Json;namespaceDataForSeoDemos{publicstaticpartialclassDemos{publicstaticasyncTasksrp_extra_tasks_post(){varhttpClient=newHttpClient{BaseAddress=newUri("https://api.dataforseo.com/"),//Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginDefaultRequestHeaders={Authorization=newAuthenticationHeaderValue("Basic",Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}};varrnd=newRandom();//you can set as "index of post_data" your ID, string, etc. we will return it with all results.varpostObject=newDictionary<int,object>{[rnd.Next(1,30000000)]=new{priority=1,url="https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"},[rnd.Next(1,30000000)]=new{priority=1,se_name="google.co.uk",se_language="English",loc_name_canonical="London,England,United Kingdom",key="online rank checker"},[rnd.Next(1,30000000)]=new{priority=1,se_id=22,loc_id=1006886,key_id=1095202}};vartaskPostResponse=awaithttpClient.PostAsync("v2/srp_extra_tasks_post",newStringContent(JsonConvert.SerializeObject(new{data=postObject})));varobj=JsonConvert.DeserializeObject<dynamic>(awaittaskPostResponse.Content.ReadAsStringAsync());if(obj.status=="error")Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");else{foreach(varresultinobj.results){vartaskState=((IEnumerable<dynamic>)result).First();if(taskState.status=="error")Console.WriteLine($"Error in task with post_id {taskState.post_id}. Code: {taskState.error.code} Message: {taskState.error.message}");Console.WriteLine(taskState);}}}}}

Currently available only for “google desktop” and “google mobile”.POST https://api.dataforseo.com/v2/srp_extra_tasks_postThe credits are charged both for the setting of a task and getting of its results.The cost can be calculated on the Home Page SERP API.

All the data included in the POST request should be in the JSON format (UTF-8 encoding). The tasks shall be set through the POST method, by placing the tasks array into the data field. It is not recommended to set more than 100 tasks at once due to the different task variations you are likely to use. Note that the usage of the url field slows down the tasks processing. On the contrary, by using system identifiers (se_id, loc_id, key_id), you can accelerate the tasks processing and set more than 100 tasks at once.

You can get the completed task results via the unique task_id. Alternatively, you may indicate the pingback_url or postback_url to get task results send to a specific url.

Description of the fields for a task setting:

Name of a field

Type

Description

priority

integer

execution priorityoptional fieldcan have such values:1 - normal execution priority (set by default)2 - high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Home Page SERP API.

url

string

direct URL of a search queryoptional fieldyou can specify a direct URL and we will sort it out to the necessary fields. Such method is the most difficult for our API processing and you should exactly specify language and location in the URL. We don’t recommend to use 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 idoptional field, if you specify se_nameyou must choose one of the fields se_id or se_namethe list of available search engines with se_id you can get by separate request List of Search Enginesalso, when the information about set task is returned you will get se_idcurrently 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 the words (like “ maps”, “ map pack”, “ shopping”) included into the “se_name”

se_name

string

search engine domainoptional field if you specify se_idyou must choose one of the fields se_id or se_namethe list of available search engines with se_name you can get by separate request List of Search Enginesexample: “google.co.uk”currently available only for “google desktop” and “google mobile” . to get se_name for “google desktop” and “google mobile” you must choose a search engine without any additional the words (like “ maps”, “ map pack”, “ shopping”) included into the “se_name”

se_language

string

search engine languagerequired field if se_id is not specifiedthe list of available search engines with se_language you can get by separate request List of Search Enginesexample: “English”

loc_id

integer

search engine location idoptional field if you specify loc_name_canonicalyou must choose one of the fields loc_id or loc_name_canonicalthe list of available locations of search engines with loc_id you can get by separate request List of Locationsalso when the information about set task is returned you will get loc_idplease notice that we use Google Geographical Targeting including such types of locations as CountryStateRegionMunicipalityCity, that’s why you can specify loc_id appropriate Criteria ID

loc_name_canonical

string

full name of search engine locationoptional field if you specify loc_idyou must choose one of the fields loc_id or loc_name_canonicalthe list of available locations of search engines with loc_name_canonical you can get by separate List of Locationsplease notice that we use Google Geographical Targeting including such types of locations as CountryStateRegionMunicipalityCity, that’s why you can specify loc_name_canonical appropriate Canonical Nameexample: “London,England,United Kingdom”

key_id

integer

keyword idoptional field if you specify keywhen 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 you to save key_id returned after the task was set and use this field in the future.

key

string

keywordoptional field if you specify key_idUTF-8 encodingall %## 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:’, ‘cache:’, ‘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 search queryoptional fieldfor instance, if you want to disable auto correction of misspelling in the search query for google, you can specify “&nfpr=1”

postback_url

string

return URL for sending task resultsoptional fieldif you specify this URL there will be no need to pick up tasks using Get SERP Tasks Results. We will send a result of a completed task by POST request for URL as soon as a task is completed.

pingback_url

string

notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use string ‘$task_id’ as $task_id variable and ‘$post_id’ as $post_id variable. we will set necessary values before sending of a request. for example: http://your-server.com/pingscript?taskId=$task_id http://your-server.com/pingscript?taskId=$task_id&postId=$post_id

When setting tasks, you send tasks data in the array using data field. 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 such feature, you can use this field to associate the set tasks with identifiers at your system.

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

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly if status=“error”the list of possible errors can be found below.

code

integer

error code

message

string

text description of error

results_time

string

execution time, seconds

results_count

string

number of elements in the array ofresults

results

array

results array of tasks setting

task_id

integer

unique task identifier in our systemyou can use task_id to request task results any time within the next 30 days.

status

string

results of this task setting“ok” - success“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly if status=“error”the list of possible errors can be found below.

code

integer

error code

message

string

text description of error

post_id

string

index in the array received in a POST request

post_key

string

key received in a POST requestkeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

se_id

integer

search engine idif status=“ok”, then this field will be always filledYou can use it for finding relations between your and our search engines.

loc_id

integer

search engine location idif status=“ok”, then this field will be always filledYou can use it for finding relations between your and our search engines.

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

Possible errors codes

Error Code

Meaning

404

“not found or not enough data: site” - you didn’t specify a website in the task

404

“not found or not enough data: search engine” - you’ve specified nonexistent se_id or a search engine wasn’t found by specified se_name

404

“not found or not enough data: location” - you’ve specified nonexistent loc_id or a location of a search engine wasn’t found by specified loc_name_canonical

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 fielddata. POST data should be represented as an array and added to the field data: array(‘data’ => $post_array_for_tasks)

501

“invalid data” - data in the field data isn’t an array with the required structure.

500

“internal error” - some internal error. We did our best to not 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/login

<?phprequire('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/login
$client=newRestClient('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;?>

fromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")response=client.get("/v2/srp_extra_tasks_get")ifresponse["status"]=="error":print("error. Code: %d Message: %s"%(response["error"]["code"],response["error"]["message"]))else:print(response["results"])

GET https://api.dataforseo.com/v2/srp_extra_tasks_getYou are not charged when receiving results

You can get the list of completed tasks that have not been collected yet. Note that all collected results are automatically erased from the list.

By indicating the pingback_url or the postback_url you get the list of completed tasks to a specific url, avoiding the extra srp_extra_tasks_get command. GET requests will be sent to the pingback_url, POST requests will be sent to the postback_url.

The list of completed results will be enclosed in the results field of the API response array.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly 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 ofresults

results

array

results array of tasks

task_id

integer

unique task identifier in our systemin the future you will be able to use it within 30 days to request results of this task any time

post_id

string

index in the array received in a POST array

post_key

string

key received in a POST arraykeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

se_id

integer

search engine idYou can use it for finding relations between your and our search engines

loc_id

integer

search engine location idYou can use it for finding relations between your and our search engines.

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

post_key

string

keyreceived in a POST arraykeyword 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 provide exact results

result_datetime

string

date and time when a result was receivedin 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 at your profile settings is used

result_spell

string

auto correction of a search engineif a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engine

measurement unitsshows which measurement units are used in the rating fieldthere are two possible options: stars, percents

rating_max

integer

maximum value for a rating

paid

boolean

paid advertisement

‘map’ element in SERP

type

string

type of element = ‘map’

position

integer

position in the SERP

url

string

relevant URL

title

string

snippet header in the SERP

‘twitter’ element in SERP

type

string

type of element = ‘twitter’

position

integer

position in the SERP

url

string

URL of the twitter homepage

title

string

title of the twitter

items

array

array of items

url

string

URL of the tweet

tweet

string

tweet message

date

string

date of tweet message

‘shopping’ element in SERP

type

string

type of element = ‘shopping’

position

integer

position in the SERP

title

string

title of the product in google shopping

items

array

array of items

title

string

title of the product

url

string

URL of the product

price

string

price of the product

source

string

source

‘video’ element in SERP

type

string

type of element = ‘video’

position

integer

position in the SERP

items

array

array of URL videos

url

string

URL of the video

title

string

title of the video

source

string

source of the video

‘images’ element in SERP

type

string

type of element = ‘images’

position

integer

position in the SERP

url

string

URL of the image

title

string

title of the image

position

integer

position in the SERP

items

array

array of URL images

url

string

URL of the image

alt

string

alt attribute

‘google flights’ element in SERP

type

string

type of element = ‘google_flights’

position

integer

position in the SERP

url

string

URL of current tickets

title

string

title

position

integer

position in the SERP

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

position

integer

position in the SERP

items

array

array of vacancies

url

string

URL of this vacancy

snippet

string

snippet

author

string

author

date

string

date of this vacancy

type

string

type of work

‘related search’ element in SERP

type

string

type of element = ‘related_search’

position

integer

position in the SERP

title

string

title of the related search element

items

array

array of related keywords

‘related’ element in SERP

type

string

type of element = ‘related’

position

integer

position in the SERP

items

array

array of related keywords

right

array

results array from the right side of the SERP with extra elementshere you can find the following elements: knowledge_graph

‘knowledge graph’ element in SERP

type

string

type of element = ‘knowledge_graph’

position

integer

position in the SERP

url

string

relevant URL in the SERP

title

string

header in the SERP

subtitle

string

subtitle in the SERP

description

string

text of knowledge graph

parts

array

array of knowledge graph text items

Possible errors 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 specified parameters

Setting Google Reviews Tasks

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

<?phprequire('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/login
$client=newRestClient('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;?>

fromrandomimportRandomfromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")rnd=Random()#you can set as "index of post_data" your ID, string, etc. we will return it with all results.post_data[rnd.randint(1,30000000)]=dict(priority=1,se_language="English",loc_name_canonical="London,England,United Kingdom",se_deep=50,sort_by="highest_rating",key="hedonism wines")post_data[rnd.randint(1,30000000)]=dict(priority=1,se_language="English",loc_id=1006886,se_deep=50,sort_by="highest_rating",key_id=30778900)response=client.post("/v2/srp_google_reviews_tasks_post",dict(data=post_data))ifresponse["status"]=="error":print("error. Code: %d Message: %s"%(response["error"]["code"],response["error"]["message"]))else:print(response["results"])

usingSystem;usingSystem.Collections.Generic;usingSystem.Linq;usingSystem.Net.Http;usingSystem.Net.Http.Headers;usingSystem.Text;usingSystem.Threading.Tasks;usingNewtonsoft.Json;namespaceDataForSeoDemos{publicstaticpartialclassDemos{publicstaticasyncTasksrp_google_reviews_tasks_post(){varhttpClient=newHttpClient{BaseAddress=newUri("https://api.dataforseo.com/"),//Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginDefaultRequestHeaders={Authorization=newAuthenticationHeaderValue("Basic",Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}};varrnd=newRandom();//you can set as "index of post_data" your ID, string, etc. we will return it with all results.varpostObject=newDictionary<int,object>{[rnd.Next(1,30000000)]=new{priority=1,se_language="English",loc_name_canonical="London,England,United Kingdom",se_deep=50,sort_by="highest_rating",key="hedonism wines"},[rnd.Next(1,30000000)]=new{priority=1,se_language="English",loc_id=1006886,se_deep=50,sort_by="highest_rating",key_id=30778900}};vartaskPostResponse=awaithttpClient.PostAsync("v2/srp_google_reviews_tasks_post",newStringContent(JsonConvert.SerializeObject(new{data=postObject})));varobj=JsonConvert.DeserializeObject<dynamic>(awaittaskPostResponse.Content.ReadAsStringAsync());if(obj.status=="error")Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");else{foreach(varresultinobj.results){vartaskState=((IEnumerable<dynamic>)result).First();if(taskState.status=="error")Console.WriteLine($"Error in task with post_id {taskState.post_id}. Code: {taskState.error.code} Message: {taskState.error.message}");Console.WriteLine(taskState);}}}}}

Currently available only for “google”.POST https://api.dataforseo.com/v2/srp_google_reviews_tasks_postThe credits are charged both for the setting of a task and getting of its results.The cost can be calculated on the Home Page SERP API.

All the data included in the POST request should be in the JSON format (UTF-8 encoding). The tasks shall be set through the POST method, by placing the tasks array into the data field. It is not recommended to set more than 100 tasks at once due to the different task variations you are likely to use. Note that the usage of the url field slows down the tasks processing. On the contrary, by using system identifiers (loc_id, key_id), you can accelerate the tasks processing and set more than 100 tasks at once.

You can get the completed task results via the unique task_id. Alternatively, you may indicate the pingback_url or postback_url to get task results send to a specific url.

Description of the fields for a task setting:

Name of a field

Type

Description

priority

integer

execution priorityoptional fieldcan have such values:1 - normal execution priority (set by default)2 - high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Home Page SERP API.

location idoptional field if you specify loc_name_canonicalyou must choose one of the fields loc_id or loc_name_canonicalthe list of available locations loc_id you can get by separate request List of Locationsalso when the information about set task is returned you will get loc_idplease notice that we use Google Geographical Targeting including such types of locations as CountryStateRegionMunicipalityCity, that’s why you can specify loc_id appropriate Criteria ID

loc_name_canonical

string

full name of locationoptional field if you specify loc_idyou must choose one of the fields loc_id or loc_name_canonicalthe list of available locations loc_name_canonical you can get by separate List of Locationsplease notice that we use Google Geographical Targeting including such types of locations as CountryStateRegionMunicipalityCity, that’s why you can specify loc_name_canonical appropriate Canonical Nameexample: “London,England,United Kingdom”

key_id

integer

keyword idoptional field if you specify keywhen 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 you to save key_id returned after the task was set and use this field in the future.

key

string

keywordoptional field if you specify key_idUTF-8 encodingall %## 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:’, ‘cache:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’ then the charge per task will be multiplied by 10.

additional parameters of search queryoptional fieldfor instance, if you want to disable auto correction of misspelling in the search query for google, you can specify “&nfpr=1”

postback_url

string

return URL for sending task resultsoptional fieldif you specify this URL there will be no need to pick up tasks using Get SERP Tasks Results. We will send a result of a completed task by POST request for URL as soon as a task is completed.

pingback_url

string

notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use string ‘$task_id’ as $task_id variable and ‘$post_id’ as $post_id variable. we will set necessary values before sending of a request. for example: http://your-server.com/pingscript?taskId=$task_id http://your-server.com/pingscript?taskId=$task_id&postId=$post_id

When setting tasks, you send tasks data in the array using data field. 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 such feature, you can use this field to associate the set tasks with identifiers at your system.

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

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly if status=“error”the list of possible errors can be found below.

code

integer

error code

message

string

text description of error

results_time

string

execution time, seconds

results_count

string

number of elements in the array ofresults

results

array

results array of tasks setting

task_id

integer

unique task identifier in our systemyou can use task_id to request task results any time within the next 30 days.

status

string

results of this task setting“ok” - success“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly if status=“error”the list of possible errors can be found below.

code

integer

error code

message

string

text description of error

post_id

string

index in the array received in a POST request

post_key

string

key received in a POST requestkeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

loc_id

integer

location idif status=“ok”, then this field will be always filled

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

Possible errors codes

Error Code

Meaning

404

“not found or not enough data: location” - you’ve specified nonexistent loc_id or a location of a search engine wasn’t found by specified loc_name_canonical

“invalid ‘data’ field” - probably you haven’t passed data for the tasks in the fielddata. POST data should be represented as an array and added to the field data: array(‘data’ => $post_array_for_tasks)

501

“invalid data” - data in the field data isn’t an array with the required structure.

500

“internal error” - some internal error. We did our best to not 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/login

<?phprequire('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/login
$client=newRestClient('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;?>

fromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")response=client.get("/v2/srp_google_reviews_tasks_get")ifresponse["status"]=="error":print("error. Code: %d Message: %s"%(response["error"]["code"],response["error"]["message"]))else:print(response["results"])

GET https://api.dataforseo.com/v2/srp_google_reviews_tasks_getYou are not charged when receiving results

You can get the list of completed tasks that have not been collected yet. Note that all collected results are automatically erased from the list.

By indicating the pingback_url or the postback_url you get the list of completed tasks to a specific url, avoiding the srp_google_reviews_tasks_get command. GET requests will be sent to the pingback_url, POST requests will be sent to the postback_url.

The list of completed results will be enclosed in the results field of the API response array.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly 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 ofresults

results

array

results array of tasks

task_id

integer

unique task identifier in our systemin the future you will be able to use it within 30 days to request results of this task any time

post_id

string

index in the array received in a POST array

post_key

string

key received in a POST arraykeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

loc_id

integer

location id

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

results_count

integer

total number of results in the reviews list

result_se_check_url

string

direct URL to search engine results You can use it to make sure that we provide exact results

Get Google Reviews Results by task_id

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

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

GET https://api.dataforseo.com/v2/srp_google_reviews_tasks_get/$task_idYou are charged for each GET request for results receiving.The cost can be calculated on the Home Page SERP API.

Description of the fields for a request setting:

Name of a field

Type

Description

task_id

string

unique task identifier in our systemin the future you will be able to use it within 30 days to request results of this task any time.

As a response of API server you will receive array in the field resultsof which there will be a list of complete results.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, then you can see more detailed information of array error error

error

array

informational array of erroronly 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 ofresult

results

array

results array of tasks setting

task_id

integer

unique task identifier in our systemyou can use task_id to request task results any time within the next 30 days.

post_id

string

index in the array received in a POST request

loc_id

integer

location idLocation identifier that helps to find the needed location in our system.

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

post_key

string

keyreceived in a POST arraykeyword 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 provide exact results

result_datetime

string

date and time when a result was receivedin 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 at your profile settings is used

result_title

string

title in reviews list

result_subtitle

string

subtitle in reviews list

result_stat

array

ratings information about the reviews element of a resultempty array if result does not have a rating

rating

integer/float

ratingthe popularity rate based on reviews and displayed in the reviews list

rating_max

integer

maximum value for a rating

result_reviews_count

integer

total number of results in the reviews list

result

array

list of reviews

position

integer

position in the reviews list

review_text

string

text of the review

time_ago

string

when the review was written and review’s source

stat

array

ratings information about the reviews element of a resultempty array if result does not have a rating

rating

integer/float

ratingthe popularity rate based on reviews and displayed in the reviews list

rating_max

integer

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

if a user is “local guide”

profile_name

string

name of the user who wrote a review

profile_url

string

URL of profile of the user who wrote a review

profile_image_url

string

URL of profile image of the user who wrote a review

owner_answer

string

owner’s answer to a review

owner_time_ago

string

when an answer was written

Possible errors 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” - reviews list is empty. Check if you have added key correctly

404

“top results not found” - there is no reviews list with specified parameters

Merchant API

The DataForSEO Merchant API provides is the most convenient way to get reliable e-commerce data about prices, products, and retailers. We have selected the most popular e-commerce platforms and would add even more in the nearest future. After you connect to Merchant API, you will be able to collect up-to-date information for analyzing competitors and making better business decisions.

Google Shopping

Google Shopping API provides TOP100 results at Google Shopping based on a keyword (product). Moreover, Google Shooping HTML service can provide you with the HTML page of SERP for any keyword. Using Google Shopping Shops you can get a list of shops by specifying product ID (the unique identifier of a product in Google Shopping).

The operating principle of Google Shopping API is similar to Rank Tracker API. The main difference is that with Google Shopping API you don’t recive all completed results at once. What you recive is a list of task_id of completed results, so each result should be requested separately using its task_id. This is due to huge amounts of data included in each Google Shopping API task.

You can find a list of available Google Shopping countries on this page.

Tasks with higher priority are processed faster. Therefore, the delivery of such results takes less time.

Setting Google Shopping Tasks

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

<?phprequire('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/login
$client=newRestClient('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();//for example, some data selection cycle for tasks
for($i=0;$i<3;$i++){// 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/merchant_google_shopping_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=shoes&tbm=shop&tbs=vw:l&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 )
// You must choose a search engine with the word "shopping" included into the "se_name" field
// If a task was set successfully, this *_id will be returned in results: 'v2/merchant_google_shopping_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 shopping","se_language"=>"English","loc_name_canonical"=>"London,England,United Kingdom","key"=>mb_convert_encoding("shoes","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
// You must choose a search engine with the word "shopping" included into the "se_name" field
$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"=>2933,"loc_id"=>1006886,"key_id"=>68415);//This example has a cycle of up to 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
if(count($post_array)>99){try{// POST /v2/merchant_google_shopping_tasks_post/$data
// $tasks_data must by array with key 'data'
$task_post_result=$client->post('v2/merchant_google_shopping_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";}}}if(count($post_array)>0){try{// POST /v2/merchant_google_shopping_tasks_post/$data
// $tasks_data must by array with key 'data'
$task_post_result=$client->post('v2/merchant_google_shopping_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;?>

fromrandomimportRandomfromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")rnd=Random()#you can set as "index of post_data" your ID, string, etc. we will return it with all results.post_data=dict()post_data[rnd.randint(1,30000000)]=dict(priority=1,url="https://www.google.co.uk/search?q=shoes&tbm=shop&tbs=vw:l&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS")post_data[rnd.randint(1,30000000)]=dict(priority=1,se_name="google.co.uk shopping",se_language="English",loc_name_canonical="London,England,United Kingdom",key="shoes")post_data[rnd.randint(1,30000000)]=dict(priority=1,se_id=2933,loc_id=1006886,key_id=68415)response=client.post("/v2/merchant_google_shopping_tasks_post",dict(data=post_data))ifresponse["status"]=="error":print("error. Code: %d Message: %s"%(response["error"]["code"],response["error"]["message"]))else:print(response["results"])

usingSystem;usingSystem.Collections.Generic;usingSystem.Linq;usingSystem.Net.Http;usingSystem.Net.Http.Headers;usingSystem.Text;usingSystem.Threading.Tasks;usingNewtonsoft.Json;namespaceDataForSeoDemos{publicstaticpartialclassDemos{publicstaticasyncTaskmerchant_google_shopping_tasks_post(){varhttpClient=newHttpClient{BaseAddress=newUri("https://api.dataforseo.com/"),//Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginDefaultRequestHeaders={Authorization=newAuthenticationHeaderValue("Basic",Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}};varrnd=newRandom();//you can set as "index of post_data" your ID, string, etc. we will return it with all results.varpostObject=newDictionary<int,object>{[rnd.Next(1,30000000)]=new{priority=1,url="https://www.google.co.uk/search?q=shoes&tbm=shop&tbs=vw:l&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"},[rnd.Next(1,30000000)]=new{priority=1,se_name="google.co.uk shopping",se_language="English",loc_name_canonical="London,England,United Kingdom",key="shoes"},[rnd.Next(1,30000000)]=new{priority=1,se_id=2933,loc_id=1006886,key_id=68415}};vartaskPostResponse=awaithttpClient.PostAsync("v2/merchant_google_shopping_tasks_post",newStringContent(JsonConvert.SerializeObject(new{data=postObject})));varobj=JsonConvert.DeserializeObject<dynamic>(awaittaskPostResponse.Content.ReadAsStringAsync());if(obj.status=="error")Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");else{foreach(varresultinobj.results){vartaskState=((IEnumerable<dynamic>)result).First();if(taskState.status=="error")Console.WriteLine($"Error in task with post_id {taskState.post_id}. Code: {taskState.error.code} Message: {taskState.error.message}");Console.WriteLine(taskState);}}}}}

POST https://api.dataforseo.com/v2/merchant_google_shopping_tasks_postThe credits are charged both for the setting of a task and getting of its results.The cost can be calculated on the Home Page Merchant API.

All the data included in the POST request should be in the JSON format (UTF-8 encoding). The tasks shall be set through the POST method, by placing the tasks array into the data field. It is not recommended to set more than 100 tasks at once due to the different task variations you are likely to use. Note that the usage of the url field slows down the tasks processing. On the contrary, by using system identifiers (se_id, lod_id, key_id), you can accelerate the tasks processing and set more than 100 tasks at once.

You can get the completed task results via the unique task_id. Alternatively, you may indicate the pingback_url or postback_url to get task results send to a specific URL.

Description of the fields for a task setting:

Name of a field

Type

Description

priority

integer

execution priorityoptional fieldcan take the following values:1 - normal execution priority (set by default)2 - high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Home Page Merchant API.

url

string

direct URL of a search queryoptional fieldyou can specify a direct URL, it will be sorted to the neccessary fields. Such method is more time-consuming and moreover it requires that you specify the exact language and location in the URL. We don’t recommend using this method.example:https://www.google.co.uk/search?q=shoes&tbm=shop&tbs=vw:l&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS

se_id

integer

search engine idoptional field, if you specify se_nameyou must choose one of the fields se_id or se_namethe list of availiable search engines with se_id can be accessed by sending a separate request to the List of Search Enginesto get se_id for Google Shopping you must choose a search engine with the word “shopping” included into the “se_name” fieldalso, you can find se_id in the array returned after the task setting is complete

se_name

string

search engine domainoptional field if you specify se_idyou must choose one of the fields se_id or se_namethe list of availiable search engines with se_id can be accessed by sending a separate request to the List of Search Enginesyou must specify a search engine where field “se_name” contains the word “shopping”example: “google.co.uk shopping”

se_language

string

search engine languagerequired field if se_id is not specifiedthe list of available search engines with se_languages can be accessed by sending a separate request to the List of Search Enginesexample: “English”

loc_id

integer

search engine location idoptional field if you specify loc_name_canonicalyou must choose one of the fields loc_id or loc_name_canonicalthe list of avaliabale search engine locations with loc_id can be accessed by sending a separate request to the List of Locationsalso, you can find loc_id in the array returned after the task setting is completeplease note that we use Google Geographical Targeting with the foolowing location types: CountryStateRegionMunicipalityCity, that’s why you can specify loc_id appropriate Criteria ID

loc_name_canonical

string

full name of search engine locationoptional field if you specify loc_idyou must choose one of the fields loc_id or loc_name_canonicalthe list of availiable search engine locations with loc_name_canonical can be accessed by sending a separate request to the List of Locationsplease note that we use Google Geographical Targeting with the foolowing location types: CountryStateRegionMunicipalityCity, that’s why you can specify loc_name_canonical appropriate Canonical Nameexample: “London,England,United Kingdom”

key_id

integer

keyword idoptional field if you specify keywhen 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 you to save key_id returned after the task was set and use this field in the future.

key

string

keywordoptional field if you specify key_idUTF-8 encodingall %## 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”

price_min

integer

minimum search results price filteroptional fieldminimum value: 0

price_max

integer

maximum search results price filteroptional field

price_orderby

string

sorting by pricesoptional fieldsearch results filter type can take two possible values:abc - in ascending orderdesc - in descending order

se_param_add

string

additional parameters of search queryoptional fieldfor instance, if you want to disable auto correction of misspelling in the search query, you can specify “&nfpr=1”

postback_url

string

return URL for sending task resultsoptional fieldif you specify this URL there will be no need to pick up tasks using Get Google Shopping Tasks Results. We will send a result of a completed task by POST request for URL as soon as a task is completed.

pingback_url

string

notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use string ‘$task_id’ as $task_id variable and ‘$post_id’ as $post_id variable. we will set necessary values before sending a request. for example http://your-server.com/pingscript?taskId=$task_id http://your-server.com/pingscript?taskId=$task_id&postId=$post_id

When setting tasks, you send tasks data in the array using data field. 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 such feature, you can use this field to associate the set tasks with identifiers at your system.

Here are some examples:

There is an identifier at your system of a task that you set to collect data, let it be 100500. When you set the task you send it in the data array with 100500 index like here: "{"data":{"100500":{"priority":1,"se_name":"google.co.uk shopping","se_language":"English","loc_name_canonical":"London,England,United Kingdom","key":"shoes"}}}"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 at your system.

You want to associate other kinds of data at your system. For instance:

a keyword has id=1238 at your system,

a search engine 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 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 necessary data will have this value 1238#43289#97435#2#9999. As a result, the request for setting of a task will look like this:
"{"data":{"1238#43289#97435#2#9999":{"priority":1,"se_name":"google.co.uk shopping","se_language":"English","loc_name_canonical":"London,England,United Kingdom","key":"shoes"}}}"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 API server you will receive JSONarray in the field results of which there will be an information appropriate to the set tasks.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, you can see the more detailed information about the possible cause of an error in the error array

error

array

informational array of erroronly if status=“error”the list of possible errors can be found below.

code

integer

error code

message

string

text description of error

results_time

string

execution time, seconds

results_count

integer

number of elements in the array of resultsresults

results

array

results array of tasks setting

task_id

integer

unique task identifier in our systemyou can use task_id to request task results any time within the next 30 days.

status

string

results of this task setting“ok” - success“error” - errorif status=“error”, you can see the more detailed information about the possible cause of an error in the error array

error

array

informational array of erroronly if status=“error”the list of possible errors can be found below.

code

integer

error code

message

string

text description of error

post_id

string

index in the array received in a POST request

post_key

string

key received in a POST requestkeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

se_id

integer

search engine idif status=“ok”, then this field will be always filledLocation identifier that helps to find the needed location in our system.

loc_id

integer

search engine location idif status=“ok”, then this field will be always filledLocation identifier that helps to find the needed location in our system.

key_id

integer

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

Possible errors codes

Error Code

Meaning

404

“not found or not enough data: search engine” - you’ve specified nonexistent se_id or a search engine wasn’t found by specified se_name

404

“not found or not enough data: location” - you’ve specified nonexistent loc_id or a location of a search engine wasn’t found by specified loc_name_canonical

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 fielddata. POST data should be represented as an array and added to the field data: array(‘data’ => $post_array_for_tasks)

501

“invalid data” - data in the field data isn’t an array with the required structure.

500

“internal error” - some internal error. We did our best to not let this type of error ever happen.

Get Google Shopping Completed Tasks

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

<?phprequire('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/login
$client=newRestClient('https://api.dataforseo.com',null,'login','password');// #1 - get task_id list of ALL ready results
//GET /v2/merchant_google_shopping_tasks_get
$tasks_get_result=$client->get('v2/merchant_google_shopping_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;?>

fromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")response=client.get("/v2/merchant_google_shopping_tasks_get")ifresponse["status"]=="error":print("error. Code: %d Message: %s"%(response["error"]["code"],response["error"]["message"]))else:print(response["results"])

GET https://api.dataforseo.com/v2/merchant_google_shopping_tasks_getYou are not charged when receiving results

You will get the list of complete results, that you haven’t collected yet. After you collect a result the task will be removed from this list.

By indicating the pingback_url or the postback_url you get the list of completed tasks to a specific url, avoiding the extra merchant_google_shopping_tasks_get command. GET requests will be sent to the pingback_url, POST requests will be sent to the postback_url.

The list of completed results will be enclosed in the results field of the API response array.

Description of the fields in the results array:

Name of a field

Type

Description

status

string

general result“ok” - successful“error” - errorif status=“error”, you can see the more detailed information about the possible cause of an error in the error array

error

array

informational array of erroronly 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

integer

number of elements in the array of resultsresults

results

array

results array of tasks

task_id

integer

unique task identifier in our systemyou can use task_id to request task results any time within the next 30 days

post_id

string

index in the array received in a POST array

post_key

string

key received in a POST arraykeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

se_id

integer

search engine idYou can use it for finding relations between your and our search engines

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

post_key

string

key received in a POST arraykeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

result_position

integer

position in the Google Shopping SERP

result_datetime

string

date and time when a result was receivedin 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 at your profile settings is used

result_title

string

snippet header in the Google Shopping SERP

result_description

string

product description

result_product_id

string

product IDthe unique identifier of a product in Google Shoppingif there are no values, you will get null

product rating(represented by star symbols) from 0 to 5if there are no values, you will get null

result_reviews_count

integer

number of feedbacksleft by users for a certain productif there are no values, you will get null

result_shop_stat

float/integer

shop ratingbased on data collected by Google and/or its partnersin the event that the measurement unit in the result_shop_stat_type is equal to stars, the value can be in the range 0 to 5if the measurement unit is equal to percents, the value can be in the range 0 to 100if there are no values, you will get null

result_shop_stat_type

string

measurement unitsshows which measurement units are used in the result_shop_stat fieldthere are two possible options: stars, percentsif there are no values, you will get null

result_shop_stat_count

integer

number of shop feedbacksleft by users collected by Google and/or its partnersif there are no values, you will get null

result_tags

array

tags specified within adsif there is no data, the array will be empty

result_spell

string

auto correction of a search engineif a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engineif there are no values, you will get null

result_url

string

a URL of shop where a specified product is being sold

result_shopping_url

string

a URL to the product in the Google Shopping platformif there are no values, you will get null

result_se_check_url

string

direct URL to search engine results you can use it to make sure that we provide exact results

paid

array

results array ofpaidGoogle Shopping SERP

task_id

integer

unique task identifier in our systemyou can use task_id to request task results any time within the next 30 days

keyword id in our systemif you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id

post_key

string

key received in a POST arraykeyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)

result_position

integer

position in the Google Shopping SERP

result_datetime

string

date and time when a result was receivedin 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 at your profile settings is used

result_title

string

snippet header in the Google Shopping SERP

result_snippet

string

snippet in the Google Shopping SERP

result_location

string

ad positioncan have the following values: top, bottom

result_spell

string

auto correction of a search engineif a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engineif there are no values, you will get null

result_url

string

relevant URL in the Google Shopping SERP

result_se_check_url

string

direct URL to search engine results you can use it to make sure that we provide exact results

extra

array

results array ofextraGoogle Shopping SERP elements

related

array

array of ‘related search queries’ stringsthis array will be present if the element is in the Google Shopping SERP

Possible errors 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” - Google Shopping SERP is empty. Check if you have added key correctly

404

“top results not found” - there is no Google Shopping SERP with specified parameters

Setting Google Shopping HTML Tasks

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

<?phprequire('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/login
$client=newRestClient('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();//for example, some data selection cycle for tasks
for($i=0;$i<3;$i++){// 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/merchant_google_shopping_html_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=shoes&tbm=shop&tbs=vw:l&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 )
// You must choose a search engine with the word "shopping" included into the "se_name" field
// If a task was set successfully, this *_id will be returned in results: 'v2/merchant_google_shopping_html_tasks_get' 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 shopping","se_language"=>"English","loc_name_canonical"=>"London,England,United Kingdom","key"=>mb_convert_encoding("shoes","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
// You must choose a search engine with the word "shopping" included into the "se_name" field
$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"=>2933,"loc_id"=>1006886,"key_id"=>68415);//This example has a cycle of up to 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
if(count($post_array)>99){try{// POST /v2/merchant_google_shopping_tasks_post/$data
// $tasks_data must by array with key 'data'
$task_post_result=$client->post('v2/merchant_google_shopping_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";}}}if(count($post_array)>0){try{// POST /v2/merchant_google_shopping_html_tasks_post/$data
// $tasks_data must by array with key 'data'
$task_post_result=$client->post('v2/merchant_google_shopping_html_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;?>

fromrandomimportRandomfromclientimportRestClient#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginclient=RestClient("login","password")rnd=Random()#you can set as "index of post_data" your ID, string, etc. we will return it with all results.post_data=dict()post_data[rnd.randint(1,30000000)]=dict(priority=1,url="https://www.google.co.uk/search?q=shoes&tbm=shop&tbs=vw:l&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS")post_data[rnd.randint(1,30000000)]=dict(priority=1,se_name="google.co.uk shopping",se_language="English",loc_name_canonical="London,England,United Kingdom",key="shoes")post_data[rnd.randint(1,30000000)]=dict(priority=1,se_id=2933,loc_id=1006886,key_id=68415)response=client.post("/v2/merchant_google_shopping_html_tasks_post",dict(data=post_data))ifresponse["status"]=="error":print("error. Code: %d Message: %s"%(response["error"]["code"],response["error"]["message"]))else:print(response["results"])

usingSystem;usingSystem.Collections.Generic;usingSystem.Linq;usingSystem.Net.Http;usingSystem.Net.Http.Headers;usingSystem.Text;usingSystem.Threading.Tasks;usingNewtonsoft.Json;namespaceDataForSeoDemos{publicstaticpartialclassDemos{publicstaticasyncTaskmerchant_google_shopping_html_tasks_post(){varhttpClient=newHttpClient{BaseAddress=newUri("https://api.dataforseo.com/"),//Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/loginDefaultRequestHeaders={Authorization=newAuthenticationHeaderValue("Basic",Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}};varrnd=newRandom();//you can set as "index of post_data" your ID, string, etc. we will return it with all results.varpostObject=newDictionary<int,object>{[rnd.Next(1,30000000)]=new{priority=1,url="https://www.google.co.uk/search?q=shoes&tbm=shop&tbs=vw:l&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"},[rnd.Next(1,30000000)]=new{priority=1,se_name="google.co.uk shopping",se_language="English",loc_name_canonical="London,England,United Kingdom",key="shoes"},[rnd.Next(1,30000000)]=new{priority=1,se_id=2933,loc_id=1006886,key_id=68415}};vartaskPostResponse=awaithttpClient.PostAsync("v2/merchant_google_shopping_html_tasks_post",newStringContent(JsonConvert.SerializeObject(new{data=postObject})));varobj=JsonConvert.DeserializeObject<dynamic>(awaittaskPostResponse.Content.ReadAsStringAsync());if(obj.status=="error")Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");else{foreach(varresultinobj.results){vartaskState=((IEnumerable<dynamic>)result).First();if(taskState.status=="error")Console.WriteLine($"Error in task with post_id {taskState.post_id}. Code: {taskState.error.code} Message: {taskState.error.message}");Console.WriteLine(taskState);}}}}}

POST https://api.dataforseo.com/v2/merchant_google_shopping_html_tasks_postThe credits are charged both for the setting of a task and getting of its results.The cost can be calculated on the Home Page Merchant API.

All the data included in the POST request should be in the JSON format (UTF-8 encoding). The tasks shall be set through the POST method, by placing the tasks array into the data field. It is not recommended to set more than 100 tasks at once due to the different task variations you are likely to use. Note that the usage of the url field slows down the tasks processing. On the contrary, by using system identifiers (se_id, lod_id, key_id), you can accelerate the tasks processing and set more than 100 tasks at once.

You can get the completed task results via the unique task_id. Alternatively, you may indicate the pingback_url or postback_url to get task results send to a specific URL.

Description of the fields for a task setting:

Name of a field

Type

Description

priority

integer

execution priorityoptional fieldcan take the following values:1 - normal execution priority (set by default)2 - high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Home Page Merchant API.

url

string

direct URL of a search queryoptional fieldyou can specify a direct URL, it will be sorted to the neccessary fields. Such method is more time-consuming and moreover it requires that you specify the exact language and location in the URL. We don’t recommend using this method.example:https://www.google.co.uk/search?q=shoes&tbm=shop&tbs=vw:l&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS

se_id

integer

search engine idoptional field, if you specify se_nameyou must choose one of the fields se_id or se_namethe list of availiable search engines with se_id can be accessed by sending a separate request to the List of Search Enginesto get se_id for Google Shopping you must choose a search engine with the word “shopping” included into the “se_name” fieldalso, you can find se_id in the array returned after the task setting is complete

se_name

string

search engine domainoptional field if you specify se_idyou must choose one of the fields se_id or se_namethe list of availiable search engines with se_id can be accessed by sending a separate request to the List of Search Enginesyou must specify a search engine where field “se_name” contains the word “shopping”example: “google.co.uk shopping”

se_language

string

search engine languagerequired field if se_id is not specifiedthe list of available search engines with se_languages can be accessed by sending a separate request to the List of Search Enginesexample: “English”

loc_id

integer

search engine location idoptional field if you specify loc_name_canonicalyou must choose one of the fields loc_id or loc_name_canonicalthe list of avaliabale search engine locations with loc_id can be accessed by sending a separate request to the List of Locationsalso, you can find loc_id in the array returned after the task setting is completeplease note that we use Google Geographical Targeting with the foolowing location types: CountryStateRegionMunicipalityCity, that’s why you can specify loc_id appropriate Criteria ID

loc_name_canonical

string

full name of search engine locationoptional field if you specify loc_idyou must choose one of the fields loc_id or loc_name_canonicalthe list of availiable search engine locations with loc_name_canonical can be accessed by sending a separate request to the List of Locationsplease note that we use Google Geographical Targeting with the foolowing location types: CountryStateRegionMunicipalityCity, that’s why you can specify loc_name_canonical appropriate Canonical Nameexample: “London,England,United Kingdom”

key_id

integer

keyword idoptional field if you specify keywhen 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 you to save key_id returned after the task was set and use this field in the future.

key

string

keywordoptional field if you specify key_idUTF-8 encodingall %## 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”

price_min

integer

minimum search results price filteroptional fieldminimum value: 0

price_max

integer

maximum search results price filteroptional field

price_orderby

string

sorting by pricesoptional fieldsearch results filter type can take two possible values:abc - in ascending orderdesc - in descending order

se_param_add

string

additional parameters of search queryoptional fieldfor instance, if you want to disable auto correction of misspelling in the search query, you can specify “&nfpr=1”