NAVNavbar
Logo
php python csharp java

Merchant API


The DataForSEO Merchant API is the most convenient way to get reliable e-commerce data about prices, products, and retailers. We have selected the top two e-commerce platforms: Google Shopping and Amazon, and we plan to add even more in the nearest future. Merchant API will provide you with all essential metrics for conducting comprehensive competitor analysis, price monitoring, and market niche research. It will help you to adjust and optimize the assortment and pricing according to different locations as well as open up new business opportunities based on quality real-time data.

Note: The new version of the Merchant API is available!
Check the DataForSEO v3 Docs >>
Learn more about DataForSEO v3 >>

We will continue to support the v2 of the DataForSEO API. None of the DataForSEO v2 features and endpoints will be removed or deprecated in the foreseeable future. However, all the new features and updates will be released in DataForSEO v3 and thus will not be supported in v2.

Google Shopping


Google Shopping API provides the TOP 100 results from Google Shopping based on a keyword (product). Moreover, Google Shopping HTML service can provide you with the HTML page of SERP for any keyword. If you specify the product ID (the unique product identifier in Google Shopping) using Google Shopping Sellers, you can get a list of shops.

The operating principle of Google Shopping API is similar to that of  Rank Tracker API. The main difference is that with Google Shopping API, you don’t receive all completed results at once. Instead, you will receive a list of task identifiers (task_id) that are unique and assigned to each separate task. You can then use the task’s task_id to return its results. This is due to the vast 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/#api_dashboard

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

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

$post_array = array();

// 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) > 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;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 3,
    "results": {
        "11913049": {
            "post_id": 11913049,
            "post_key": "shoes",
            "task_id": 404227822,
            "se_id": 2933,
            "loc_id": 1006886,
            "key_id": 68415,
            "status": "ok"
        },
        "20469414": {
            "post_id": 20469414,
            "post_key": "shoes",
            "task_id": 404227823,
            "se_id": 2933,
            "loc_id": 1006886,
            "key_id": 68415,
            "status": "ok"
        },
        "6273173": {
            "post_id": 6273173,
            "post_key": "shoes",
            "task_id": 404227824,
            "se_id": 2933,
            "loc_id": 1006886,
            "key_id": 68415,
            "status": "ok"
        }
    }
}


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, sending the array of tasks into the data field. It is not recommended to set more than 100 tasks at a time due to different task variations you are likely to use. Note that the usage of the url field slows down the the processing of the task. On the contrary, using system identifiers (se_idloc_idkey_id), you can accelerate the task’s processing and set more than 100 tasks at a time.

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. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

Description of the fields for setting a task:

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

url string direct URL of a search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=shoes&tbm=shop&tbs=vw:l&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
se_id integer search engine id
optional field, if you specify se_name
you must choose one of the fields se_id or se_name
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
you must choose a search engine with the word “shopping” included in the se_id field to get se_id for Google Shopping
also, when the information about the set task is returned, you will get se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields se_id or se_name
you can get the list of available search engines with se_id by making a separate request to the List of Search Engines
you must specify a search engine where the field se_name contains the word “shopping”
example: “google.co.uk shopping”
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with their se_languages by making a separate request to the List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you must choose one of the fields loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_idby making a separate request to the List of Locations
when the information about the set task is returned you will get loc_id
please note that we use Google Geographical Targeting  including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonicalby making a separate request to the List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
key_id integer keyword id
optional field if you specify key
when you set a task for the first time you won’t be able to know this field. But if you plan to collect rankings for this keyword we recommend saving the key_id returned after the task was set and use this field to get results later on.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”
price_min integer the minimum search results price filter
optional field
the minimum value: 0
price_max integer the maximum search results price filter
optional field
price_orderby string sorting by prices
optional field
search results filter type can have two possible values:
asc – in ascending order
desc – in descending order
se_param_add string additional parameters of search query
optional field
for example, if you want to disable auto-correction the search query misspelling for google, you should use the “&nfpr=1” parameter
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify the postback URL there will be no need to use Get Google Shopping Tasks Results for obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$task_id’ string as a $task_id variable and ‘$post_id’ as $post_id variable. We will set the necessary values before sending the request. For example:
http://your-server.com/pingscript?taskId=$task_id
http://your-server.com/pingscript?taskId=$task_id&postId=$post_id


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

Here are some examples:

  1. There is an identifier in your system that corresponds to a task that you set to collect data, for example, 100500. When you set the task you send it in the data array with the 100500 index, e.g.: "{"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 in your system.
  2. You may also want to associate other kinds of data in your system. For instance:
    • a keyword has id=1238 in 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 the API server, you will receive a JSON array in the results field of which there will be information appropriate to the set tasks.

Description of the fields in the results array:

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


Possible error codes

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

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

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

    // #1 - get task_id list of ALL ready results
    //GET /v2/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;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0120 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "11577837",
            "post_key": "shoes",
            "task_id": 675785734,
            "se_id": 2933,
            "loc_id": 1006886,
            "key_id": 68415,
            "result_spell": "",
            "result_se_check_url": "https://www.google.co.uk/search?q=shoes&num=100&tbm=shop&&tbs=vw:l&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
        }
    ]
}

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

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. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

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

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:

Field name Type Descr+iption
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count integer the number of elements in the array of results results
results array results array of tasks
            task_id integer unique task identifier in our system(UInt64)
you will be able to use it within 30 days to request the results of the task at any time
            post_id string the index in the array received in the POST array
            post_key string key received in the POST array
the keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines
            loc_id integer search engine location id
Location identifier that helps to find the needed location in our system. You can use it for matching your search engines with the DataForSEO List of Search Engines
            key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
            result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by 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

Get Google Shopping Results by task_id

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

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

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

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

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0135 sec.",
    "results_count": 100,
    "results": {
        "organic": [
            {
                "task_id": 676669794,
                "post_id": "949845416541",
                "se_id": 2933,
                "loc_id": 1006886,
                "key_id": 68415,
                "post_key": "shoes",
                "result_position": 1,
                "result_datetime": "2018-05-29 14:41:29 +00:00",
                "result_title": "Stradivarius Slingback mid-heel Court Shoes Woman Mustard 4",
                "result_description": "Mustard 4 - polyester,polyester,polyurethane,polyurethane thermoplastic,",
                "result_product_id": null,                
                "result_price": 19.99,
                "result_currency": "GBP",
                "result_stars": null,
                "result_reviews_count": null,
                "result_shop_stat": null,
                "result_shop_stat_type": null,
                "result_shop_stat_count": null,
                "result_tags": [],
                "result_spell": null,
                "result_best_match": false,
                "result_url": "https://www.stradivarius.com/gb/partnumbers-c1020132524p300516502.html?colorId=124&LGWCODE=1287734112437V2018;123611;7451",
                "result_shopping_url": null,
                "result_se_check_url": "https://www.google.co.uk/search?q=shoes&num=100&tbm=shop&&tbs=vw:l&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            },
            {
                "task_id": 676669794,
                "post_id": "949845416541",
                "se_id": 2933,
                "loc_id": 1006886,
                "key_id": 68415,
                "post_key": "shoes",
                "result_position": 2,
                "result_datetime": "2018-05-29 14:41:29 +00:00",
                "result_title": "Samuel Windsor Classic Oxford Shoe - Black",
                "result_description": "The Samuel Windsor commitment to quality ensures these handmade Classic black Oxford shoes will prove to be the finest - most ...",
                "result_product_id": null,
                "result_price": 45,
                "result_currency": "GBP",
                "result_stars": 4.62,
                "result_reviews_count": 1046,
                "result_shop_stat": 4.5,
                "result_shop_stat_type": "stars",
                "result_shop_stat_count": 9627,
                "result_tags": [],
                "result_spell": null,
                "result_best_match": false,
                "result_url": "https://www.samuel-windsor.co.uk/buy.cfm/oxford-shoes/classic-oxford-shoe-black/73/yes/53960?Affiliate=12,400",
                "result_shopping_url": null,
                "result_se_check_url": "https://www.google.co.uk/search?q=shoes&num=100&tbm=shop&&tbs=vw:l&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            },

            {
                "task_id": 676669794,
                "post_id": "949845416541",
                "se_id": 2933,
                "loc_id": 1006886,
                "key_id": 68415,
                "post_key": "shoes",
                "result_position": 98,
                "result_datetime": "2018-05-29 14:41:29 +00:00",
                "result_title": "ASOS DESIGN Dare Chunky Trainers - White",
                "result_description": "Trainers by ASOS DESIGN, All-white, alright?, Lace-up fastening, Padded tongue and cuff, Chunky sole, Moulded tread. Giving ...",
                "result_product_id": null,
                "result_price": 38,
                "result_currency": "GBP",
                "result_stars": null,
                "result_reviews_count": null,
                "result_shop_stat": 4.4,
                "result_shop_stat_type": "stars",
                "result_shop_stat_count": 1013,
                "result_tags": [
                    "ASOS",
                    "Trainer",
                    "Women's"
                ],
                "result_spell": null,
                "result_best_match": false,
                "result_url": "http://www.asos.com/asos/asos-design-dare-chunky-trainers/prd/9665793?&affid=14173&channelref=product+search&mk=abc&currencyid=1",
                "result_shopping_url": null,
                "result_se_check_url": "https://www.google.co.uk/search?q=shoes&num=100&tbm=shop&&tbs=vw:l&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            },
            {
                "task_id": 676669794,
                "post_id": "949845416541",
                "se_id": 2933,
                "loc_id": 1006886,
                "key_id": 68415,
                "post_key": "shoes",
                "result_position": 99,
                "result_datetime": "2018-05-29 14:41:29 +00:00",
                "result_title": "Nike Zoom Strike Men's Running Shoe - Grey",
                "result_description": "Light, simple and comfortable runner from Nike. Fitted with Zoom Air tech in the heel, for efficient and responsive cushioning ...",
                "result_product_id": "3198619856837288516",
                "result_price": 69.95,
                "result_currency": "GBP",
                "result_stars": 4,
                "result_reviews_count": 13,
                "result_shop_stat": null,
                "result_shop_stat_type": null,
                "result_shop_stat_count": null,
                "result_tags": [],
                "result_spell": null,
                "result_best_match": false,
                "result_url": "https://www.nike.com/gb/t/zoom-strike-running-shoe-XPTbL94M/AJ0189-002",
                "result_shopping_url": "https://www.google.co.uk/shopping/product/3649279603778976255?q=shoes&num=100&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS&prds=paur:ClkAsKraX2Dv16zu-Np0yyKeV4JMTK8p4ssp7ibx0X28uNZMjj0wz0-pBBt7XkKXihkDCvJVNCEZwragNodVkRI4btZrtcK6IZICQH_oLopmsO7jKuJdncUllxIZAFPVH71fuI8Be62rZSA5r3VLtAUT_jdDvA&sa=X&ved=0ahUKEwiV14nVk6vbAhXBRhQKHUPbCakQwBMI1Q8",
                "result_se_check_url": "https://www.google.co.uk/search?q=shoes&num=100&tbm=shop&&tbs=vw:l&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            },
            {
                "task_id": 676669794,
                "post_id": "949845416541",
                "se_id": 2933,
                "loc_id": 1006886,
                "key_id": 68415,
                "post_key": "shoes",
                "result_position": 100,
                "result_datetime": "2018-05-29 14:41:29 +00:00",
                "result_title": "New Balance 247 Classic - Red/White (Size EU 42 / UK 8)",
                "result_description": "The 247 sneaker is designed to keep up with your demanding life on the move. Sneaker is lightweight and flexible with a ...",
                "result_product_id": null,
                "result_price": 45,
                "result_currency": "GBP",
                "result_stars": 4.18,
                "result_reviews_count": 11,
                "result_shop_stat": null,
                "result_shop_stat_type": null,
                "result_shop_stat_count": null,
                "result_tags": [],
                "result_spell": null,
                "result_best_match": false,
                "result_url": "http://www.newbalance.co.uk/pd/247-Classic/190737388547.html?Ecid=ps_MRL247RW_Google_PLA&ncr=true&&CAWELAID=172000720000053417",
                "result_shopping_url": null,
                "result_se_check_url": "https://www.google.co.uk/search?q=shoes&num=100&tbm=shop&&tbs=vw:l&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            }
        ],
        "paid": [
            {
                "task_id": 676669794,
                "post_id": "949845416541",
                "se_id": 2933,
                "loc_id": 1006886,
                "key_id": 68415,
                "post_key": "shoes",
                "result_position": 1,
                "result_datetime": "2018-05-29 14:41:29 +00:00",
                "result_title": "Shoes from JustFab® | Your First Style from £9\u200e",
                "result_snippet": "New VIPs Get Their First Exclusive Shoes from Just £9 Today!",
                "result_location": "bottom",
                "result_spell": null,
                "result_url": "https://style.justfab.co.uk/",
                "result_se_check_url": "https://www.google.co.uk/search?q=shoes&num=100&tbm=shop&&tbs=vw:l&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            }
        ],
        "extra": {
            "related": [
                [
                    "nike shoes",
                    "adidas shoes",
                    "jordan shoes",
                    "basketball shoes",
                    "light up shoes",
                    "gucci shoes",
                    "puma shoes"                
                ]
            ]
        }
    }
}

Description of the fields for requesting the results:

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


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:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count integer the number of elements in the results array
results array results array of tasks setting
      organic array results array of organic Google Shopping SERP
            task_id integer the unique task identifier in our system(UInt64)
you can use task_id to request task results any time within the next 30 days. You are charged for each GET request for receiving results.
            post_id string the index of the array received in the POST array
            se_id integer search engine id
            loc_id integer search engine location id
You can use it for matching your search engines with the DataForSEO List of Search Engines.
            key_id integer unique keyword identifier in our system
f you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
            post_key string key received in a POST array
the keyword 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 the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified 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 ID
the unique identifier of a product in Google Shopping
if there are no values, you will get null
            result_price float product price
            result_currency string currency type
in the ISO format
            result_stars float product rating
(represented in star symbols) from 0 to 5
if there are no values, you will get null
            result_reviews_count integer amount of feedback
left by users for a certain product
if there are no values, you will get null
            result_shop_stat float/integer shop rating
based on the data collected by Google and/or its partners
in the event that the measurement unit in the result_shop_stat_type is equal to stars, the value can be in the 0 to 5 range
if the measurement unit is equal to percents, the value can be in the range from 0 to 100
if there are no values, you will get null
            result_shop_stat_type string measurement units
shows which measurement units are used in the result_shop_stat field
there are two possible options: starspercents
if there are no values, you will get null
            result_shop_stat_count integer amount of shop feedback
left by users collected by Google and/or its partners
if there are no values, you will get null
            result_tags array tags specified within ads
if there is no data, the array will be empty
            result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
if there are no values, you will get null
            result_best_match boolean is true if the product is marked with “Best match” label
            result_url string the URL of the shop where the specified product is being sold
            result_shopping_url string the URL of the product in the Google Shopping platform
if 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 of paid Google Shopping SERP
            task_id integer unique task identifier in our system(UInt64)
youwill be able to use it within 30 days to request the results of the task at any time
            post_id string index of the array received in the POST array
            se_id integer search engine id
            loc_id integer search engine location id
Location identifier that helps to find the needed location in our system.
            key_id integer keyword id in our system
if you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id
            post_key string key received in a POST array
keyword 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 received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified 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 position
can have the following values: topbottom
            result_spell string auto correction of a search engine
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engine
if 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 of extra Google Shopping SERP elements
            related array array of ‘related search queries’ strings
this array will be present if the element is found in the Google Shopping SERP


Possible error codes

Error Code Meaning
102 “task in queue” – the task is being enqueued to handling, please, try again later
201 “task handed” – the task has been received and sent to handling, please, try again later
202 “in progress” – the task is in the handling process, please, try again later
404 “search engine did not return results” – 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/#api_dashboard

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

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

$post_array = array();

// 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) > 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;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 3,
    "results": {
        "20469414": {
            "post_id": "19840083",
            "post_key": "shoes",
            "task_id": 681890700,
            "se_id": 2972,
            "loc_id": 2840,
            "key_id": 68415,
            "status": "ok"
        },
        "6273173": {
            "post_id": "19840083",
            "post_key": "shoes",
            "task_id": 681890700,
            "se_id": 2972,
            "loc_id": 2840,
            "key_id": 68415,
            "status": "ok"
        },
        "19840083": {
            "post_id": "19840083",
            "post_key": "shoes",
            "task_id": 681890700,
            "se_id": 2972,
            "loc_id": 2840,
            "key_id": 68415,
            "status": "ok"
        }
    }
}

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, sending the array of tasks 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 processing of the task. On the contrary, using our system identifiers (se_id, loc_id, key_id), you can accelerate the task’s processing and set more than 100 tasks at a time.

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 sent to a specific URL. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

Description of the fields for a task setting:

The data that is sent to you will be in a ZIP archive and you will need to decode it

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

url string direct URL of a search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=shoes&tbm=shop&tbs=vw:l&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
se_id integer search engine id
optional field, if you specify se_name
you must choose one of the fields se_id or se_name
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
you must choose a search engine with the word “shopping” included in the se_id field to get se_id for Google Shopping
also, when the information about the set task is returned, you will get se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields se_id or se_name
you can get the list of available search engines with se_id by making a separate request to the List of Search Engines
you must specify a search engine where field “se_name” contains the word “shopping”
example: “google.co.uk shopping”
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with their se_languages by making a separate request to the List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you must choose one of the fields loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_idby making a separate request to the List of Locations
when the information about the set task is returned you will get loc_id
please note that we use Google Geographical Targeting  including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonicalby making a separate request to the List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
key_id integer keyword id
optional field if you specify key
when you set a task for the first time you won’t be able to know this field. But if you plan to collect rankings for this keyword we recommend saving the key_id returned after the task was set and use this field to get results later on.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”
price_min integer the minimum search results price filter
optional field
the minimum value: 0
price_max integer the maximum search results price filter
optional field
price_orderby string sorting by prices
optional field
search results filter type can have two possible values:
asc – in ascending order
desc – in descending order
se_param_add string additional parameters of search query
optional field
for example, if you want to disable auto-correction the search query misspelling for google, you should use the “&nfpr=1” parameter
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify the postback URL there will be no need to use Get Google Shopping Tasks Results for obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$task_id’ string as a $task_id variable and ‘$post_id’ as $post_id variable. We will set the necessary values before sending the request. For example:
http://your-server.com/pingscript?taskId=$task_id
http://your-server.com/pingscript?taskId=$task_id&postId=$post_id


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

Here are some examples:

  1. There is an identifier in your system that corresponds to a task that you set to collect data, for example, 100500. When you set the task you send it in the data array with the 100500 index, e.g.: "{"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 in your system.
  2. You may also want to associate other kinds of data in your system. For instance:
    • a keyword has id=1238 in 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 the API server, you will receive a JSON array in the results field of which there will be information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array informational array of error
only 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 results results
results array results array of tasks setting
            task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results any time within the next 7 days
            status string results of this task setting
“ok” – success
“error” – error
if 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 error
only 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 request
keyword is returned with the decoded %## (plus symbol ‘+’ will be decoded to a space character)
            se_id integer search engine id
if status=“ok”, this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines.
            loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines.
            key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when when setting a task


Possible error codes

Error Code Meaning
404 “not found or not enough data: search engine” – you’ve specified nonexistent se_id or a search engine according to the specified se_name wasn’t found.
404 “not found or not enough data: location” – you’ve specified nonexistent loc_id or a location of a search engine according to the specified loc_name_canonical wasn’t found
404 “not enough data: keyword” – you didn’t specify a keyword in the task
501 “invalid ‘data’ field” – probably you haven’t passed data for the tasks in the 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 HTML Completed Tasks

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

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

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

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

    //get tasks one by one

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1104 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "2365896",
            "task_id": 681890700,
            "post_key": "shoes",
            "key_id": 68415,
            "se_domain": "google.com shopping",
            "se_id": 2972,
            "loc_id": 2840
        }
    ]
}

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

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. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

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

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:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if 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 error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count integer number of elements in the results array
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 system(UInt64)
you can use task_id to request task results any time within the next 7 days
      post_key string key received in a POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      key_id integer keyword id in our system
if you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id
      se_domain string search engine domain
      se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines.
      loc_id integer search engine location id
You can use it for matching your search engines with the DataForSEO List of Search Engines.

Get Google Shopping HTML Results by task_id

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

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

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

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

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1766 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "post ID 1",
            "task_id": 681890700,
            "keyword": "shoes",
            "se_domain": "google.com shopping",
            "country": "US",
            "device": "shopping",            
            "html": [
                [
                    "<!doctype html> ... "
                ]
            ]
        }
    ]
}

Description of the fields for a request setting:

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


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:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if 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 error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count integer number of elements in the array of results results
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 system(UInt64)
you can use task_id to request task results any time within the next 7 days. You are charged for each GET request for results receiving.
      keyword string keyreceived in a POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      se_domain string search engine domain
      country string ISO country code
      device string device
      html array results array
result array with the html page


Possible error codes

Error Code Meaning
102 “task in queue” – the task is being enqueued for 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 the key correctly
404 “top results not found” – there is no SERP with the specified parameters

Setting Google Shopping Sellers Tasks


Using this API you can get a list of shops by specifying the product ID (the unique identifier of a product in Google Shopping).

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

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

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

try {
    // POST /v2/merchant_google_shopping_shops_tasks_post/$data
    $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 = array();
    $post_array[$my_unq_id] = array(
    "priority" => 1,
    "se_id" => 2933,
    "loc_name_canonical" => "London,England,United Kingdom",
    "product_id" => "1924701347928518037"
    );
    $task_post_result = $client->post('v2/merchant_google_shopping_shops_tasks_post', array('data' => $post_array));
    print_r($task_post_result);

    //do something with post results

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 1,
    "results": {
        "11913049": {
            "post_id": 11913049,
            "product_id": "1924701347928518037",
            "task_id": 404227822,
            "se_id": 2933,
            "loc_id": 1006886,
            "status": "ok"
        }
    }
}

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, sending the array of tasks into the data field. It is not recommended to set more than 100 tasks at a time due to different task variations you are likely to use. Note that the usage of the url field slows down the processing of the task. On the contrary, using our system identifiers (se_id, loc_id, key_id), you can accelerate the task’s processing and set more than 100 tasks at a time.

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 sent to a specific URL. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

Description of the fields for a task setting:

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

se_id integer search engine id
optional field, if you specify se_name
you must choose one of the fields se_id or se_name
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
to get se_id for Google Shopping you must choose a search engine with the word “shopping” included into the “se_name” field
also, when the information about the set task is returned, you will get se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields se_id or se_name
you can get the list of available search engines with se_id by making a separate request to the List of Search Engines
you must specify a search engine where field “se_name” contains the word “shopping”
example: “google.co.uk shopping”
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with their se_languages by making a separate request to the List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you must choose one of the fields loc_id or loc_name_canonical
the list of avaliabale search engine locations with loc_id can be accessed by sending a separate request to the List of Locations
also, you can find loc_id in the array returned after the task setting is complete
please note that we use Google Geographical Targeting with the foolowing location types: Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields loc_id or loc_name_canonical
the list of availiable search engine locations with loc_name_canonical can be accessed by sending a separate request to the List of Locations
please note that we use Google Geographical Targeting with the foolowing location types: Country State Region Municipality City, that’s why you can specify loc_name_canonical appropriate Canonical Name
example: “London,England,United Kingdom”
product_id string product ID
required field
the unique product identifier in Google Shopping
se_param_add string additional parameters of the search query
optional field
for example, if you want to disable auto-correction the search query misspelling for google, you should use the “&nfpr=1” parameter
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify this URL there will be no need to use Get Google Shopping Tasks Resultsfor obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$task_id’ string as a $task_id variable and ‘$post_id’ as $post_id variable. We will set the necessary values before sending 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 a task, you send its data in the array using data fieldS. The index of the task in this array ($my_unq_id variable in examples) can be used at any time after that, as the post_id field. It will be returned to you with all server responses as well as our unique task_id field. Thanks to this feature, you can use this field to associate the set tasks with identifiers in your system.

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count integer number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system(UInt64)
you will be able to use it within 30 days to request the results of the task at any time.
            status string results of this task setting
“ok” – success
“error” – error
if status=“error”, check the error array for more details
            error array the informational array of the error
only if status=“error”
the list of possible errors can be found below.
                  code integer error code
                  message string text description of the error
            post_id string index in the array received in the POST request
            product_id string product ID
the unique identifier of a product in Google Shopping
            se_id integer search engine id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines.
            loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines.


Possible error codes

Error Code Meaning
404 “not found or not enough data: search engine” – you’ve specified nonexistent se_id or a search engine according to the specified se_name wasn’t found
404 “not found or not enough data: location” – you’ve specified nonexistent loc_id or a location of a search engine according to the specified loc_name_canonical wasn’t found
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 data field: 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 Sellers Completed Tasks

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

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

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

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

    //get tasks one by one

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0120 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "874654654",
            "product_id": "1924701347928518037",
            "task_id": 812007503,
            "se_id": 2933,
            "loc_id": 1006886,
            "result_se_check_url": "https://www.google.co.uk/shopping/product/1924701347928518037/online?&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
        }
    ]
}

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

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_shops_tasks_get command. GET requests will be sent to the pingback_url, POST requests will be sent to the postback_url. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

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

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:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if 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 the error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count integer number of elements in the results array
results array results array of tasks
            post_id string index in the array received in a POST request
            task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results any time within the next 30 days
            product_id string product ID
the unique identifier of a product in Google Shopping
            se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines.
            loc_id integer search engine location id
You can use it for matching your search engines with the DataForSEO List of Search Engines.
            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 Shopping Sellers Results by task_id

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

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

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

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

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1103 sec.",
    "results_count": 30,
    "results": {
        "organic": [
            {
                "task_id": 814590947,
                "post_id": "874654654",
                "se_id": 2933,
                "loc_id": 1006886,
                "product_id": "1924701347928518037",
                "result_position": 1,
                "result_datetime": "2018-06-21 07:57:08 +00:00",
                "result_title": "Converse Chuck Taylor All Stars Hi Leather Shoe - White",
                "result_seller_name": "Runcolors",
                "result_base_price": 48.34,
                "result_delivery_price": "Free delivery",
                "result_total_price": 49.88,
                "result_currency": "GBP",
                "result_shop_stat": null,
                "result_shop_stat_type": null,
                "result_shop_stat_count": null,
                "result_details": null,
                "result_shop_ad_url": "https://www.google.co.uk/aclk?sa=l&ai=DChcSEwjB1vfxo-TbAhUFJoYKHeOaDYQYABABGgJ2dQ&sig=AOD64_0WrUcADNZ-IxbrzAErlUAXk9fp-w&ctype=5&q=&ved=0ahUKEwjiyvbxo-TbAhUJvlkKHZWbDB4Q2ikIKQ&adurl=",
                "result_se_check_url": "https://www.google.co.uk/shopping/product/1924701347928518037/online?&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
                "result_shop_ad_aclk": "DChcSEwjB1vfxo-TbAhUFJoYKHeOaDYQYABABGgJ2dQ"
            },
            {
                "task_id": 814590947,
                "post_id": "874654654",
                "se_id": 2933,
                "loc_id": 1006886,
                "product_id": "1924701347928518037",
                "result_position": 2,
                "result_datetime": "2018-06-21 07:57:08 +00:00",
                "result_title": "Converse Chuck Taylor All Stars Hi Leather Shoe - White",
                "result_seller_name": "extremepie",
                "result_base_price": 47.95,
                "result_delivery_price": "+£39.00 delivery",
                "result_total_price": 50.9,
                "result_currency": "GBP",
                "result_shop_stat": 4.7,
                "result_shop_stat_type": "stars",
                "result_shop_stat_count": 937,
                "result_details": null,
                "result_shop_ad_url": "https://www.google.co.uk/aclk?sa=l&ai=DChcSEwjB1vfxo-TbAhUFJoYKHeOaDYQYABADGgJ2dQ&sig=AOD64_227egzovOaw8lQeROo2AsWKE0jVQ&ctype=5&q=&ved=0ahUKEwjiyvbxo-TbAhUJvlkKHZWbDB4Q2ikILw&adurl=",
                "result_se_check_url": "https://www.google.co.uk/shopping/product/1924701347928518037/online?&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
                "result_shop_ad_aclk": "DChcSEwjB1vfxo-TbAhUFJoYKHeOaDYQYABADGgJ2dQ"
            },
            {
                "task_id": 814590947,
                "post_id": "874654654",
                "se_id": 2933,
                "loc_id": 1006886,
                "product_id": "1924701347928518037",
                "result_position": 3,
                "result_datetime": "2018-06-21 07:57:08 +00:00",
                "result_title": "Converse Chuck Taylor All Stars Hi Leather Shoe - White",
                "result_seller_name": "Converse UK",
                "result_base_price": 65,
                "result_delivery_price": null,
                "result_total_price": 65,
                "result_currency": "GBP",
                "result_shop_stat": null,
                "result_shop_stat_type": null,
                "result_shop_stat_count": null,
                "result_details": null,
                "result_shop_ad_url": "https://www.google.co.uk/aclk?sa=l&ai=DChcSEwjB1vfxo-TbAhUFJoYKHeOaDYQYABAFGgJ2dQ&sig=AOD64_2Ox-sQsCNugyPt7729rfVHgdLGQg&ctype=5&q=&ved=0ahUKEwjiyvbxo-TbAhUJvlkKHZWbDB4Q2ikIMw&adurl=",
                "result_se_check_url": "https://www.google.co.uk/shopping/product/1924701347928518037/online?&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
                "result_shop_ad_aclk": "DChcSEwjB1vfxo-TbAhUFJoYKHeOaDYQYABAFGgJ2dQ"
            },

            {
                "task_id": 814590947,
                "post_id": "874654654",
                "se_id": 2933,
                "loc_id": 1006886,
                "product_id": "1924701347928518037",
                "result_position": 30,
                "result_datetime": "2018-06-21 07:57:08 +00:00",
                "result_title": "Converse Chuck Taylor All Stars Hi Leather Shoe - White",
                "result_seller_name": "eBay - takemore_net",
                "result_base_price": 101,
                "result_delivery_price": "Free delivery",
                "result_total_price": 101,
                "result_currency": "GBP",
                "result_shop_stat": null,
                "result_shop_stat_type": null,
                "result_shop_stat_count": null,
                "result_details": null,
                "result_shop_ad_url": "https://www.google.co.uk/aclk?sa=l&ai=DChcSEwjzlcj-o-TbAhUSVdMKHTHhBDMYABAJGgJ3Yg&sig=AOD64_1oyNnqKMBiGwLHB43uKQosqdeQuA&ctype=5&q=&ved=0ahUKEwiv7sb-o-TbAhXLbxQKHYIsCjwQ2ikIOA&adurl=",
                "result_se_check_url": "https://www.google.co.uk/shopping/product/1924701347928518037/online?&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
                "result_shop_ad_aclk": "DChcSEwjzlcj-o-TbAhUSVdMKHTHhBDMYABAJGgJ3Yg"
            }
        ]
    }
}

Description of the fields for a setting a request:

Field name Type Description
task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results any time within the next 30 days


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count integer the number of elements in the results array
results array results array of tasks setting
      organic array results array of organic Google Shopping Sellers SERP
            task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results any time within the next 30 days. You are charged for each GET request for receiving results.
            post_id string index in the array received in the POST array
            se_id integer search engine id
            loc_id integer search engine location id
Location identifier that helps to find the needed location in our system.
            product_id string product ID
the unique identifier of a product in Google Shopping
            result_position integer position in the Google Shopping SERP
            result_datetime string date and time when a result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified at your profile settings is used
            result_title string product title
            result_seller_name string seller’s name
            result_base_price float base price
            result_delivery_price string price of product delivery
            result_total_price float total price
            result_currency string currency type
in the ISO format
            result_shop_stat float/integer shop rating
based on the data collected by Google and/or its partners
in the event that the measurement unit in the result_shop_stat_type is equal to stars, the value can be in the 0 to 5 range
if the measurement unit is equal to percents, the value can be in the range 0 to 100
if there are no values, you will get null
            result_shop_stat_type string measurement units
shows which measurement units are used in the result_shop_stat field
there are two possible options: starspercents
if there are no values, you will get null
            result_shop_stat_count integer amount of shop feedback
left by users for a certain period
collected by Google and/or its partners
if there are no values, you will get null
            result_details string details
if there are no values, you will get null
            result_shop_ad_url string Google Ad service URL
            result_se_check_url string direct URL to search engine results
you can use it to make sure that we provided exact results
            result_shop_ad_aclk string the ad’s unique click referral parameter
you can get the full URL of the product in Google Shopping Sellers Ad Url


Possible error codes

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

Setting Google Shopping Product Specification Tasks

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

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

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

try {
    // POST /v2/merchant_google_shopping_product_spec_tasks_post/$data
    $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 = array();
    $post_array[$my_unq_id] = array(
    "se_id" => 2933,
    "loc_name_canonical" => "London,England,United Kingdom",
    "product_id" => "1583419775492369734"
    );
    $task_post_result = $client->post('v2/merchant_google_shopping_product_spec_tasks_post', array('data' => $post_array));
    print_r($task_post_result);

    //do something with post results

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 1,
    "results": {
        "11913049": {
            "post_id": 11913049,
            "product_id": "1583419775492369734",
            "task_id": 404227822,
            "se_id": 2933,
            "loc_id": 1006886,
            "status": "ok"
        }
    }
}

You should specify the product ID (the unique product identifier in Google Shopping) to get a list of shops with this 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, sending the array of tasks 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.

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 sent to a specific URL. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

Description of the fields for a task setting:

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

se_id integer search engine id
optional field, if you specify se_name
you must choose one of the fields se_id or se_name
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
you must choose a search engine with the word “shopping” included in the se_id field to get se_id for Google Shopping
also, when the information about the set task is returned, you will get the se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields se_id or se_name
you can get the list of available search engines with se_id by making a separate request to the List of Search Engines
you must specify a search engine where the field se_name contains the word “shopping”
example: “google.co.uk shopping”
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with their se_languages by making a separate request to the List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you can receive the list of available locations of search engines with their loc_idby making a separate request to the List of Locations
when the information about the set task is returned you will get loc_id
please note that we use Google Geographical Targeting  including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonicalby making a separate request to the List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
product_id string product ID
required field
the unique identifier of a product in Google Shopping
se_param_add string additional parameters of search query
optional field
for example, if you want to disable auto-correction the search query misspelling for google, you should use the “&nfpr=1” parameter
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify the postback URL there will be no need to use Get Google Shopping Tasks Results for obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$task_id’ string as a $task_id variable and ‘$post_id’ as $post_id variable. We will set the necessary values before sending the request. For example:
http://your-server.com/pingscript?taskId=$task_id
http://your-server.com/pingscript?taskId=$task_id&postId=$post_id


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

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count integer the number of elements in the results array
results array results array of tasks setting
            task_id integer the unique task identifier in our system(UInt64)
you will be able to use it within 30 days to request the results of the task at any time.
            status string results of this task setting
“ok” – success
“error” – error
if status=“error”, you can see the more detailed information about the possible cause of an error in the error array
            error array the informational array of error
only if status=“error”
the list of possible errors can be found below.
                  code integer error code
                  message string text description of the error
            post_id string index in the array received in the POST request
            product_id string product ID
the unique identifier of a product in Google Shopping
            se_id integer search engine id
if status=“ok”, then this field will be always filled
Location identifier that helps to find the needed location in our system.
            loc_id integer search engine location id
if status=“ok”, then this field will be always filled
Location identifier that helps to find the needed location in our system.


Possible error codes

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

Get Google Shopping Product Specification Completed Tasks

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

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

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

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

    //get tasks one by one

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0120 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "798446411578",
            "product_id": "1583419775492369734",
            "task_id": 4612100998,
            "se_id": 2933,
            "loc_id": 2826,
            "result_se_check_url": "https://www.google.co.uk/shopping/product/1583419775492369734/specs?&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCamRx0IRO1oCEXoliDJDoPjE"
        }
    ]
}

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

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. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

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

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:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if 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 the error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count integer number of elements in the results array
results array results array of tasks
            post_id string index in the array received in a POST request
            task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results any time within the next 30 days
            product_id string product ID
the unique identifier of a product in Google Shopping
            se_id integer search engine id
You can use it for finding relations between your and our search engines
            loc_id integer search engine location id
Location identifier that helps to find the needed location in our system.
            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 Shopping Product Specification Results by task_id

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

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

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

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

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.9173 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 4610074012,
            "post_id": "874654654",
            "se_id": 2933,
            "loc_id": 2826,
            "product_id": "11118922411284361046",
            "result_datetime": "2019-07-29 13:53:11 +00:00",
            "result_title": "HP Stream 11-ah055sa 11.6″ Notebook - Celeron 1.6 GHz - 2 GB RAM - 32 GB SSD - Linear grooves pattern\/Aqua blue",
            "result_se_check_url": "https://www.google.co.uk/shopping/product/11118922411284361046/specs?&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCamRx0IRO1oCEXoliDJDoPjE",
            "result_price": 128,
            "result_price_currency": "£128",
            "result_spec": {
                "General": {
                    "Product Type": "Notebook",
                    "Operating System": "Windows 10 Home 64-bit Edition - English"
                },
                "Processor / Chipset": {
                    "CPU": "Intel Celeron N3060 / 1.6 GHz",
                    "Max Turbo Speed": "2.48 GHz",
                    "Number of Cores": "Dual-Core",
                    "Cache": "2 MB",
                    "64-bit Computing": "Yes",
                    "Features": "Intel Burst Technology"
                },
                "Memory": {
                    "RAM": "2 GB (provided memory is soldered)",
                    "Technology": "DDR3L SDRAM",
                    "Speed": "1600 MHz - 1600 MHz",
                    "Rated Speed": "1600 MHz"
                },
                "Storage": {
                    "Main Storage": "32 GB SSD - (eMMC)"
                },
                "Display": {
                    "Type": "11.6",
                    "LCD Backlight Technology": "WLED backlight",
                    "Resolution": "1366 x 768 (HD)",
                    "Widescreen": "Yes",
                    "Features": "HD standard-viewing angle (SVA) anti-glare"
                },
                "Manufacturer Warranty": {
                    "Service & Support": "Limited warranty - parts and labour - 1 year - pick-up and return"
                },
                "Universal Product Identifiers": {
                    "Brand": "HP",
                    "Part Numbers": "10181372, 11-AH055SA, 3RN45EA#ABU",
                    "GTIN": "00193015022294"
                }
            }
        }
    ]
}

Description of the fields for a request setting:

Field name Type Description
task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results any time within the next 30 days


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:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if 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 error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count integer number of elements in the array of results results
results array results array of tasks setting
      task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results any time within the next 30 days. 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 id
Location identifier that helps to find the needed location in our system.
      product_id string product ID
the unique identifier of a product in Google Shopping
      result_datetime string date and time when a result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified at your profile settings is used
      result_title string product title
      result_se_check_url string direct URL to search engine results
you can use it to make sure that we provided exact results
      result_price float/integer product price on the specification page
      result_price_currency string product price on the specification page with the currency sign
      result_spec array array of product specification
depending on the product, the quantity and the name of items will be different.
            $block_name array array of the specification elements that are grouped in the $block_name block
                  $spec_item string value of $spec_item item


Possible error codes

Error Code Meaning
102 “task in queue” – the task is being enqueued to handling, please, try again later
201 “task handed” – the task has been received and sent to handling, please, try again later
202 “in progress” – the task is in the handling process, please, try again later
404 “search engine did not return results” – 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

Get Google Shopping Sellers Ad URL

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

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

try {

    //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/#api_dashboard
    $client = new RestClient('https://api.dataforseo.com/', null, 'login', 'password');
    $ad_aclk = "DChcSEwjRxPWhsLnjAhUVHisKHc4YABABGgJzZg";
    $ad_url = $client->get('v2/merchant_google_shopping_shops_ad_url/' . $ad_aclk);
    print_r($ad_url);

    //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";
    exit();
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1644 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 4573535324617,
            "ai_url": "https:\/\/www.quickmobilefix.com\/products\/apple-iphone-6-64gb-white-silver-unlocked-grade-a-full-bundle?variant=14655505286&currency=GBP"
        }
    ]
}


This endpoint will provide you with a URL of the advertised product through the Google Ad Services pagead aclk.

Description of the fields for setting a request:

Field name Type Description
ad_aclk string the ad’s unique click referral parameter
you can get it from Google Shopping Sellers Results


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:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count integer the number of elements in the results array
results array results array of tasks setting
      task_id integer unique task identifier in our system(UInt64)
      ai_url string product url


Possible error codes

Error Code Meaning
404 “ai_url not found” – check if the “ai_url” is correct

Amazon

Amazon API provides TOP 100 results from Amazon results pages based on a keyword (product). Moreover, you can get the HTML of results pages by using Amazon HTML API. Using the Amazon ASIN for a particular product you can get a full list of ASINs assigned to different modifications of this product (ASIN is the unique identifier of a product assigned by Amazon).

The operating principle of Amazon API is similar to that of Rank Tracker API. The main difference is that with Amazon API, you don’t receive all completed results at once. Instead, you will receive a list of task identifiers (task_id) that are unique and assigned to each separate task. You can then use the task’s task_id to return its results. This is due to the vast amounts of data included in each Amazon API task.

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

Setting Amazon Tasks

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

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

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

$post_array = array();

// 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", "key_id" ( actual and fresh list can be found here: "se_id":
// https://api.dataforseo.com/v2/cmn_se) (see example #3 for details)
// If a task was set successfully, this *_id will be returned in results: 'v2/merchant_amazon_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.amazon.com/s/?field-keywords=shoes&language=en_US"
);

// 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", "key_id" ( actual and
// fresh list can be found here: "se_id": https://api.dataforseo.com/v2/cmn_se
// You must choose a search engine with the word "amazon" included into the "se_name" field
// If a task was set successfully, this *_id will be returned in results: 'v2/merchant_amazon_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" => "amazon.com",
"se_language" => "English",
"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 ,
// You must choose a search engine with the word "amazon" 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" => 2897,
"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) > 0) {
    try {
        // POST /v2/merchant_amazon_tasks_post/$data
        // $tasks_data must by array with key 'data'
        $task_post_result = $client->post('v2/merchant_amazon_tasks_post', array('data' => $post_array));
        print_r($task_post_result);

        //do something with post results

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 3,
    "results": {
        "11913049": {
            "post_id": 11913049,
            "post_key": "shoes",
            "task_id": 864328311,
            "se_id": 2897,
            "key_id": 68415,
            "status": "ok"
        },
        "20469414": {
            "post_id": 20469414,
            "post_key": "shoes",
            "task_id": 864458311,
            "se_id": 2897,
            "key_id": 68415,
            "status": "ok"
        },
        "6273173": {
            "post_id": 6273173,
            "post_key": "shoes",
            "task_id": 864458311,
            "se_id": 2897,
            "key_id": 68415,
            "status": "ok"
        }
    }
}

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, sending the array if tasks into the data field. It is not recommended to set more than 100 tasks at once due to different task variations you are likely to use. Note that the usage of the url field slows down the processing of the task. On the contrary, using system identifiers (se_idkey_id), you can accelerate the task’s 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 sent to a specific URL. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

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

Description of the fields for setting a task:

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

url string direct URL of a search query
optional field
you can specify a direct URL, and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.amazon.com/s/?field-keywords=shoes&language=en_US
se_id integer search engine id
optional field, if you specify se_name
you must choose one of the fields se_id or se_name
you can get the list of available search engines with their se_idby making a separate request to the List of Search Engines
you must choose a search engine with the word “amazon” included in the “se_name” field to get se_id for Amazon
also, when the information about the set task is returned, you will get se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields se_id or se_name
you can get the list of available search engines with se_name by making a separate request to the List of Search Engines
you must specify a search engine where the field “se_name” contains the word “amazon”
example: “amazon.com”
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with their se_language by making a separate request to the List of Search Engines
example: “English”
key_id integer keyword id
optional field if you specify key
when you set a task for the first time you won’t be able to know this field. But if you plan to collect rankings for this keyword we recommend saving the key_id returned after the task was set and use this field to get results later on.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”
price_min integer the minimum search results price filter
optional field
minimum value: 0
price_max integer the maximum search results price filter
optional field
sortby string type of sorting
optional field
search results filter type, you can specify:
relevance – sort by Relevance
featured – sort by Featured Rank
price_low_to_high – sort by Price: Low to High
price_high_to_low – sort by Price: High to Low
avg_customer_review – sort by Avgerage Customer Review
newest_arrival – sort by Newest Arrival
se_param_add string additional parameters of search query
optional field
for example, if you want to disable auto correction of misspelling in the search query, you should specify “&nfpr=1”
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify the postback URL there will be no need to use Get Amazon Tasks Results for obtaining results. We will send a result of a completed task by a POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use string ‘$task_id’ as $task_id variable and ‘$post_id’ as $post_id variable. We will set the necessary values before sending the request. For example
http://your-server.com/pingscript?taskId=$task_id
http://your-server.com/pingscript?taskId=$task_id&postId=$post_id


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

Here are some examples:

  1. There is an identifier in your system that corresponds to a task that you set to collect data, for example, 100500. When you set the task you send it in the data array with the 100500 index, e.g.: "{"data":{"100500":{"priority":1,"se_name":"amazon.com","se_language":"English","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 in your system.
  2. You may also want to associate other kinds of data in your system. For instance:
    • a keyword has id=68415 in your system,
    • a search engine id=2897,
    • 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 the necessary data will have the following value: 1238#43289#97435#2#9999. As a result, the request for setting of a task will look like this: "{"data":{"68415#2897#9999":{"priority":1,"se_name":"amazon.com","se_language":"English","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 the API server you will receive a JSON array in the results field of which there will be information appropriate to the set tasks.

Description of the fields in the results array:

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


Possible error codes

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

Get Amazon Completed Tasks

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

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

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

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

    //get tasks one by one

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0120 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "874654654",
            "post_key": "shoes",
            "task_id": 864528251,
            "se_id": 2897,
            "key_id": 68415,
            "result_se_check_url": "https://www.amazon.com/s/?field-keywords=shoes&language=en_US"
        }
    ]
}

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

By indicating the pingback_url or the postback_url you get the list of completed tasks to a specific url, avoiding the extra merchant_amazon_tasks_get command. GET requests will be sent to the pingback_url, POST requests will be sent to the postback_url.
Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs
Please note, if you specify postback_url or pingback_url field, a task will not be in the list of completed tasks. The task can be found in the list only if your server returned HTTP code response less than 200 or bigger than 300.

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:

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

Get Amazon Results by task_id

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

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

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

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

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0135 sec.",
    "results_count": 108,
    "results": {
        "organic": [
            {
                "task_id": 865269634,
                "post_id": "874654654",
                "se_id": 2897,
                "key_id": 68415,
                "post_key": "shoes",
                "result_position": 1,
                "result_datetime": "2018-07-03 15:55:35 +00:00",
                "result_title": "Men's Running Shoes Fashion Breathable Sneakers Mesh Soft Sole Casual Athletic Lightweight",
                "result_seller_name": "keezmz",
                "result_product_id": "B078FT6JBD",
                "result_price_from": 21.99,
                "result_price_to": null,
                "result_currency": "USD",
                "result_stars": 3.9,
                "result_amazon_choice": true,
                "result_reviews_count": 334,
                "result_count": 70000,
                "result_url": "https://www.amazon.com/keezmz-Breathable-Sneakers-Athletic-Lightweight/dp/B078FT6JBD/ref=sr_1_5/141-6255624-1337112?s=apparel&ie=UTF8&qid=1530633326&sr=1-5&nodeID=7141123011&psd=1&keywords=shoes",
                "result_se_check_url": "https://www.amazon.com/s/?url=search-alias%3Daps&field-keywords=shoes&page=1&language=en_US"
            },
            {
                "task_id": 865269634,
                "post_id": "874654654",
                "se_id": 2897,
                "key_id": 68415,
                "post_key": "shoes",
                "result_position": 2,
                "result_datetime": "2018-07-03 15:55:35 +00:00",
                "result_title": "Mens Running Shoes Casual Walking Sneakers Workout Athletic Shoe for Men",
                "result_seller_name": "Kundork",
                "result_product_id": "B07D5WK8BZ",
                "result_price_from": 5.99,
                "result_price_to": null,
                "result_currency": "USD",
                "result_stars": 4.1,
                "result_amazon_choice": true,
                "result_reviews_count": 41,
                "result_count": 70000,
                "result_url": "https://www.amazon.com/Kundork-Running-Walking-Sneakers-Athletic/dp/B07D5WK8BZ/ref=sr_1_6/141-6255624-1337112?s=apparel&ie=UTF8&qid=1530633326&sr=1-6&nodeID=7141123011&psd=1&keywords=shoes",
                "result_se_check_url": "https://www.amazon.com/s/?url=search-alias%3Daps&field-keywords=shoes&page=1&language=en_US"
            },
            {
                "task_id": 865269634,
                "post_id": "874654654",
                "se_id": 2897,
                "key_id": 68415,
                "post_key": "shoes",
                "result_position": 100,
                "result_datetime": "2018-07-03 15:55:35 +00:00",
                "result_title": "Womens Summer Espadrille Ankle Strap Flat Sandals Peep Toe Flip-Flop Shoes",
                "result_seller_name": "FISACE",
                "result_product_id": "B07DJ2793S",
                "result_price_from": 18.99,
                "result_price_to": null,
                "result_currency": "USD",
                "result_stars": 5,
                "result_amazon_choice": false,
                "result_reviews_count": 1,
                "result_count": 70000,
                "result_url": "https://www.amazon.com/FISACE-Womens-Espadrille-Sandals-Flip-Flop/dp/B07DJ2793S/ref=sr_1_105/141-1227682-4431915?s=apparel&ie=UTF8&qid=1530633335&sr=1-105&nodeID=7141123011&psd=1&keywords=shoes",
                "result_se_check_url": "https://www.amazon.com/s/?url=search-alias%3Daps&field-keywords=shoes&page=1&language=en_US"
            }
        ],
        "paid": [
            {
                "task_id": 865269634,
                "post_id": "874654654",
                "se_id": 2897,
                "key_id": 68415,
                "post_key": "shoes",
                "result_position": 1,
                "result_datetime": "2018-07-03 15:55:35 +00:00",
                "result_title": "Boot and Shoe Cream Polish - Made in the USA",
                "result_seller_name": "OrthoStep",
                "result_product_id": "B074F2NQYY",
                "result_price_from": 6.99,
                "result_price_to": null,
                "result_currency": "USD",
                "result_stars": 5,
                "result_amazon_choice": false,
                "result_reviews_count": 3,
                "result_count": 70000,
                "result_url": "https://www.amazon.com/OrthoStep-Black-Polish-Cream-Leather/dp/B074F2NQYY/ref=sr_1_1_sspa/141-6255624-1337112?s=apparel&ie=UTF8&qid=1530633326&sr=1-1-spons&nodeID=7141123011&psd=1&keywords=shoes&psc=1",
                "result_se_check_url": "https://www.amazon.com/s/?url=search-alias%3Daps&field-keywords=shoes&page=1&language=en_US"
            }
        ],
        "extra": [
            {
                "task_id": 865269634,
                "post_id": "874654654",
                "se_id": 2897,
                "key_id": 68415,
                "post_key": "shoes",
                "result_position": 0,
                "result_datetime": "2018-07-03 15:55:35 +00:00",
                "result_title": "Adidas Men's Forum Lo Refined White/Black Ankle-High Fashion Sneaker - 10M",
                "result_seller_name": "by adidas",
                "result_product_id": "B07BQFYHKG",
                "result_price_from": 95.01,
                "result_price_to": null,
                "result_currency": "USD",
                "result_stars": 4.5,
                "result_reviews_count": 62,
                "result_count": 200000,
                "result_url": "https://www.amazon.com/adidas-Refined-Originals-Cblack-Casual/dp/B0719SP9N9/ref=sr_1_5/ref=sr_1_5_acs_osp_osp7-f0c09514_cov_2?ie=UTF8&qid=1550245342&sr=8-5-acs&keywords=shoes&tag=instyleosp-20&ascsubtag=f0c09514-5438-4ed8-9e12-7ed2627486ba&linkCode=oas&cv_ct_id=amzn1.osp.f0c09514-5438-4ed8-9e12-7ed2627486ba&cv_ct_pg=search&cv_ct_wn=osp-search&pd_rd_w=rP6xe&pf_rd_p=7f6b8bb9-631f-46f6-b8ad-496a9af123d5&pf_rd_r=D3MNHZ2NS8EV294Y3Q0E&pd_rd_r=121b4df3-6994-4115-9cea-e1ce2ae2db2e&pd_rd_wg=nhmsm&creativeASIN=B0719SP9N9&pd_rd_i=B0719SP9N9&pf_rd_r=D3MNHZ2NS8EV294Y3Q0E&pd_rd_w=rP6xe&pd_rd_wg=nhmsm&pf_rd_p=7f6b8bb9-631f-46f6-b8ad-496a9af123d5&pd_rd_r=121b4df3-6994-4115-9cea-e1ce2ae2db2e",
                "result_se_check_url": "https://www.amazon.com/s/?url=search-alias%3Daps&field-keywords=shoes&page=1&language=en_US"
            }
        ]
    }
}

Description of the fields for requesting the results:

Field name Type Description
task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results at any time within the next 30 days


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:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array informational array of the error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count integer number of elements in the results array
results array results array of tasks setting
      organic array results array of organic Amazon SERP
            task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results at any time within the next 30 days. You are charged for each GET request for receiving results.
            post_id string the index of the array received in the POST array
            se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines
            key_id integer keyword id in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
            post_key string key received in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            result_position integer position in the Amazon SERP
            result_datetime string date and time when a result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
            result_title string snippet header in the Amazon SERP
            result_seller_name string seller name
            result_product_id string product ID
the unique product identifier in Amazon
if there are no values, you will get null
            result_price_from float the regular price of a product
if there are no values, you will get null
            result_price_to float the upper limit of the product price range
if there are no values, you will get null
            result_currency string currency type
in the ISO format
if there are no values, you will get null
            result_stars float product rating
represented in star symbols from 0 to 5
if there are no values, you will get null
            result_amazon_choice boolean is true if the product is marked with the “Amazon Choice” label
            result_reviews_count integer the amount of feedback
left by users for a certain product
if there are no values, you will get null
            results_count integer total number of results in the SERP
            result_url string the URL of the shop where a specified product is being sold
            result_se_check_url string direct URL to SERP
you can use it to make sure that we provided exact results
      paid array results array of paid Amazon SERP
            task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results at any time within the next 30 days. You are charged for each GET request for receiving results.
            post_id string the index of the array received in a POST array
            se_id integer search engine id
            key_id integer keyword id in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
            post_key string key received in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            result_position integer position in the Amazon SERP
            result_datetime string date and time when the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
            result_title string snippet header in the Amazon SERP
            result_seller_name string seller name
            result_product_id string product ID
the unique product identifier in Amazon
if there are no values, you will get null
            result_price_from float the regular price of a product
if there are no values, you will get null
            result_price_to float the upper limit of the product price range
if there are no values, you will get null
            result_currency string currency type
in the ISO format
if there are no values, you will get null
            result_stars float product rating
represented in star symbols from 0 to 5
if there are no values, you will get null
            result_amazon_choice boolean is true if the product marked with “Amazon Choice” label
            result_reviews_count integer the amount of feedback
left by users for a certain product
if there are no values, you will get null
            results_count integer the total number of results in the SERP
            result_url string the URL of the shop where a specified product is being sold
            result_se_check_url string direct URL to SERP
you can use it to make sure that we provided exact results
      extra array results array of extra Amazon SERP
            task_id integer the unique task identifier in our system(UInt64)
you can use task_id to request task results at any time within the next 30 days. You are charged for each GET request for receiving results.
            post_id string the index of the array received in the POST array
            se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines.
            key_id integer the unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
            post_key string key received in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            result_position integer position in the Amazon SERP
            result_datetime string date and time when the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
            result_title string snippet header in the Amazon SERP
            result_seller_name string seller name
            result_product_id string product ID
the unique product identifier in Amazon
if there are no values, you will get null
            result_price_from float the regular price of the product
if there are no values, you will get null
            result_price_to float the upper limit of the product price range
if there are no values, you will get null
            result_currency string currency type
in the ISO format
if there are no values, you will get null
            result_stars float product rating
epresented by star symbols from 0 to 5
if there are no values, you will get null
            result_reviews_count integer amount of feedback
left by users for a certain product
if there are no values, you will get null
            results_count integer the total number of results in the SERP
            result_url string the URL of the shop where a specified product is being sold
            result_se_check_url string direct URL to search engine results
you can use it to make sure that we provided exact results


Possible error codes

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

Setting Amazon HTML Tasks

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

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

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

$post_array = array();

// 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", "key_id" ( actual and fresh list can be found here: "se_id":
// https://api.dataforseo.com/v2/cmn_se) (see example #3 for details)
// If a task was set successfully, this *_id will be returned in results: 'v2/merchant_amazon_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.amazon.com/s/?field-keywords=shoes&language=en_US"
);

// 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", "key_id" ( actual and
// fresh list can be found here: "se_id": https://api.dataforseo.com/v2/cmn_se 
// You must choose a search engine with the word "amazon" included into the "se_name" field
// If a task was set successfully, this *_id will be returned in results: 'v2/merchant_amazon_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" => "amazon.com",
"se_language" => "English",
"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 ,
// You must choose a search engine with the word "amazon" 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" => 2897,
"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) > 0) {
    try {
        // POST /v2/merchant_amazon_html_tasks_post/$data
        // $tasks_data must by array with key 'data'
        $task_post_result = $client->post('v2/merchant_amazon_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;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 3,
    "results": {
        "20469414": {
            "post_id": 20469414,
            "post_key": "shoes",
            "task_id": 357758709,
            "se_id": 2897,
            "key_id": 68415,
            "status": "ok"
        },
        "6273173": {
            "post_id": 6273173,
            "post_key": "shoes",
            "task_id": 236858709,
            "se_id": 2897,
            "key_id": 68415,
            "status": "ok"
        },
        "19840083": {
            "post_id": 19840083,
            "post_key": "shoes",
            "task_id": 589058709,
            "se_id": 2897,
            "key_id": 68415,
            "status": "ok"
        }
    }
}

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 different task variations you are likely to use. Note that the usage of the url field slows down the processing of the task. On the contrary, using system identifiers (se_id, key_id), you can accelerate the task’s processing and set more than 100 tasks at a time.

You can get the completed task results via the unique task_id. Alternatively, you may indicate the pingback_url or postback_url to get the task results sent to a specific URL. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

Description of the fields for setting a task:

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

url string direct URL of a search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.amazon.com/s/?field-keywords=shoes&language=en_US
se_id integer search engine id
optional field, if you specify se_name
you must choose one of the fields se_id or se_name
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
you must choose a search engine with the word “amazon” included in the “se_name” field to get se_id for Amazon
also, you can find se_id in the array returned after the task setting is complete
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields se_id or se_name
you can get the list of available search engines with their se_name by making a separate request to the List of Search Engines
you must choose a search engine with the word “amazon” included in the “se_name” field to get se_name for Amazonexample: “amazon.com”
se_language string search engine language
required field if se_id is not specified
the list of available search engines with se_languages can be accessed by sending a separate request to the List of Search Engines
example: “English”
key_id integer keyword id
optional field if you specify key
when you set a task for the first time you won’t be able to know this field. But if you plan to collect rankings for this keyword we recommend you to save key_id returned after the task was set and use this field in the future.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”
price_min integer minimum search results price filter
optional field
minimum value: 0
price_max integer maximum search results price filter
optional field
sortby string type of sorting
optional field
search results filter type, you can specify:
relevance – sort by Relevance
featured – sort by Featured Rank
price_low_to_high – sort by Price: Low to High
price_high_to_low – sort by Price: High to Low
avg_customer_review – sort by Avg. Customer Review
newest_arrival – sort by Newest Arrival
se_param_add string additional parameters of search query
optional field
for instance, if you want to disable auto correction of misspelling in the search query, you can specify “&nfpr=1”
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify this URL there will be no need to pick up tasks using Get Amazon 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 task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use 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:

  1. 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":"amazon.com","se_language":"English","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.
  2. You want to associate other kinds of data at your system. For instance:
    • a keyword has id=68415 at your system,
    • a search engine id=2897,
    • 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":"amazon.com","se_language":"English","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 JSON array in the field results of which there will be information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=”error”, you can see the more detailed information about the possible cause of an error in the error array
error array informational array of error
only 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 results results
results array results array of tasks setting
            task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results any time within the next 7 days.
            status string results of this task setting
“ok” – success
“error” – error
if 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 error
only 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 request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            se_id integer search engine id
if status=”ok”, then this field will be always filled
Location identifier that helps to find the needed location in our system.
            key_id integer keyword id in our system
if you plan to use this keyword in the future we recommend you to save this id and use it when you set a task as key_id


Possible error 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 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 Amazon HTML Completed Tasks

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

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

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

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

    //get tasks one by one

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1104 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "874654654",
            "task_id": 835058177,
            "post_key": "shoes",
            "key_id": 68415,
            "se_domain": "amazon.com",
            "se_id": 2897
        }
    ]
}

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

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

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

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:

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

Get Amazon HTML Results by task_id

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

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

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

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

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1766 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "874654654",
            "task_id": 836648828,
            "keyword": "shoes",
            "se_domain": "amazon.com",
            "device": "desktop",           
            "html": [
                [
                    "<!doctype html> ... "
                ]
            ]
        }
    ]
}

Description of the fields for setting a request:

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


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:

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


Possible error codes

Error Code Meaning
102 “task in queue” – the task is being enqueued for 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” – Amazon SERP is empty. Check if you have added the key correctly
404 “top results not found” – there is no SERP with the specified parameters

Setting Amazon ASIN Tasks

Using this API you can get a full list of ASINs assigned to different modifications of a product (ASIN is the unique identifier of a product assigned by Amazon).

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

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

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

try {
    // POST /v2/merchant_amazon_asin_tasks_post/$data
    $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 = array();
    $post_array[$my_unq_id] = array(
    "priority" => 1,
    "se_id" => 2897,
    "product_id" => "B07F9M8CG3"
    );
    $task_post_result = $client->post('v2/merchant_amazon_asin_tasks_post', array('data' => $post_array));
    print_r($task_post_result);

    //do something with post results

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 1,
    "results": {
        "874654654": {
            "post_id": 874654654,
            "product_id": "B07F9M8CG3",
            "task_id": 1337336262,
            "se_id": 2897,
            "status": "ok"
        }
    }
}

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, sending the array of tasks into the data field. It is not recommended to set more than 100 tasks at a time due to different task variations you are likely to use.

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 sent to a specific URL. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

Description of the fields for setting a task:

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

se_id integer search engine id
optional field, if you specify se_name
you must choose one of the fields se_id or se_name
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
you must choose a search engine with the word “amazon” included in the se_name field to get se_id for Amazon
also, when the information about the set task is returned, you will get se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields se_id or se_name
you can get the list of available search engines with se_id by making a separate request to the List of Search Engines
you must specify a search engine where the field “se_name” contains the word “amazon”
example: “amazon.com”
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with their se_language by making a separate request to the List of Search Engines
example: “English”
product_id string product ID
required field
the unique product identifier in Amazon (ASIN)
se_param_add string additional parameters of search query
optional field
for example, if you want to disable auto correction of misspelling in the search query, you should specify “&nfpr=1”
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify the postback URL there will be no need to use Get Amazon ASIN Tasks Results for obtaining results. We will send the result of a completed task by the POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$task_id’ string as the $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 a task, you send its data in the array using data fields. The index of the task in this array ($my_unq_id variable in examples) can be used at any time after that, as the post_id field. It will be returned to you with all server responses as well as our unique task_id field. Thanks to this feature, you can use this field to associate the set tasks with identifiers in your system.

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=”error”, check theerror array for more details
error array the informational array of the error
only if status=”error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count integer number of elements in the results array
results array results array of task setting
            task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results at any time within the next 30 days.
            status string results of this task setting
“ok” – success
“error” – error
if status=”error”, check theerror array for more details
            error array the informational array of the error
only if status=”error”
the list of possible errors can be found below.
                  code integer error code
                  message string text description of the error
            post_id string index in the array received in the POST request
            product_id string product ID
the unique product identifier in Amazon (ASIN) received in the POST request
            se_id integer search engine id
if status=”ok”, then this field will be always filled
You can use it for matching your search engines with the DataForSEO List of Search Engines


Possible error codes

Error Code Meaning
404 “not found or not enough data: search engine” – you’ve specified nonexistent se_id or a search engine according to the specified se_name wasn’t found
501 “invalid ‘data’ field” – probably you haven’t passed data for the tasks in the data field. POST data should be represented as an array and added to the data field: array(‘data’ => $post_array_for_tasks)
501 “invalid data” – data in the 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 Amazon ASIN Completed Tasks

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

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

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

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

    //get tasks one by one

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0120 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "874654654",
            "product_id": "B07F9M8CG3",
            "task_id": 1293377374,
            "se_id": 2897,
            "result_se_check_url": "https://www.amazon.com/dp/B07F9M8CG3?language=en_US"
        }
    ]
}

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

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

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

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:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”,check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count integer number of elements in the results array
results array results array of tasks
            post_id string index of the array received in the POST request
            task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results at any time within the next 30 days
            product_id string product ID
the unique product identifier in Amazon (ASIN) received in the POST request
            se_id integer search engine id
You can use it for matching your search engines with the DataForSEO List of Search Engines
            result_se_check_url string direct URL to search engine results
you can use it to make sure that we provided exact results

Get Amazon ASIN Results by task_id

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

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

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

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

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1103 sec.",
    "results_count": 1,
    "results": {
        "organic": [
            {
                "task_id": 1293367374,
                "post_id": "874654654",
                "se_id": 2897,
                "product_id": "B07F9M8CG3",
                "result_datetime": "2018-08-17 13:00:04 +00:00",
                "result_title": "Hetohec Sport Baseball Shoes Knitted Fashion Outdoor Sneakers Lightweight Gym Athletic Shoe Men Trail Workout",
                "result_description": "Below it will help us choose right size for shoes, compare the chart size with your feet length carefully before ordering.Thank you!  Size Chart:  EU38/6 D(M) US Men-Feet length: 9.65 Inches  EU39/6.5 D(M) US Men-Feet length: 9.84 Inches  EU40/7 D(M) US Men-Feet length: 10.04 Inches  EU41/8 D(M) US Men-Feet length: 10.24 Inches  EU42/8.5 D(M) US Men-Feet length: 10.43 Inches  EU43/9.5 D(M) US Men-Feet length: 10.63 Inches  EU44/10 D(M) US Men-Feet length: 10.84 Inches  EU45/11 D(M) US Men-Feet length: 11.05 Inches  EU46/12 D(M) US Men-Feet length: 11.22 Inches  EU47/13 D(M) US Men-Feet length: 11.41 Inches  If your foot is wider or fatter than the standard foot, we suggest that you consider increasing one size and order.  Contents  1 x Sport Running Shoes",
                "result_price_from": 4.99,
                "result_price_to": 18.99,
                "result_currency": "USD",
                "result_stars": 4,
                "result_reviews_count": 19,
                "result_seller_name": "Hetohec",
                "result_details": "Shipping Information:\r\nView shipping rates and policies \r\r\nASIN:\r\nB07F9J9SLJ \r\r\nItem model number:\r\nHetohec1266 \r\r\nDate first listed on Amazon:\r\nJuly 5, 2018 \r",
                "result_current_asin": "B07F9M8CG3",
                "result_parent_asin": "B07F9J9SLJ",
                "result_product_asins": [
                    "B07F9MLHHH",
                    "B07F9JW7WQ",
                    "B07F9NC524",
                    "B07F9GQN8K",
                    "B07G75GPYP",
                    "B07F9QFQH6",
                    "B07F9NWTSR",
                    "B07G75L9R7",
                    "B07G74QVRN",
                    "B07F9LMLBJ",
                    "B07F9NXL21",
                    "B07F9LTGC6",
                    "B07G768XYH",
                    "B07G751HSC",
                    "B07F9LDT26",
                    "B07G76CVJ9",
                    "B07F9KHZHK",
                    "B07F9H46FJ",
                    "B07G74Y7MQ",
                    "B07F9LC48J",
                    "B07G74QN4C",
                    "B07G75SDG1",
                    "B07F9M5CLV",
                    "B07F9K9J2S",
                    "B07F9HJXG2",
                    "B07F9N61S5",
                    "B07G77NKCS",
                    "B07G75YD59",
                    "B07F9M8CG3",
                    "B07F9KZ2XF",
                    "B07F9FZS5J",
                    "B07G77W9J2",
                    "B07G71R7SM",
                    "B07F9HPNNQ",
                    "B07F9JPXPC",
                    "B07G73C71M",
                    "B07G75R6LJ",
                    "B07F9L31QQ",
                    "B07G75YRD1",
                    "B07F9LP71K",
                    "B07G767TS1",
                    "B07F9K3F4T",
                    "B07G74NMBB",
                    "B07F9SSN95"
                ],
                "result_image_url": "https://images-na.ssl-images-amazon.com/images/I/51GlnhAlijL._SY395_QL70_FMwebp_.jpg",
                "result_se_check_url": "https://www.amazon.com/dp/B07F9M8CG3?language=en_US"
            }
        ]
    }
}

Description of the fields for a requesting the results:

Field name Type Description
task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results at any time within the next 30 days


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:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count integer number of elements in the results array
results array results array of task setting
      organic array results array of organic Amazon ASINs
            task_id integer unique task identifier in our system(UInt64)
you can use task_id to request task results at any time within the next 30 days. You are charged for each GET request for receiving results.
            post_id string index in the array received in a POST array
            se_id integer search engine id
            product_id string product ID
the unique identifier of a product in Amazon (ASIN)
received in a POST request
            result_datetime string date and time when a result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
            result_title string product title
            result_description string product description
            result_price_from float the regular price of a product
if there are no values, you will get null
            result_price_to float the upper limit of a product price range
if there are no values, you will get null
            result_currency string currency type
in the ISO format
if there are no values, you will get null
            result_stars float product rating
(represented by star symbols) from 0 to 5
if there are no values, you will get null
            result_reviews_count integer amount of feedback
left by users for a certain product
if there are no values, you will get null
            result_seller_name string seller name
            result_details string details
if there are no values, you will get null
            result_current_asin string current ASIN
ASIN of the product
Please note that if the id is parent, then you will see the child ASIN of the product presented on the Amazon page in this field
            result_parent_asin string parent ASIN
            result_product_asins array product ASINs
list of ASINs
            result_image_url string image URL
            result_se_check_url string direct URL to search engine results
you can use it to make sure that we provided exact results


Possible error codes

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