NAVNavbar
Logo
php python csharp java

Keywords Data API

Google

Keywords Data API is a toolkit designed for keyword research and analysis. Our system uses Google AdWords API, that’s why we have the corresponding possibilities and limits. Google doesn’t return data for keywords that fall into such categories as weapons, tobacco, drugs, violence, and terrorism. If you want to learn more about Google restrictions and prohibited categories, check the article on our blog.

Please note that if you post, for instance, 100 keywords and at least one of them matches the specified categories, no data for the whole keyword list will be retrieved. You can find more details on Google Advertising Policies Help.

You can use Clickstream as a data source for getting keyword data that Google doesn’t provide.

The operating principle of Keywords Data API is similar to that of Rank Tracker API. The main difference is that with Keywords Data 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 Keywords Data API task.

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

Search Volume for Keyword


You can receive the search volume data for the last month, search volume trend for the last year (that allows estimating search volume dynamics), current cost-per-click and competition value for paid search.

There are two methods to retrieve data: Live and Delayed

Live data retrieving fits perfectly in case your app functionality implies real-time data providing. With this method, you will get results within 30 seconds after the task is posted.

If you have requests that don’t require real-time data retrieval, then the delayed queue is the best solution for you. Set a task and retrieve the results when our system collects them. On average it takes 15-30 minutes to receive the results.

You can also check the update status of keywords search volume returned by Google API using Get AdWords Status.

The updated data for this method is available starting from the 15th day of a month till its end.

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

Live Data

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');

    $post_array[] = array(
    "language" => "en",
    "loc_name_canonical"=> "United States",
    "key" => "average page rpm adsense"
    );
    $post_array[] = array(
    "language" => "en",
    "loc_id" => 2840,
    "key" => "adsense blank ads how long"
    );
    $post_array[] = array(
    "language" => "en",
    "loc_name_canonical"=> "United States",
    "key" => "leads and prospects"
    );

    $sv_post_result = $client->post('v2/kwrd_sv', array('data' => $post_array));
    print_r($sv_post_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";
    exit();
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "task_id": 423292503,
    "results_time": "2.1886 sec.",
    "results_count": 3,
    "results": [
        {
            "language": "en",
            "loc_id": 2840,
            "key": "leads and prospects",
            "cmp": 0.47619047619048,
            "cpc": 0,
            "sv": 10,
            "categories": [
                10019,
                10276,
                10885,
                11273,
                13418,
                11088,
                12209,
                10004,
                10102,
                10007,
                12376,
                10296,
                10168,
                10012
            ],
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 10
                }
            ]
        },
        {
            "language": "en",
            "loc_id": 2840,
            "key": "adsense blank ads how long",
            "cmp": 0,
            "cpc": 0,
            "sv": 10,
            "categories": [],
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 0
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 0
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 0
                }
            ]
        },
        {
            "language": "en",
            "loc_id": 2840,
            "key": "average page rpm adsense",
            "cmp": null,
            "cpc": null,
            "sv": null,
            "categories": [],
            "ms": null
        }
    ]
}

You don’t have to group keywords according to the required location/language. Send as many array elements for any language/location as you need. Our system will charge credits per each keyword in the array.

All POST data should be sent in the JSON format (UTF-8 encoding).The keywords are sent by the POST method passing tasks array. The data should be specified in the data field of this POST array. We recommend to send up to 100 tasks at a time.

Each array element has the following structure:

Field name Type Description
key string keyword
required field
for example: “rank tracker api”
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
language string language
optional field
note that we do not recommend using this field when setting a task
if you specify the language, Google may return the search volume value as null
you can find more details here
if you use this field, you can specify the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting
search_partners boolean Google search partners
optional field
if you specify the true value in the field, the results will be delivered considering Google and search partners. By default, search partners are not considered


As a response from the API server, you will receive a JSON array with keywords data in the results field.

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
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
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            language string language
            loc_id integer search engine location id
            key string keyword
keyword is returned with decoded %## (plus symbol ‘+’ is decoded to a space character)
            cmp float competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Google Ads data and can be between 0 and 1 (inclusive).
if there is no data, then the value is null
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is null
            sv integer the average annual search volume rate
represents the (approximate) number of searches for the keyword on google.com or google.com and partners, depending on the user’s targeting
if there is no data, then the value is null
            categories array product and service categories
you can download the full list of possible categories
            ms array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is null


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this fields: field” – please check the parameters specified in the field
404 “not found or not enough data: location” – you have specified a nonexistent loc_id, or the location for the search engine according to your loc_name_canonical wasn’t found
500 “RateExceededError” – occurs when our service exceeds the Queries Per Second (QPS) limit set by Google API. Any service that works with Google API has this limit. We are working on expanding the limits. More details about Google API limits can be found here: developers.google.com – docs/rate-limits.We recommend to process these errors (just like any other errors) and set the next task in 30 seconds if such error occurs.

Set Task

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();
$post_array["your post_id parameter here"] = array( 
    "language" => "en",
    "loc_name_canonical" => "United States",
    "key" => "best seo",
    "pingback_url" => 'https://your-server.com/your_pingback_url.php?task_id=$task_id&post_id=$post_id'
);

if (count($post_array) > 0) {
    try {
        $task_post_result = $client->post('/v2/kwrd_sv_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.0829 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "your post_id parameter here",
            "task_id": 218390,
            "status": "ok"
        }
    ]
}

You don’t have to group keywords according to the required location/language. Send as many array elements for any language/location as you need. Our system will charge credits per each keyword in the array.

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent by the POST method passing tasks array. The data should be specified in the data field of this POST array. We recommend to send up to 100 tasks at a time.

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

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

Description of the fields for setting a task:

Field name Type Description
key string keyword
required field
for example: “rank tracker api”
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
language string language
optional field
note that we do not recommend using this field when setting a task
if you specify the language, Google may return the search volume value as null
you can find more details here
if you use this field, you can specify the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting
search_partners boolean Google search partners
optional field
if you specify the true value in the field, the results will be delivered considering Google and search partners. By default, search partners are not considered
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 Results by task_id 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 an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            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


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
404 “not found or not enough data: location” – you have specified a nonexistent loc_id, or the location for the search engine according to your loc_name_canonical wasn’t found
404 “‘data’ field structure is invalid” – specify the parameters to set a task
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_sv_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_sv_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.0594 sec.",
    "results_count": 2,
    "results": [
        {
            "task_id": 218796,
            "post_id": "your post_id parameter here",
            "status": "ok"
        },
        {
            "task_id": 218800,
            "post_id": "your post_id parameter here",
            "status": "ok"
        }
    ]
}

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

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

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
            post_id string the index in the array received in the POST array
            status string results of this task setting
“ok” – success
“error” – error
if status=“error”, check the error array for more details


Possible error codes:

Error Code Meaning
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_sv_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_sv_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/kwrd_sv_tasks_get/$task_id
            $kwrd_sv_result = $client->get('v2/kwrd_sv_tasks_get/'.$tasks_get_row["task_id"]);
            print_r($kwrd_sv_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.0722 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 218800,
            "post_id": "your post_id parameter here",
            "status": "ok",
            "result": [
                {
                    "language": "en",
                    "loc_id": 2840,
                    "key": "best seo company",
                    "cmp": 0.3628918537802365,
                    "cpc": 30.300584,
                    "sv": 2900,
                    "categories": [
                        13152,
                        11088,
                        13316,
                        10276,
                        10004,
                        10007,
                        12376,
                        13418
                    ],
                    "ms": [
                        {
                            "year": 2017,
                            "month": 12,
                            "count": 2400
                        },
                        {
                            "year": 2017,
                            "month": 11,
                            "count": 2400
                        },
                        {
                            "year": 2017,
                            "month": 10,
                            "count": 2900
                        },
                        {
                            "year": 2017,
                            "month": 9,
                            "count": 2400
                        },
                        {
                            "year": 2017,
                            "month": 8,
                            "count": 2400
                        },
                        {
                            "year": 2017,
                            "month": 7,
                            "count": 2400
                        },
                        {
                            "year": 2017,
                            "month": 6,
                            "count": 2400
                        },
                        {
                            "year": 2017,
                            "month": 5,
                            "count": 6600
                        },
                        {
                            "year": 2017,
                            "month": 4,
                            "count": 2400
                        },
                        {
                            "year": 2017,
                            "month": 3,
                            "count": 2900
                        },
                        {
                            "year": 2017,
                            "month": 2,
                            "count": 2900
                        },
                        {
                            "year": 2017,
                            "month": 1,
                            "count": 2400
                        }
                    ]
                }
            ]
        }
    ]
}

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

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time. You are charged for each GET request for receiving the results.
post_id string the index of the array received in the POST array
status string result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
results array results array of tasks setting
            language string language
            loc_id integer search engine location id
            key string keyword
keyword is returned decoded %## (plus symbol ‘+’ is decoded to a space character)
            cmp float competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Google Ads data and can be between 0 and 1 (inclusive).
if there is no data, then the value is null
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is null
            sv integer the average annual search volume rate
represents the (approximate) number of searches for the keyword on google.com or google.com and partners, depending on the user’s targeting
if there is no data, then the value is null
            categories array product and service categories
you can download the full list of possible categories
            ms array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is null


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
500 “internal error” – some internal error. We did our bestnot not to let this type of error ever happen.

Bulk Keyword Search Volume


You can receive the search volume data for the last month, search volume trend for the last year (that allows estimating search volume dynamics), current cost-per-click and competition value for paid search.

You can get the required information in a bulk for up to 700 keywords. For this, create an array of 700 keywords for the same location/language.

There are two methods to retrieve data: Live and Delayed.

Live data retrieving fits perfectly in case your app functionality implies real-time data providing. With this method, you will get results within 30 seconds after the task is posted.

If you have requests that don’t require real-time data retrieval, then the delayed queue is the best solution for you. Set a task and retrieve the results when our system collects them. On average it takes 15-30 minutes to receive the results.

You can also check the update status of keywords search volume returned by Google API using Get AdWords Status.

The updated data for this method is available starting from the 15th day of a month till its end.

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

Live Data

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');

    $post_array[] = array(
        "language" => "en",
        "loc_name_canonical"=> "United States",
        "keys" => array(
            "average page rpm adsense",
            "adsense blank ads how long",
            "leads and prospects"
        )
    );

    $sv_post_result = $client->post('v2/kwrd_sv_batch', array('data' => $post_array));
    print_r($sv_post_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";
    exit();
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "task_id": 423292503,
    "results_time": "2.1886 sec.",
    "results_count": 3,
    "results": [
        {
            "language": "en",
            "loc_id": 2840,
            "key": "leads and prospects",
            "cmp": 0.47619047619048,
            "cpc": 0,
            "sv": 10,
            "categories": [
                10019,
                10276,
                10885,
                11273,
                13418,
                11088,
                12209,
                10004,
                10102,
                10007,
                12376,
                10296,
                10168,
                10012
            ],
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 10
                }
            ]
        },
        {
            "language": "en",
            "loc_id": 2840,
            "key": "adsense blank ads how long",
            "cmp": 0,
            "cpc": 0,
            "sv": 10,
            "categories": [],
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 0
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 0
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 0
                }
            ]
        },
        {
            "language": "en",
            "loc_id": 2840,
            "key": "average page rpm adsense",
            "cmp": null,
            "cpc": null,
            "sv": null,
            "categories": [],
            "ms": null
        }
    ]
}

If you send more than 700 keywords in one array, the number of keywords will be divided by 700, and the total charged requests will be rounded up.

For instance, if you send 1500 keywords in one array, the system will charge 450 credits (3 API requests * 150 credits).
If you send 300 keywords in one array, the system will charge 150 credits (one API request).
If you send 700 keywords in one array, the system will also charge 150 credits.

We recommend to send up to 2100 in one request to avoid any technical issues while retrieving the data.

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent by the POST method passing tasks array. The data should be specified in the data field of this POST array. We recommend to send up to 100 tasks at a time.

Each array element has the following structure:

Field name Type Description
keys array keywords array
required field
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
language string language
optional field
note that we do not recommend using this field when setting a task
if you specify the language, Google may return the search volume value as null
you can find more details here
if you use this field, you can specify the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting
sort_by string results sorting column
optional field
by default the results are sorted by the “sv” field, if you don’t want to receive sorted results, specify “none” value in the field
search_partners boolean Google search partners
optional field
if you specify the true value in the field, the results will be delivered considering Google and search partners. By default, search partners are not considered


As a response from the API server, you will receive a JSON array with keywords data in the results field.

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
task_id integer unique task identifier in our system (UInt64)
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            language string language
            loc_id integer search engine location id
            key string keyword
keyword is returned decoded %## (plus symbol ‘+’ is decoded to a space character)
            cmp float competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Google Ads data and can be between 0 and 1 (inclusive).
if there is no data, then the value is null
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is null
            sv integer the average annual search volume rate
represents the (approximate) number of searches for the keyword on google.com or google.com and partners, depending on the user’s targeting
if there is no data, then the value is null
            categories array product and service categories
you can download the full list of possible categories
            ms array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is null


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
404 “not found or not enough data: location” – you have specified a nonexistent loc_id, or the location for the search engine according to your loc_name_canonical wasn’t found
500 “RateExceededError” – occurs when our service exceeds the Queries Per Second (QPS) limit set by Google API. Any service that works with Google API has this limit. We are working on expanding the limits. More details about Google API limits can be found here: developers.google.com – docs/rate-limits.We recommend to process these errors (just like any other errors) and set the next task in 30 seconds if such error occurs.

Set Task

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();
$post_array["your post_id parameter here"] = array( 
    "language" => "en",
    "loc_name_canonical" => "United States",
    "keys" => array(
        "repeat customers",
        "best sleeping wireless earbuds",
        "staniel cay day trip",
        "iota hoodie",
        "monero hat"
    ),
    "pingback_url" => 'https://your-server.com/your_pingback_url.php?task_id=$task_id&post_id=$post_id'
);

if (count($post_array) > 0) {
    try {
        $task_post_result = $client->post('/v2/kwrd_sv_batch_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.0855 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "your post_id parameter here",
            "task_id": 218876,
            "status": "ok"
        }
    ]
}

If you send more than 700 keywords in one array, the number of keywords will be divided by 700 and the total charged requests rounded up.

For instance, if you send 1500 keywords in one array, the system will charge 300 credits (3 API requests * 100 credits).
If you send 300 keywords in one array, the system will charge 100 credits (one API request).
If you send 700 keywords in one array, the system will also charge 100 credits.

We recommend to send up to 2100 in one request to avoid any technical issues while retrieving the data.

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent by the POST method passing tasks array. The data should be specified in the data field of this POST array. We recommend to send up to 100 tasks at a time.

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

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

Description of the fields for setting a task:

Field name Type Description
keys array keywords array
required field
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
language string language
optional field
note that we do not recommend using this field when setting a task
if you specify the language, Google may return the search volume value as null
you can find more details here
if you use this field, you can specify the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting
sort_by string results sorting column
optional field
by default the results are sorted by “sv” field, if you don’t want to receive sorted results, specify “none” value in the field
search_partners boolean Google search partners
optional field
if you specify the true value in the field, the results will be delivered considering Google and search partners. By default, search partners are not considered
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 Results by task_id. 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 an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            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


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
404 “not found or not enough data: location” – you have specified a nonexistent loc_id, or the location for the search engine according to your loc_name_canonical wasn’t found
404 “‘data’ field structure is invalid” – specify the parameters to set a task
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_sv_batch_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_sv_batch_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.0599 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 218876,
            "post_id": "your post_id parameter here",
            "status": "ok"
        }
    ]
}

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

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

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            status string result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details


Possible error codes:

Error Code Meaning
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_sv_batch_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_sv_batch_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/kwrd_sv_batch_tasks_get/$task_id
            $kwrd_sv_batch_result = $client->get('v2/kwrd_sv_batch_tasks_get/'.$tasks_get_row["task_id"]);
            print_r($kwrd_sv_batch_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.0751 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 218876,
            "post_id": "your post_id parameter here",
            "status": "ok",
            "result": [
                {
                    "language": "en",
                    "loc_id": 2840,
                    "key": "repeat customers",
                    "cmp": 0.15841979249800478,
                    "cpc": 0,
                    "sv": 390,
                    "categories": [
                        11088,
                        12378,
                        10276,
                        10004,
                        10007
                    ],
                    "ms": [
                        {
                            "year": 2017,
                            "month": 12,
                            "count": 390
                        },
                        {
                            "year": 2017,
                            "month": 11,
                            "count": 480
                        },
                        {
                            "year": 2017,
                            "month": 10,
                            "count": 480
                        },
                        {
                            "year": 2017,
                            "month": 9,
                            "count": 390
                        },
                        {
                            "year": 2017,
                            "month": 8,
                            "count": 390
                        },
                        {
                            "year": 2017,
                            "month": 7,
                            "count": 320
                        },
                        {
                            "year": 2017,
                            "month": 6,
                            "count": 390
                        },
                        {
                            "year": 2017,
                            "month": 5,
                            "count": 390
                        },
                        {
                            "year": 2017,
                            "month": 4,
                            "count": 390
                        },
                        {
                            "year": 2017,
                            "month": 3,
                            "count": 480
                        },
                        {
                            "year": 2017,
                            "month": 2,
                            "count": 390
                        },
                        {
                            "year": 2017,
                            "month": 1,
                            "count": 480
                        }
                    ]
                },
                {
                    "language": "en",
                    "loc_id": 2840,
                    "key": "best sleeping wireless earbuds",
                    "cmp": null,
                    "cpc": null,
                    "sv": null,
                    "categories": [],
                    "ms": null
                }
            ]
        }
    ]
}

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
post_id string the index in the array received in the POST request
status string results of this task setting
“ok” – success
“error” – error
if status=“error”, check the error array for more details
results array results array of tasks setting
            language string language
            loc_id integer search engine location id
            key string keyword
keyword is returned decoded %## (plus symbol ‘+’ is decoded to a space character)
            cmp float competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Google Ads data and can be between 0 and 1 (inclusive).
if there is no data, then the value is null
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is null
            sv integer the average annual search volume rate
represents the (approximate) number of searches for the keyword on google.com or google.com and partners, depending on the user’s targeting
if there is no data, then the value is null
            categories array product and service categories
you can download the full list of possible categories
            ms array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is null


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

Keywords for Domain


This option will select keywords for the specified domain. In addition to keywords, you will also receive search volume for the last month, search volume trend for the last year (that allows estimating search volume dynamics), current cost-per-click and competition level for paid search.

There are two methods to retrieve data: Live and Delayed

Live data retrieving fits perfectly in case your app functionality implies real-time data providing. With this method, you will get results within 30 seconds after the task is posted.

If you have requests that don’t require real-time data retrieval, then the delayed queue is the best solution for you. Set a task and retrieve the results when our system collects them. On average it takes 15-30 minutes to receive the results.

You can also check the update status of keywords search volume returned by Google API using Get AdWords Status.

The updated data for this method is available starting from the 15th day of a month till its end.

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

Live Data

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');

    $kw_get_result = $client->get('v2/kwrd_for_domain/ranksonic.com/us/en');
    print_r($kw_get_result);

    //do something with results

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "task_id": 423292503,
    "results_time": "5.6869 sec.",
    "results_count": 700,
    "results": [
        {
            "language": "en",
            "loc_id": 2840,
            "key": "seo checker",
            "cmp": 0.73449937159615,
            "cpc": 268.914463,
            "sv": 3600,
            "categories": [
                13152,
                11088,
                13316,
                10276,
                10004,
                10007,
                12376,
                13418
            ],
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 4400
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 3600
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 4400
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 3600
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 4400
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 3600
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 3600
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 3600
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 3600
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 3600
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 2900
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 2900
                }
            ]
        },
        {
            "language": "en",
            "loc_id": 2840,
            "key": "seo software",
            "cmp": 0.61448140900196,
            "cpc": 207.076566,
            "sv": 1600,
            "categories": [
                13152,
                11088,
                13316,
                10276,
                10004,
                10007,
                12376,
                13418
            ],
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 1900
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 2400
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 1900
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 1600
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 1300
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 1900
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 2400
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 1300
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 1600
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 1900
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 1300
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 1300
                }
            ]
        },

        {
            "language": "en",
            "loc_id": 2840,
            "key": "check serp ranking for keyword",
            "cmp": 0.097560975609756,
            "cpc": 0,
            "sv": 10,
            "categories": [
                13152,
                10019,
                13316,
                10276,
                10885,
                11497,
                13418,
                11498,
                12204,
                11088,
                10004,
                10007,
                12376,
                10168
            ],
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 40
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 50
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 20
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 20
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 10
                }
            ]
        }
    ]
}

Keywords are received through the GET method with the following parameters:

Field name Type Description
domain string domain
required field
you can also specify the URL in single quotes, like
GET https://api.dataforseo.com/v2/kwrd_for_domain/'https://seo.com/page/'/us/en
country_code string ISO country code
optional field
language string language
optional field
can have the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting
sort_by string results sorting column
optional field
can have the following values: “sv”, “relevance”
default value: “sv”


As a response of the API server, you will receive a JSON array with data on the selected keywords in the results field. The maximum amount of the selected keywords is 700. The results array is returned according to the sorting field sv.

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
task_id integer unique task identifier in our system (UInt64)
results_time string execution time, seconds
results_count integer the number of elements in the results array results
results array results array
            language string language
            loc_id integer search engine location id
            key string keyword
            cmp float competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Google Ads data and can be between 0 and 1 (inclusive).
if there is no data, then the value is null
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is null
            sv integer the average annual search volume rate
represents the (approximate) number of searches for the keyword on google.com or google.com and partners, depending on the user’s targeting
if there is no data, then the value is null
            categories array product and service categories
you can download the full list of possible categories
            ms array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is null


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
500 “RateExceededError” – occurs when our service exceeds the Queries Per Second (QPS) limit set by Google API. Any service that works with Google API has this limit. We are working on expanding the limits. More details about Google API limits can be found here: developers.google.com – docs/rate-limits.We recommend to process these errors (just like any other errors) and set the next task in 30 seconds if such error occurs.

Set Task

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();
$post_array["your post_id parameter here"] = array( 
    "domain" => "ranksonic.com",
    "country_code" => "us",
    "language" => "en",
    "sort_by" => "relevance",
    "pingback_url" => 'https://your-server.com/your_pingback_url.php?task_id=$task_id&post_id=$post_id'
);

if (count($post_array) > 0) {
    try {
        $task_post_result = $client->post('/v2/kwrd_for_domain_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.0790 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "your post_id parameter here",
            "task_id": 219163,
            "status": "ok"
        }
    ]
}

All POST data should be sent in the JSON format (UTF-8 encoding). The domains are sent through the POST method passing the tasks array. The data should be specified in the data field of this POST array. We recommend to send up to 100 tasks at a time.

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

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

Each array element has the following structure:

Field name Type Description
domain string domain
required field
you can also specify a URL
country_code string ISO country code
optional field
language string language
optional field
can have the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting
sort_by string results sorting column
optional field
can have the following values: “sv”, “relevance”
default value: “sv”
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 Results by task_id. 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 an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            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


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
404 “not found or not enough data: location” – you have specified a nonexistent loc_id, or the location for the search engine according to your loc_name_canonical wasn’t found
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_for_domain_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_for_domain_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.0979 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 254521,
            "post_id": "your post_id parameter here",
            "status": "ok"
        }
    ]
}

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

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

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            status string result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details


Possible error codes:

Error Code Meaning
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_for_domain_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_for_domain_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/kwrd_for_domain_tasks_get/$task_id
            $kwrd_for_domain_result = $client->get('v2/kwrd_for_domain_tasks_get/'.$tasks_get_row["task_id"]);
            print_r($kwrd_for_domain_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.0929 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 219066,
            "post_id": "your post_id parameter here",
            "status": "ok",
            "result": [
                {
                    "language": "en",
                    "loc_id": 2840,
                    "key": "free seo keyword generator",
                    "cmp": 0.4647887323943662,
                    "cpc": 6.850526,
                    "sv": 40,
                    "categories": [
                        13152,
                        11088,
                        10081,
                        13316,
                        10276,
                        10004,
                        10007,
                        10423,
                        12376,
                        13418,
                        10010,
                        11595
                    ],
                    "ms": [
                        {
                            "year": 2017,
                            "month": 12,
                            "count": 70
                        },
                        {
                            "year": 2017,
                            "month": 11,
                            "count": 40
                        },
                        {
                            "year": 2017,
                            "month": 10,
                            "count": 30
                        },
                        {
                            "year": 2017,
                            "month": 9,
                            "count": 30
                        },
                        {
                            "year": 2017,
                            "month": 8,
                            "count": 20
                        },
                        {
                            "year": 2017,
                            "month": 7,
                            "count": 30
                        },
                        {
                            "year": 2017,
                            "month": 6,
                            "count": 30
                        },
                        {
                            "year": 2017,
                            "month": 5,
                            "count": 30
                        },
                        {
                            "year": 2017,
                            "month": 4,
                            "count": 30
                        },
                        {
                            "year": 2017,
                            "month": 3,
                            "count": 30
                        },
                        {
                            "year": 2017,
                            "month": 2,
                            "count": 50
                        },
                        {
                            "year": 2017,
                            "month": 1,
                            "count": 40
                        }
                    ]
                },
                {
                    "language": "en",
                    "loc_id": 2840,
                    "key": "free seo keyword tool",
                    "cmp": 0.33124018838304553,
                    "cpc": 3.66848,
                    "sv": 210,
                    "categories": [
                        13152,
                        11088,
                        13316,
                        10276,
                        10004,
                        10007,
                        12376,
                        13418
                    ],
                    "ms": [
                        {
                            "year": 2017,
                            "month": 12,
                            "count": 170
                        },
                        {
                            "year": 2017,
                            "month": 11,
                            "count": 210
                        },
                        {
                            "year": 2017,
                            "month": 10,
                            "count": 260
                        },
                        {
                            "year": 2017,
                            "month": 9,
                            "count": 210
                        },
                        {
                            "year": 2017,
                            "month": 8,
                            "count": 170
                        },
                        {
                            "year": 2017,
                            "month": 7,
                            "count": 170
                        },
                        {
                            "year": 2017,
                            "month": 6,
                            "count": 170
                        },
                        {
                            "year": 2017,
                            "month": 5,
                            "count": 170
                        },
                        {
                            "year": 2017,
                            "month": 4,
                            "count": 210
                        },
                        {
                            "year": 2017,
                            "month": 3,
                            "count": 170
                        },
                        {
                            "year": 2017,
                            "month": 2,
                            "count": 140
                        },
                        {
                            "year": 2017,
                            "month": 1,
                            "count": 210
                        }
                    ]
                }
            ]
        }
    ]
}

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

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time.
post_id string the index of the array received in the POST array
status string result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
results array results array of tasks setting
      language string language
      loc_id integer search engine location id
      key string keyword
            cmp float competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Google Ads data and can be between 0 and 1 (inclusive).
if there is no data, then the value is null
      cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is null
      sv integer the average annual search volume rate
represents the (approximate) number of searches for the keyword on google.com or google.com and partners, depending on the user’s targeting
if there is no data, then the value is null
      categories array product and service categories
you can download the full list of possible categories here
      ms array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is null


Possible errors codes

Error Code Meaning
102 “task in queue” – the task is being enqueued to handling, please, try again later
201 “task handed” – the task has been received and sent to handling, please, try again later
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Keywords for Keywords


This option will select keyword suggestions for the specified keywords. In addition to new keyword ideas, you will receive search volume for the last month, search volume trend for the last year (that allows estimating search volume dynamics), current cost-per-click and competition level for paid search.

There are two methods to retrieve data: Live and Delayed

Live data retrieving fits perfectly in case your app functionality implies real-time data providing. With this method, you will get results within 30 seconds after the task is posted.

If you have requests that don’t require real-time data retrieval, then the delayed queue is the best solution for you. Set a task and retrieve the results when our system collects them. On average, it takes 15-30 minutes to receive the results.

You can also check the update status of keywords search volume returned by Google API using Get AdWords Status.

The updated data for this method is available starting from the 15th day of a month till its end.

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

Live Data

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');

    $post_array[] = array(
    "language" => "en",
    "loc_name_canonical"=> "United States",
    "keys" => array("seo", "seo agency", "seo marketing")
    );

    $kw_post_result = $client->post('v2/kwrd_for_keywords', array('data' => $post_array));
    print_r($kw_post_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";
    exit();
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "task_id": 423292503,
    "results_time": "5.6869 sec.",
    "results_count": 700,
    "results": [
        {
            "language": "en",
            "loc_id": 2840,
            "key": "seo checker",
            "cmp": 0.73449937159615,
            "cpc": 268.914463,
            "sv": 3600,
            "categories": [
                13152,
                11088,
                13316,
                10276,
                10004,
                10007,
                12376,
                13418
            ],
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 4400
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 3600
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 4400
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 3600
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 4400
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 3600
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 3600
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 3600
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 3600
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 3600
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 2900
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 2900
                }
            ]
        },
        {
            "language": "en",
            "loc_id": 2840,
            "key": "seo software",
            "cmp": 0.61448140900196,
            "cpc": 207.076566,
            "sv": 1600,
            "categories": [
                13152,
                11088,
                13316,
                10276,
                10004,
                10007,
                12376,
                13418
            ],
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 1900
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 2400
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 1900
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 1600
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 1300
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 1900
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 2400
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 1300
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 1600
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 1900
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 1300
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 1300
                }
            ]
        },

        {
            "language": "en",
            "loc_id": 2840,
            "key": "check serp ranking for keyword",
            "cmp": 0.097560975609756,
            "cpc": 0,
            "sv": 10,
            "categories": [
                13152,
                10019,
                13316,
                10276,
                10885,
                11497,
                13418,
                11498,
                12204,
                11088,
                10004,
                10007,
                12376,
                10168
            ],
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 40
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 50
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 20
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 20
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 10
                }
            ]
        }
    ]
}

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent through the POST method passing a tasks array. The data should be specified in the data field of this POST array. We recommend to send up to 100 tasks at a time.

Each array element has the following structure:

Field name Type Description
keys array keywords array
required field
You can specify a maximum of 200 keywords
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
Please note that the ‘Postal Code’ is not supported in  Keywords Data API.
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
language string language
optional field
can have the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting
sort_by string results sorting column
optional field
can have the following values: “sv”, “relevance”
default value: “sv”
keys_negative array negative keywords array
optional field
These keywords will be ignored in the results array
You can specify a maximum of 200 keywords
closely_variants boolean closely variants
optional field
Only the results that are highly relevant to the provided keywords will be shown
if this option is chosen, keys_negative should not be the same as the provided default value: false


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
task_id integer unique task identifier in our system (UInt64)
results_time string execution time, seconds
results_count integer the number of elements in the results array
results array results array
            language string language
            loc_id integer search engine location id
            key string keyword
            cmp float competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Google Ads data and can be between 0 and 1 (inclusive).
if there is no data, then the value is null
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is null
            sv integer the average annual search volume rate
represents the (approximate) number of searches for the keyword on google.com or google.com and partners, depending on the user’s targeting
if there is no data, then the value is null
            categories array product and service categories
you can download the full list of possible categories
            ms array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is null


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
404 “not found or not enough data: location” – you have specified a nonexistent loc_id, or the location for the search engine according to your loc_name_canonical wasn’t found
500 “RateExceededError” – occurs when our service exceeds the Queries Per Second (QPS) limit set by Google API. Any service that works with Google API has this limit. We are working on expanding the limits. More details about Google API limits can be found here: developers.google.com – docs/rate-limits.We recommend to process these errors (just like any other errors) and set the next task in 30 seconds if such error occurs.

Set Task

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();
$post_array["your post_id parameter here"] = array( 
    "language" => "en",
    "loc_name_canonical" => "United States",
    "keys" => array(
        "online rank checker",
        "best seo"
    ),
    "pingback_url" => 'https://your-server.com/your_pingback_url.php?task_id=$task_id&post_id=$post_id'
);

if (count($post_array) > 0) {
    try {
        $task_post_result = $client->post('/v2/kwrd_for_keywords_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.0784 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "your post_id parameter here",
            "task_id": 219428,
            "status": "ok"
        }
    ]
}

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent through the POST method passing a tasks array. The data should be specified in the data field of this POST array. We recommend to send up to 100 tasks at a time.

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

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

Description of the fields for setting a task:

Field name Type Description
keys array keywords array
required field
You can specify a maximum of 200 keywords
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
language string language
optional field
can have the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting
sort_by string results sorting column
optional field
can have the following values: “sv”, “relevance”
default value: “sv”
keys_negative array negative keywords array
optional field
These keywords will be ignored in the results array
You can specify the maximum of 200 keywords
closely_variants boolean closely variants
optional field
Only the results that are highly relevant to the provided keywords will be shown
if this option is chosen, keys_negative should not be the same as the provided default value: false
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 Results by task_id 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 an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            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


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
404 “not found or not enough data: location” – you have specified a nonexistent loc_id, or the location for the search engine according to your loc_name_canonical wasn’t found
404 “‘data’ field structure is invalid” – specify the parameters to set a task
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_for_keywords_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_for_keywords_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.0974 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 219463,
            "post_id": "your post_id parameter here",
            "status": "ok"
        }
    ]
}

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

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

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            status string result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details


Possible error codes:

Error Code Meaning
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_for_keywords_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_for_keywords_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/kwrd_for_keywords_tasks_get/$task_id
            $kwrd_for_keywords_result = $client->get('v2/kwrd_for_keywords_tasks_get/'.$tasks_get_row["task_id"]);
            print_r($kwrd_for_keywords_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.0985 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 219463,
            "post_id": "your post_id parameter here",
            "status": "ok",
            "result": [
                {
                    "language": "en",
                    "loc_id": 2840,
                    "key": "serp",
                    "cmp": 0.007817985417229273,
                    "cpc": 3.044352,
                    "sv": 12100,
                    "categories": [
                        13152,
                        11088,
                        13316,
                        10276,
                        10004,
                        10007,
                        12376,
                        13418
                    ],
                    "ms": [
                        {
                            "year": 2017,
                            "month": 12,
                            "count": 9900
                        },
                        {
                            "year": 2017,
                            "month": 11,
                            "count": 12100
                        },
                        {
                            "year": 2017,
                            "month": 10,
                            "count": 12100
                        },
                        {
                            "year": 2017,
                            "month": 9,
                            "count": 9900
                        },
                        {
                            "year": 2017,
                            "month": 8,
                            "count": 12100
                        },
                        {
                            "year": 2017,
                            "month": 7,
                            "count": 12100
                        },
                        {
                            "year": 2017,
                            "month": 6,
                            "count": 9900
                        },
                        {
                            "year": 2017,
                            "month": 5,
                            "count": 12100
                        },
                        {
                            "year": 2017,
                            "month": 4,
                            "count": 12100
                        },
                        {
                            "year": 2017,
                            "month": 3,
                            "count": 12100
                        },
                        {
                            "year": 2017,
                            "month": 2,
                            "count": 12100
                        },
                        {
                            "year": 2017,
                            "month": 1,
                            "count": 12100
                        }
                    ]
                },
                {
                    "language": "en",
                    "loc_id": 2840,
                    "key": "best seo",
                    "cmp": 0.18683419830647363,
                    "cpc": 7.467613,
                    "sv": 880,
                    "categories": [
                        13152,
                        11088,
                        13316,
                        10276,
                        10004,
                        10007,
                        12376,
                        13418
                    ],
                    "ms": [
                        {
                            "year": 2017,
                            "month": 12,
                            "count": 1000
                        },
                        {
                            "year": 2017,
                            "month": 11,
                            "count": 480
                        },
                        {
                            "year": 2017,
                            "month": 10,
                            "count": 1000
                        },
                        {
                            "year": 2017,
                            "month": 9,
                            "count": 1000
                        },
                        {
                            "year": 2017,
                            "month": 8,
                            "count": 880
                        },
                        {
                            "year": 2017,
                            "month": 7,
                            "count": 880
                        },
                        {
                            "year": 2017,
                            "month": 6,
                            "count": 590
                        },
                        {
                            "year": 2017,
                            "month": 5,
                            "count": 880
                        },
                        {
                            "year": 2017,
                            "month": 4,
                            "count": 720
                        },
                        {
                            "year": 2017,
                            "month": 3,
                            "count": 1000
                        },
                        {
                            "year": 2017,
                            "month": 2,
                            "count": 1000
                        },
                        {
                            "year": 2017,
                            "month": 1,
                            "count": 880
                        }
                    ]
                }  
            ]
        }
    ]
}

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

Description of the fields for sending a request:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
post_id string the index in the array received in the POST request
status string results of this task setting
“ok” – success
“error” – error
if status=“error”, check the error array for more details
results array results array of tasks setting
      language string language
      loc_id integer search engine location id
      key string keyword
keyword is returned decoded %## (plus symbol ‘+’ is decoded to a space character)
      cmp float competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Google Ads data and can be between 0 and 1 (inclusive).
if there is no data, then the value is null
      cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is null
      sv integer the average annual search volume rate
represents the (approximate) number of searches for the keyword on google.com or google.com and partners, depending on the user’s targeting
if there is no data, then the value is null
      categories array product and service categories
you can download the full list of possible categories
      ms array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is null


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
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Keywords for Category


This option will select keywords for the specified product category. In addition to the result, you will also receive a search volume for the last month, search volume trend for the last year (that allows estimating search volume dynamics), current cost-per-click and competition level for paid search.

There are two methods to retrieve data: Live and Delayed

Live data retrieving fits perfectly in those cases if your app functionality implies supplying users with data in real-time. Using this method, you will get results within 30 seconds after the task was posted.

If you have requests that don’t demand to retrieve the data in real-time, then the delayed queue is the best solution for you. Set a task and retrieve results when our system collects them. On average it takes 15-30 minutes to receive results.

You can also check the update status of keywords search volume returned by Google API using Get AdWords Status.

The updated data for this method is available starting from the 15th of a month till its end.

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

Live Data

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');

    //You can download the list of categories by: https://developers.google.com/adwords/api/docs/appendix/productsservices.csv
    $post_array[] = array(
    "language" => "en",
    "loc_name_canonical"=> "United States",
    "category_id" => 13895
    );

    $kw_post_result = $client->post('v2/kwrd_for_category', array('data' => $post_array));
    print_r($kw_post_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";
    exit();
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "task_id": 40356871,
    "results_time": "7.7805 sec.",
    "results_count": 700,
    "results": [
        {
            "loc_id": 2840,
            "language": "en",
            "key": "polygon",
            "cmp": 0.0023641022857323795,
            "cpc": 0.76973,
            "sv": 201000,
            "categories": [
                10273,
                10019,
                10885,
                13605,
                13895,
                11368,
                10121,
                11915,
                13388,
                13615,
                10004,
                10645,
                10168,
                10013,
                10014
            ],
            "ms": [
                {
                    "year": 2018,
                    "month": 5,
                    "count": 246000
                },
                {
                    "year": 2018,
                    "month": 4,
                    "count": 301000
                },
                {
                    "year": 2018,
                    "month": 3,
                    "count": 246000
                },
                {
                    "year": 2018,
                    "month": 2,
                    "count": 201000
                },
                {
                    "year": 2018,
                    "month": 1,
                    "count": 201000
                },
                {
                    "year": 2017,
                    "month": 12,
                    "count": 165000
                },
                {
                    "year": 2017,
                    "month": 11,
                    "count": 165000
                },
                {
                    "year": 2017,
                    "month": 10,
                    "count": 165000
                },
                {
                    "year": 2017,
                    "month": 9,
                    "count": 165000
                },
                {
                    "year": 2017,
                    "month": 8,
                    "count": 165000
                },
                {
                    "year": 2017,
                    "month": 7,
                    "count": 110000
                },
                {
                    "year": 2017,
                    "month": 6,
                    "count": 165000
                }
            ]
        },
        {
            "loc_id": 2840,
            "language": "en",
            "key": "norco",
            "cmp": 0.013728871081630123,
            "cpc": 1.27937,
            "sv": 165000,
            "categories": [
                11744,
                13605,
                10085,
                12902,
                13895,
                10121,
                10089,
                11915,
                13615,
                10645,
                10486,
                10011,
                11773,
                10014
            ],
            "ms": [
                {
                    "year": 2018,
                    "month": 5,
                    "count": 165000
                },
                {
                    "year": 2018,
                    "month": 4,
                    "count": 165000
                },
                {
                    "year": 2018,
                    "month": 3,
                    "count": 165000
                },
                {
                    "year": 2018,
                    "month": 2,
                    "count": 165000
                },
                {
                    "year": 2018,
                    "month": 1,
                    "count": 165000
                },
                {
                    "year": 2017,
                    "month": 12,
                    "count": 165000
                },
                {
                    "year": 2017,
                    "month": 11,
                    "count": 165000
                },
                {
                    "year": 2017,
                    "month": 10,
                    "count": 165000
                },
                {
                    "year": 2017,
                    "month": 9,
                    "count": 165000
                },
                {
                    "year": 2017,
                    "month": 8,
                    "count": 165000
                },
                {
                    "year": 2017,
                    "month": 7,
                    "count": 165000
                },
                {
                    "year": 2017,
                    "month": 6,
                    "count": 165000
                }
            ]
        },

        {
            "loc_id": 2840,
            "language": "en",
            "key": "murwood",
            "cmp": 0.0066137566137566125,
            "cpc": 0,
            "sv": 210,
            "categories": [
                10645,
                13605,
                13895,
                10121,
                11915,
                10014,
                13615
            ],
            "ms": [
                {
                    "year": 2018,
                    "month": 5,
                    "count": 210
                },
                {
                    "year": 2018,
                    "month": 4,
                    "count": 140
                },
                {
                    "year": 2018,
                    "month": 3,
                    "count": 210
                },
                {
                    "year": 2018,
                    "month": 2,
                    "count": 170
                },
                {
                    "year": 2018,
                    "month": 1,
                    "count": 210
                },
                {
                    "year": 2017,
                    "month": 12,
                    "count": 170
                },
                {
                    "year": 2017,
                    "month": 11,
                    "count": 170
                },
                {
                    "year": 2017,
                    "month": 10,
                    "count": 170
                },
                {
                    "year": 2017,
                    "month": 9,
                    "count": 260
                },
                {
                    "year": 2017,
                    "month": 8,
                    "count": 260
                },
                {
                    "year": 2017,
                    "month": 7,
                    "count": 170
                },
                {
                    "year": 2017,
                    "month": 6,
                    "count": 210
                }
            ]
        }
    ]
}

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent through POST method passing a tasks array. The data should be specified in the data field of this POST array. We recommend to send up to 100 tasks at a time. Each array element has the following structure:

Field name Type Description
category_id integer category ID
required field
you can download the list of categories
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
language string language
optional field
can have the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting
sort_by string results sorting column
optional field
can have the following values: “sv”, “relevance”
default value: “sv”
keys_negative array negative keywords array
optional field
These keywords will be ignored in the results array
You can specify a maximum of 200 elements


As a response from the API server, you will receive a JSON array with data on the selected keywords in the results field. The maximum amount of the selected keywords is 700. The results array is returned according to the sorting field sv.

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
task_id integer unique task identifier in our system (UInt64)
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array
            language string language
            loc_id integer search engine location id
            key string keyword
            cmp float competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Google Ads data and can be between 0 and 1 (inclusive).
if there is no data, then the value is null
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is null
            sv integer the average annual search volume rate
represents the (approximate) number of searches for the keyword on google.com or google.com and partners, depending on the user’s targeting
if there is no data, then the value is null
            categories array product and service categories
you can download the full list of possible categories
            ms array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is null


Possible errors codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
500 “RateExceededError” – occurs when our service exceeds the Queries Per Second (QPS) limit set by Google API. Any service that works with Google API has this limit. We are working on expanding the limits. More details about Google API limits can be found here: developers.google.com – docs/rate-limits.We recommend to process these errors (just like any other errors) and set the next task in 30 seconds if such error occurs.

Set Task

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();
$post_array["your post_id parameter here"] = array( 
    "language" => "en",
    "loc_name_canonical"=> "United States",
    "category_id" => 13895,
    "pingback_url" => 'https://your-server.com/your_pingback_url.php?task_id=$task_id&post_id=$post_id'
);

if (count($post_array) > 0) {
    try {
        $task_post_result = $client->post('/v2/kwrd_for_category_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.0784 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "your post_id parameter here",
            "task_id": 21942865468,
            "status": "ok"
        }
    ]
}

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent through the POST method passing a tasks array. The data should be specified in the data field of this POST array. We recommend to send up to 100 tasks at a time.

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

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

Each array element has the following structure:

Field name Type Description
category_id integer category ID
required field
you can download the list of categories
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
language string language
optional field
can have the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting
sort_by string results sorting column
optional field
can have the following values: “sv”, “relevance”
default value: “sv”
keys_negative array negative keywords array
optional field
These keywords will be ignored in the results array
You can specify a maximum of 200 keywords
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 Results by task_id 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 an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            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


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
404 “not found or not enough data: location” – you have specified a nonexistent loc_id, or the location for the search engine according to your loc_name_canonical wasn’t found
404 “‘data’ field structure is invalid” – specify the parameters to set a task
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_for_category_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_for_category_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.0974 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 219463558,
            "post_id": "your post_id parameter here",
            "status": "ok"
        }
    ]
}

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

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

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            status string result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details


Possible error codes:

Error Code Meaning
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_for_category_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_for_category_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/kwrd_for_category_tasks_get/$task_id
            $kwrd_for_category_result = $client->get('v2/kwrd_for_category_tasks_get/'.$tasks_get_row["task_id"]);
            print_r($kwrd_for_category_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.0395 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 40389413,
            "post_id": 49491179,
            "status": "ok",
            "result": [
                {
                    "loc_id": 2840,
                    "language": "en",
                    "key": "polygon",
                    "cmp": 0.0023641022857323795,
                    "cpc": 0.76973,
                    "sv": 201000,
                    "categories": [
                        10273,
                        10019,
                        10885,
                        13605,
                        13895,
                        11368,
                        10121,
                        11915,
                        13388,
                        13615,
                        10004,
                        10645,
                        10168,
                        10013,
                        10014
                    ],
                    "ms": [
                        {
                            "year": 2018,
                            "month": 5,
                            "count": 246000
                        },
                        {
                            "year": 2018,
                            "month": 4,
                            "count": 301000
                        },
                        {
                            "year": 2018,
                            "month": 3,
                            "count": 246000
                        },
                        {
                            "year": 2018,
                            "month": 2,
                            "count": 201000
                        },
                        {
                            "year": 2018,
                            "month": 1,
                            "count": 201000
                        },
                        {
                            "year": 2017,
                            "month": 12,
                            "count": 165000
                        },
                        {
                            "year": 2017,
                            "month": 11,
                            "count": 165000
                        },
                        {
                            "year": 2017,
                            "month": 10,
                            "count": 165000
                        },
                        {
                            "year": 2017,
                            "month": 9,
                            "count": 165000
                        },
                        {
                            "year": 2017,
                            "month": 8,
                            "count": 165000
                        },
                        {
                            "year": 2017,
                            "month": 7,
                            "count": 110000
                        },
                        {
                            "year": 2017,
                            "month": 6,
                            "count": 165000
                        }
                    ]
                },
                {
                    "loc_id": 2840,
                    "language": "en",
                    "key": "norco",
                    "cmp": 0.013728871081630123,
                    "cpc": 1.27937,
                    "sv": 165000,
                    "categories": [
                        11744,
                        13605,
                        10085,
                        12902,
                        13895,
                        10121,
                        10089,
                        11915,
                        13615,
                        10645,
                        10486,
                        10011,
                        11773,
                        10014
                    ],
                    "ms": [
                        {
                            "year": 2018,
                            "month": 5,
                            "count": 165000
                        },
                        {
                            "year": 2018,
                            "month": 4,
                            "count": 165000
                        },
                        {
                            "year": 2018,
                            "month": 3,
                            "count": 165000
                        },
                        {
                            "year": 2018,
                            "month": 2,
                            "count": 165000
                        },
                        {
                            "year": 2018,
                            "month": 1,
                            "count": 165000
                        },
                        {
                            "year": 2017,
                            "month": 12,
                            "count": 165000
                        },
                        {
                            "year": 2017,
                            "month": 11,
                            "count": 165000
                        },
                        {
                            "year": 2017,
                            "month": 10,
                            "count": 165000
                        },
                        {
                            "year": 2017,
                            "month": 9,
                            "count": 165000
                        },
                        {
                            "year": 2017,
                            "month": 8,
                            "count": 165000
                        },
                        {
                            "year": 2017,
                            "month": 7,
                            "count": 165000
                        },
                        {
                            "year": 2017,
                            "month": 6,
                            "count": 165000
                        }
                    ]
                },
                {
                    "loc_id": 2840,
                    "language": "en",
                    "key": "murwood",
                    "cmp": 0.0066137566137566125,
                    "cpc": 0,
                    "sv": 210,
                    "categories": [
                        10645,
                        13605,
                        13895,
                        10121,
                        11915,
                        10014,
                        13615
                    ],
                    "ms": [
                        {
                            "year": 2018,
                            "month": 5,
                            "count": 210
                        },
                        {
                            "year": 2018,
                            "month": 4,
                            "count": 140
                        },
                        {
                            "year": 2018,
                            "month": 3,
                            "count": 210
                        },
                        {
                            "year": 2018,
                            "month": 2,
                            "count": 170
                        },
                        {
                            "year": 2018,
                            "month": 1,
                            "count": 210
                        },
                        {
                            "year": 2017,
                            "month": 12,
                            "count": 170
                        },
                        {
                            "year": 2017,
                            "month": 11,
                            "count": 170
                        },
                        {
                            "year": 2017,
                            "month": 10,
                            "count": 170
                        },
                        {
                            "year": 2017,
                            "month": 9,
                            "count": 260
                        },
                        {
                            "year": 2017,
                            "month": 8,
                            "count": 260
                        },
                        {
                            "year": 2017,
                            "month": 7,
                            "count": 170
                        },
                        {
                            "year": 2017,
                            "month": 6,
                            "count": 210
                        }
                    ]
                }
            ]
        }
    ]
}

As a response of the API server, you will receive an array in the results field containing the list of completed results. Each array element has the following structure:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
task_id integer unique task identifier in our system (UInt64)
you will be able to use it within30 days to request the results of the task at any time
post_id string the index in the array received in the POST request
status string result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
results array results array of tasks setting
      language string language
      loc_id integer search engine location id
      key string keyword
keyword is returned decoded %## (plus symbol ‘+’ is decoded to a space character)
            cmp float competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Google Ads data and can be between 0 and 1 (inclusive).
if there is no data, then the value is null
      cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is null
      sv integer the average annual search volume rate
represents the (approximate) number of searches for the keyword on google.com or google.com and partners, depending on the user’s targeting
if there is no data, then the value is null
      categories array product and service categories
you can download the full list of possible categories
      ms array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is null


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
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Ads Traffic for Keywords


You can receive a set of stats for daily impressions, CPC and clicks estimation. This data is really useful for estimating real demand for a specific keyword, as it is much more accurate than the regular search volume information, which shows the broad match estimation for a group of similar keywords.

There are two methods to retrieve data: Live and Delayed

Live data retrieving fits perfectly in case your app functionality implies real-time data providing. With this method, you will get results within 30 seconds after the task is posted.

If you have requests that don’t require real-time data retrieval, then the delayed queue is the best solution for you. Set a task and retrieve the results when our system collects them. On average it takes 15-30 minutes to receive the results.

You can also check the update status of keywords search volume returned by Google API using Get AdWords Status.

The updated data for this method is available starting from the 15th day of a month till its end.

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

Live Data

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');

    $post_array[] = array(
    "language" => "en",
    "loc_name_canonical" => "United States",
    "bid" => 100.00,
    "match" => "exact",
    "keys" => array("seo marketing")
    );

    $kw_post_result = $client->post('v2/kwrd_ad_traffic_by_keywords', array('data' => $post_array));
    print_r($kw_post_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";
    exit();
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "task_id": 466312280,
    "results_time": "6.9194 sec.",
    "results_count": 1,
    "results": [
        {
            "seo marketing": {
                "language": "en",
                "loc_id": 2840,
                "bid": 100,
                "key": "seo marketing",
                "match": "exact",
                "ad_position_min": 1.11,
                "ad_position_max": 1,
                "ad_position_average": 1.06,
                "cpc_min": 13.46,
                "cpc_max": 16.45,
                "cpc_average": 14.95,
                "daily_impressions_min": 304.23,
                "daily_impressions_max": 371.84,
                "daily_impressions_average": 338.03,
                "daily_clicks_min": 4.59,
                "daily_clicks_max": 5.61,
                "daily_clicks_average": 5.1,
                "daily_cost_min": 67.61,
                "daily_cost_max": 82.64,
                "daily_cost_average": 75.12
            }
        }
    ]
}

You will get information for every single keyword in an array.

You can send up to 2500 keywords in one keys array. Our system will charge credits per request. No matter what number of keywords an array has, the price for 1 or 2500 keywords will be the same.

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent through the POST method passing a tasks array. The data should be specified in the data field of this POST array. Each array element has the following structure:

Field name Type Description
keys array keywords array
required field
maximum 2500 keywords can be specified
You can specify a maximum of 2500 keywords
each keyword can contain a maximum of 80 characters, each keyword phrase can contain a maximum of ten words
bid float the maximum custom bid
required field
The collected data will be based on this value. It stands for the price you are willing to pay for an ad. The higher value you specify, the higher positions and price you will get.
match string keywords match-type
required field
can have the following values: “exact”, “broad”, “phrase”
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
language string language
optional field
can have the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting


As a response from the API server, you will receive a JSON array with data for the selected keywords in the results field.

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
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
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      language string language
      loc_id integer search engine location id
      bid float the maximum custom bid
      key string keyword
      match string keywords match-type
      ad_position_min float the minimum ads position
represents the minimum position of the advertisement
if there is no data, then the value is null
      ad_position_max float the maximum ads position
represents the maximum position of the advertisement
if there is no data, then the value is null
      ad_position_average float the average ads position
represents the average position of the advertisement
if there is no data, then the value is null
      cpc_min float the minimum value of cost-per-click
represents the minimum cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
      cpc_max float the maximum value of cost-per-click
represents the maximum cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
      cpc_average float the average value of cost-per-click
represents the average cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
      daily_impressions_min float the minimum daily impressions value
represents the minimum number of daily impressions of the advertisement
if there is no data, then the value is null
      daily_impressions_max float the maximum daily impressions value
represents the maximum number of daily impressions of the advertisement
if there is no data, then the value is null
      daily_impressions_average float the average daily impressions value
represents the average number of daily impressions of the advertisement
if there is no data, then the value is null
      daily_clicks_min float the minimum daily clicks value
represents the minimum number of daily clicks on the advertisement
if there is no data, then the value is null
      daily_clicks_max float the maximum daily clicks value
represents the maximum number of daily clicks on the advertisement
if there is no data, then the value is null
      daily_clicks_average float the average daily clicks value
represents the average number of daily clicks on the advertisement
if there is no data, then the value is null
      daily_cost_min float the minimum daily charge value
represents the minimum daily charge for the advertisement
if there is no data, then the value is null
      daily_cost_max float the maximum daily charge value
represents the maximum daily charge for the advertisement
if there is no data, then the value is null
      daily_cost_average float the average daily charge value
represents the average daily charge for the advertisement
if there is no data then the value is null


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
500 “RateExceededError” – occurs when our service exceeds the Queries Per Second (QPS) limit set by Google API. Any service that works with Google API has this limit. We are working on expanding the limits. More details about Google API limits can be found here: developers.google.com – docs/rate-limits.We recommend to process these errors (just like any other errors) and set the next task in 30 seconds if such error occurs.

Set Task

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();
$post_array["your post_id parameter here"] = array( 
    "language" => "en",
    "loc_name_canonical" => "United States",
    "bid" => 999.0,
    "match" => "exact",
    "keys" => array(
        "online rank checker",
        "best seo"
    ),
    "pingback_url" => 'https://your-server.com/your_pingback_url.php?task_id=$task_id&post_id=$post_id'
);

if (count($post_array) > 0) {
    try {
        $task_post_result = $client->post('/v2/kwrd_ad_traffic_by_keywords_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.0679 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "your post_id parameter here",
            "task_id": 219686,
            "status": "ok"
        }
    ]
}

You can send up to 2500 keywords in one keys array. Our system will charge credits per request, no matter what number of keywords an array has, the price for 1 or 2500 keywords will be the same.

You will get information for every single keyword in an array.

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent by POST method passing tasks array. The data should be specified in the data field of this POST array. We recommend to send up to 100 tasks at a time.

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

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

Each array element has the following structure:

Field name Type Description
keys array keywords array
required field
You can specify a maximum of 2500 keywords
each keyword can contain a maximum of 80 characters, each keyword phrase can contain a maximum of ten words
bid float the maximum custom bid
required field
The collected data will be based on this value. It stands for the price you are willing to pay for an ad. The higher value you specify, the higher positions and price you will get.
match string keywords match-type
required field
can have the following values: “exact”, “broad”, “phrase”
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
language string language
optional field
can have the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting
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 Results by task_id 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 an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            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


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
404 “not found or not enough data: location” – you have specified a nonexistent loc_id, or the location for the search engine according to your loc_name_canonical wasn’t found
404 “‘data’ field structure is invalid” – specify the parameters to set a task
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_ad_traffic_by_keywords_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_ad_traffic_by_keywords_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.0795 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 219737,
            "post_id": "your post_id parameter here",
            "status": "ok"
        }
    ]
}

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

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

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            status string result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details


Possible error codes:

Error Code Meaning
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_ad_traffic_by_keywords_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_ad_traffic_by_keywords_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/kwrd_ad_traffic_by_keywords_tasks_get/$task_id
            $kwrd_ad_traffic_by_keywords_result = $client->get('v2/kwrd_ad_traffic_by_keywords_tasks_get/'.$tasks_get_row["task_id"]);
            print_r($kwrd_ad_traffic_by_keywords_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.0814 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 219737,
            "post_id": "your post_id parameter here",
            "status": "ok",
            "result": [
                {
                    "online rank checker": {
                        "language": "en",
                        "loc_id": 2840,
                        "bid": 999,
                        "key": "online rank checker",
                        "match": "exact",
                        "ad_position_min": 1.11,
                        "ad_position_max": 1,
                        "ad_position_average": 1.06,
                        "cpc_min": 10.62,
                        "cpc_max": 12.98,
                        "cpc_average": 11.8,
                        "daily_impressions_min": 5.06,
                        "daily_impressions_max": 6.18,
                        "daily_impressions_average": 5.62,
                        "daily_clicks_min": 0.16,
                        "daily_clicks_max": 0.19,
                        "daily_clicks_average": 0.17,
                        "daily_cost_min": 1.89,
                        "daily_cost_max": 2.31,
                        "daily_cost_average": 2.1
                    },
                    "best seo": {
                        "language": "en",
                        "loc_id": 2840,
                        "bid": 999,
                        "key": "best seo",
                        "match": "exact",
                        "ad_position_min": 1.11,
                        "ad_position_max": 1,
                        "ad_position_average": 1.06,
                        "cpc_min": 8.5,
                        "cpc_max": 10.38,
                        "cpc_average": 9.44,
                        "daily_impressions_min": 20.53,
                        "daily_impressions_max": 25.09,
                        "daily_impressions_average": 22.81,
                        "daily_clicks_min": 0.36,
                        "daily_clicks_max": 0.44,
                        "daily_clicks_average": 0.4,
                        "daily_cost_min": 3.48,
                        "daily_cost_max": 4.25,
                        "daily_cost_average": 3.86
                    }
                }
            ]
        }
    ]
}

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
post_id string the index in the array received in the POST request
status string results of this task setting
“ok” – success
“error” – error
if status=“error”, check the error array for more details
results array results array of tasks setting
      language string language
      loc_id integer search engine location id
      bid float the maximum custom bid
      key string keyword
      match string keywords match-type
      ad_position_min float the minimum ads position
represents the minimum position of the advertisement
if there is no data, then the value is null
      ad_position_max float the maximum ads position
represents the maximum position of the advertisement
if there is no data, then the value is null
      ad_position_average float the average ads position
represents the average position of the advertisement
if there is no data, then the value is null
      cpc_min float the minimum value of cost-per-click
represents the minimum cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
      cpc_max float the maximum value of cost-per-click
represents the maximum cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
      cpc_average float the average value of cost-per-click
represents the average cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
      daily_impressions_min float the minimum daily impressions value
represents the minimum number of daily impressions of the advertisement
if there is no data, then the value is null
      daily_impressions_max float the maximum daily impressions value
represents the maximum number of daily impressions of the advertisement
if there is no data, then the value is null
      daily_impressions_average float the average daily impressions value
represents the average number of daily impressions of the advertisement
if there is no data, then the value is null
      daily_clicks_min float the minimum daily clicks value
represents the minimum number of daily clicks on the advertisement
if there is no data, then the value is null
      daily_clicks_max float the maximum daily clicks value
represents the maximum number of daily clicks on the advertisement
if there is no data, then the value is null
      daily_clicks_average float the average daily clicks value
represents the average number of daily clicks on the advertisement
if there is no data, then the value is null
      daily_cost_min float the minimum daily charge value
represents the minimum daily charge for the advertisement
if there is no data, then the value is null
      daily_cost_max float the maximum daily charge value
represents the maximum daily charge for the advertisement
if there is no data, then the value is null
      daily_cost_average float the average daily charge value
represents the average daily charge for the advertisement
if there is no data then the value is null


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
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Ads Traffic by Platforms


You can receive a set of stats for a group of keywords and get daily impressions, CPC and clicks estimation for the following platforms: desktop/mobile/tablet.

Unlike the kwrd_ad_traffic_by_keywords method where you get information for each keyword in an array separately, using kwrd_ad_traffic_by_platforms you will get overall information for a group of keywords you send.

There are two methods to retrieve data: Live and Delayed

Live data retrieving fits perfectly in case your app functionality implies real-time data providing. With this method, you will get results within 30 seconds after the task is posted.

If you have requests that don’t require real-time data retrieval, then the delayed queue is the best solution for you. Set a task and retrieve the results when our system collects them. On average it takes 15-30 minutes to receive the results.

You can also check the update status of keywords search volume returned by Google API using Get AdWords Status.

The updated data for this method is available starting from the 15th day of a month till its end.

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

Live Data

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');

    $post_array[] = array(
    "language" => "en",
    "loc_name_canonical" => "United States",
    "bid" => 100.00,
    "match" => "exact",
    "keys" => array("seo marketing")
    );

    $kw_post_result = $client->post('v2/kwrd_ad_traffic_by_platforms', array('data' => $post_array));
    print_r($kw_post_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";
    exit();
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "task_id": 466313860,
    "results_time": "5.6141 sec.",
    "results_count": 1,
    "results": [
        {
            "desktop": {
                "language": "en",
                "loc_id": 2840,
                "bid": 100,
                "keys": [
                    "seo marketing"
                ],
                "match": "exact",
                "ad_position_min": 1.11,
                "ad_position_max": 1,
                "ad_position_average": 1.06,
                "cpc_min": 13.36,
                "cpc_max": 16.33,
                "cpc_average": 14.84,
                "daily_impressions_min": 181.51,
                "daily_impressions_max": 221.84,
                "daily_impressions_average": 201.67,
                "daily_clicks_min": 2.74,
                "daily_clicks_max": 3.35,
                "daily_clicks_average": 3.05,
                "daily_cost_min": 40.09,
                "daily_cost_max": 49,
                "daily_cost_average": 44.54
            },
            "mobile": {
                "language": "en",
                "loc_id": 2840,
                "bid": 100,
                "keys": [
                    "seo marketing"
                ],
                "match": "exact",
                "ad_position_min": 1.11,
                "ad_position_max": 1,
                "ad_position_average": 1.06,
                "cpc_min": 13.86,
                "cpc_max": 16.94,
                "cpc_average": 15.4,
                "daily_impressions_min": 112.45,
                "daily_impressions_max": 137.44,
                "daily_impressions_average": 124.94,
                "daily_clicks_min": 1.67,
                "daily_clicks_max": 2.05,
                "daily_clicks_average": 1.86,
                "daily_cost_min": 25.38,
                "daily_cost_max": 31.02,
                "daily_cost_average": 28.2
            },
            "tablet": {
                "language": "en",
                "loc_id": 2840,
                "bid": 100,
                "keys": [
                    "seo marketing"
                ],
                "match": "exact",
                "ad_position_min": 1.11,
                "ad_position_max": 1,
                "ad_position_average": 1.06,
                "cpc_min": 11.75,
                "cpc_max": 14.36,
                "cpc_average": 13.05,
                "daily_impressions_min": 10.08,
                "daily_impressions_max": 12.32,
                "daily_impressions_average": 11.2,
                "daily_clicks_min": 0.2,
                "daily_clicks_max": 0.25,
                "daily_clicks_average": 0.22,
                "daily_cost_min": 2.6,
                "daily_cost_max": 3.18,
                "daily_cost_average": 2.89
            }
        }
    ]
}

You can send up to 2500 keywords in one keys array. Our system will charge credits per request. No matter what number of keywords an array has, the price for 1 or 2500 keywords will be the same.

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent through the POST method passing a tasks array. The data should be specified in the data field of this POST array. Each array element has the following structure:

Field name Type Description
keys array keywords array
required field
You can specify a maximum of 2500 keywords
each keyword should contain a maximum of 80 characters, each keyword phrase should contain a maximum of ten words
bid float the maximum custom bid
required field
The collected data will be based on this value. It stands for the price you are willing to pay for an ad. The higher value you specify, the higher positions and price you will get.
match string keywords match-type
required field
can have the following values: “exact”, “broad”, “phrase”
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
language string language
optional field
can have the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting


As a response of the API server, you will receive a JSON array containing data for the selected keywords in the results field.

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
task_id integer unique task identifier in our system (UInt64)
results_time string execution time, seconds
results_count integer the number of elements in the results array
results array results array
      desktop array results for desktop
         language string language
         loc_id integer search engine location id
         bid float maximum custom bid
         key string keyword
         match string keywords match-type
         ad_position_min float the minimum ads position
represents the minimum advertising position
if there is no data then the value is null
         ad_position_max float the maximum ads position
represents the maximum advertising position
if there is no data then the value is null
         ad_position_average float the average ads position
represents the average advertising position
if there is no data then the value is null
         cpc_min float the minimum value of cost-per-click
represents the minimum cost per click (USD) historically paid for the keyword
if there is no data then the value is null
         cpc_max float the maximum value of cost-per-click
represents the maximum cost per click (USD) historically paid for the keyword
if there is no data then the value is null
         cpc_average float the average value of cost-per-click
represents the average cost per click (USD) historically paid for the keyword
if there is no data then the value is null
         daily_impressions_min float the minimum daily impressions value
represents the minimum number of advertising daily impression
if there is no data then the value is null
         daily_impressions_max float the maximum daily impressions value
represents the maximum number of advertising daily impressions
if there is no data then the value is null
         daily_impressions_average float the average daily impressions value
represents the average number of advertising daily impressions
if there is no data then the value is null
         daily_clicks_min float the minimum daily clicks value
represents the minimum number of advertising daily clicks
if there is no data then the value is null
         daily_clicks_max float the maximum daily clicks value
represents the maximum number of advertising daily clicks
if there is no data then the value is null
         daily_clicks_average float the average daily clicks value
represents the average number of advertising daily clicks
if there is no data then the value is null
         daily_cost_min float the minimum daily charge value
represents the minimum advertising daily charge
if there is no data then the value is null
         daily_cost_max float the maximum daily charge value
represents the maximum advertising daily charge
if there is no data then the value is null
         daily_cost_average float the average daily charge value
represents the average advertising daily charge
if there is no data then the value is null
      mobile array results for mobile
         language string language
         loc_id integer search engine location id
         bid float maximum custom bid
         key string keyword
         match string keywords match-type
         ad_position_min float the minimum ads position
represents the minimum position of the advertisement
if there is no data, then the value is null
         ad_position_max float the maximum ads position
represents the maximum position of the advertisement
if there is no data, then the value is null
         ad_position_average float the average ads position
represents the average position of the advertisement
if there is no data, then the value is null
         cpc_min float the minimum value of cost-per-click
represents the minimum cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
         cpc_max float the maximum value of cost-per-click
represents the maximum cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
         cpc_average float the average value of cost-per-click
represents the average cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
         daily_impressions_min float the minimum daily impressions value
represents the minimum number of daily impressions of the advertisement
if there is no data, then the value is null
         daily_impressions_max float the maximum daily impressions value
represents the maximum number of daily impressions of the advertisement
if there is no data, then the value is null
         daily_impressions_average float the average daily impressions value
represents the average number of daily impressions of the advertisement
if there is no data, then the value is null
         daily_clicks_min float the minimum daily clicks value
represents the minimum number of daily clicks on the advertisement
if there is no data, then the value is null
         daily_clicks_max float the maximum daily clicks value
represents the maximum number of daily clicks on the advertisement
if there is no data, then the value is null
         daily_clicks_average float the average daily clicks value
represents the average number of daily clicks on the advertisement
if there is no data, then the value is null
         daily_cost_min float the minimum daily charge value
represents the minimum daily charge for the advertisement
if there is no data, then the value is null
         daily_cost_max float the maximum daily charge value
represents the maximum daily charge for the advertisement
if there is no data, then the value is null
         daily_cost_average float the average daily charge value
represents the average daily charge for the advertisement
if there is no data then the value is null
      tablet array results for tablet
         language string language
         loc_id integer search engine location id
         bid float maximum custom bid
         key string keyword
         match string keywords match-type
         ad_position_min float the minimum ads position
represents the minimum position of the advertisement
if there is no data, then the value is null
         ad_position_max float the maximum ads position
represents the maximum position of the advertisement
if there is no data, then the value is null
         ad_position_average float the average ads position
represents the average position of the advertisement
if there is no data, then the value is null
         cpc_min float the minimum value of cost-per-click
represents the minimum cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
         cpc_max float the maximum value of cost-per-click
represents the maximum cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
         cpc_average float the average value of cost-per-click
represents the average cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
         daily_impressions_min float the minimum daily impressions value
represents the minimum number of daily impressions of the advertisement
if there is no data, then the value is null
         daily_impressions_max float the maximum daily impressions value
represents the maximum number of daily impressions of the advertisement
if there is no data, then the value is null
         daily_impressions_average float the average daily impressions value
represents the average number of daily impressions of the advertisement
if there is no data, then the value is null
         daily_clicks_min float the minimum daily clicks value
represents the minimum number of daily clicks on the advertisement
if there is no data, then the value is null
         daily_clicks_max float the maximum daily clicks value
represents the maximum number of daily clicks on the advertisement
if there is no data, then the value is null
         daily_clicks_average float the average daily clicks value
represents the average number of daily clicks on the advertisement
if there is no data, then the value is null
         daily_cost_min float the minimum daily charge value
represents the minimum daily charge for the advertisement
if there is no data, then the value is null
         daily_cost_max float the maximum daily charge value
represents the maximum daily charge for the advertisement
if there is no data, then the value is null
         daily_cost_average float the average daily charge value
represents the average daily charge for the advertisement
if there is no data, then the value is null


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
500 “RateExceededError” – occurs when our service exceeds the Queries Per Second (QPS) limit set by Google API. Any service that works with Google API has this limit. We are working on expanding the limits. More details about Google API limits can be found here: developers.google.com – docs/rate-limits.We recommend to process these errors (just like any other errors) and set the next task in 30 seconds if such error occurs.

Set Task

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();
$post_array["your post_id parameter here"] = array( 
    "language" => "en",
    "loc_name_canonical" => "United States",
    "bid" => 999.0,
    "match" => "exact",
    "keys" => array(
        "online rank checker",
        "best seo"
    ),
    "pingback_url" => 'https://your-server.com/your_pingback_url.php?task_id=$task_id&post_id=$post_id'
);

if (count($post_array) > 0) {
    try {
        $task_post_result = $client->post('/v2/kwrd_ad_traffic_by_platforms_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.0888 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "your post_id parameter here",
            "task_id": 219772,
            "status": "ok"
        }
    ]
}

You can send up to 2500 keywords in one keys array. Our system will charge credits per request. No matter what number of keywords an array has, the price for 1 or 2500 keywords will be the same.

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent through the POST method passing a tasks array. The data should be specified in the data field of this POST array. We recommend to send up to 100 tasks at a time.

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

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

Description of the fields for setting a task:

Field name Type Description
keys array array of keywords
required field
You can specify a maximum of 2500 keywords
each keyword should contain a maximum of 80 characters, each keyword phrase should contain a maximum of ten words
bid float the maximum custom bid
required field
The collected data will be based on this value. It stands for the price you are willing to pay for an ad. The higher value you specify, the higher positions and price you will get.
match string keywords match-type
required field
can have the following values: “exact”, “broad”, “phrase”
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
also when the information about set task is returned you will get the loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
Please note that the ‘Postal Code’ is not supported in Keywords Data API.
language string language
optional field
can have the following values: “ar”, “bn”, “bg”, “ca”, “zh_cn”, “zh_tw”, “hr”, “cs”, “da”, “nl”, “en”, “et”, “tl”, “fi”, “fr”, “de”, “el”, “iw”, “hi”, “hu”, “is”, “id”, “it”, “ja”, “ko”, “lv”, “lt”, “ms”, “no”, “fa”, “pl”, “pt”, “ro”, “ru”, “sr”, “sk”, “sl”, “es”, “sv”, “te”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API – Languages available for targeting
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 Results by task_id 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 an information appropriate to the set tasks.

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            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


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field
404 “not found or not enough data: location” – you have specified a nonexistent loc_id, or the location for the search engine according to your loc_name_canonical wasn’t found
404 “‘data’ field structure is invalid” – specify the parameters to set a task
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_ad_traffic_by_platforms_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_ad_traffic_by_platforms_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.0795 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 219737,
            "post_id": "your post_id parameter here",
            "status": "ok"
        }
    ]
}

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

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

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
            code integer error code
            message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within30 days to request the results of the task at any time
            post_id string the index in the array received in the POST request
            status string result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details


Possible error codes:

Error Code Meaning
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Get 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/kwrd_ad_traffic_by_platforms_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_ad_traffic_by_platforms_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/kwrd_ad_traffic_by_platforms_tasks_get/$task_id
            $kwrd_ad_traffic_by_platforms_result = $client->get('v2/kwrd_ad_traffic_by_platforms_tasks_get/'.$tasks_get_row["task_id"]);
            print_r($kwrd_ad_traffic_by_platforms_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.0781 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 219772,
            "post_id": "your post_id parameter here",
            "status": "ok",
            "result": [
                {
                    "desktop": {
                        "language": "en",
                        "loc_id": 2840,
                        "bid": 999,
                        "keys": [
                            "online rank checker",
                            "best seo"
                        ],
                        "match": "exact",
                        "ad_position_min": 1.11,
                        "ad_position_max": 1,
                        "ad_position_average": 1.06,
                        "cpc_min": 9.52,
                        "cpc_max": 11.63,
                        "cpc_average": 10.58,
                        "daily_impressions_min": 19.63,
                        "daily_impressions_max": 24,
                        "daily_impressions_average": 21.82,
                        "daily_clicks_min": 0.37,
                        "daily_clicks_max": 0.46,
                        "daily_clicks_average": 0.42,
                        "daily_cost_min": 4.06,
                        "daily_cost_max": 4.96,
                        "daily_cost_average": 4.51
                    },
                    "mobile": {
                        "language": "en",
                        "loc_id": 2840,
                        "bid": 999,
                        "keys": [
                            "online rank checker",
                            "best seo"
                        ],
                        "match": "exact",
                        "ad_position_min": 1.11,
                        "ad_position_max": 1,
                        "ad_position_average": 1.06,
                        "cpc_min": 8.69,
                        "cpc_max": 10.62,
                        "cpc_average": 9.65,
                        "daily_impressions_min": 5.06,
                        "daily_impressions_max": 6.18,
                        "daily_impressions_average": 5.62,
                        "daily_clicks_min": 0.11,
                        "daily_clicks_max": 0.13,
                        "daily_clicks_average": 0.12,
                        "daily_cost_min": 1.06,
                        "daily_cost_max": 1.3,
                        "daily_cost_average": 1.18
                    },
                    "tablet": {
                        "language": "en",
                        "loc_id": 2840,
                        "bid": 999,
                        "keys": [
                            "online rank checker",
                            "best seo"
                        ],
                        "match": "exact",
                        "ad_position_min": 1.11,
                        "ad_position_max": 1,
                        "ad_position_average": 1.06,
                        "cpc_min": 6.58,
                        "cpc_max": 8.04,
                        "cpc_average": 7.31,
                        "daily_impressions_min": 1.19,
                        "daily_impressions_max": 1.45,
                        "daily_impressions_average": 1.32,
                        "daily_clicks_min": 0.04,
                        "daily_clicks_max": 0.05,
                        "daily_clicks_average": 0.05,
                        "daily_cost_min": 0.32,
                        "daily_cost_max": 0.39,
                        "daily_cost_average": 0.36
                    }
                }
            ]
        }
    ]
}

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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within30 days to request the results of the task at any time
      post_id string the index in the array received in the POST request
      status string result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
results array results array
      desktop array results for desktop
         language string language
         loc_id integer search engine location id
         bid float maximum custom bid
         key string keyword
         match string keywords match-type
         ad_position_min float the minimum ads position
represents the minimum advertising position
if there is no data then the value is null
         ad_position_max float the maximum ads position
represents the maximum advertising position
if there is no data then the value is null
         ad_position_average float the average ads position
represents the average advertising position
if there is no data then the value is null
         cpc_min float the minimum value of cost-per-click
represents the minimum cost per click (USD) historically paid for the keyword
if there is no data then the value is null
         cpc_max float the maximum value of cost-per-click
represents the maximum cost per click (USD) historically paid for the keyword
if there is no data then the value is null
         cpc_average float the average value of cost-per-click
represents the average cost per click (USD) historically paid for the keyword
if there is no data then the value is null
         daily_impressions_min float the minimum daily impressions value
represents the minimum number of advertising daily impression
if there is no data then the value is null
         daily_impressions_max float the maximum daily impressions value
represents the maximum number of advertising daily impressions
if there is no data then the value is null
         daily_impressions_average float the average daily impressions value
represents the average number of advertising daily impressions
if there is no data then the value is null
         daily_clicks_min float the minimum daily clicks value
represents the minimum number of advertising daily clicks
if there is no data then the value is null
         daily_clicks_max float the maximum daily clicks value
represents the maximum number of advertising daily clicks
if there is no data then the value is null
         daily_clicks_average float the average daily clicks value
represents the average number of advertising daily clicks
if there is no data then the value is null
         daily_cost_min float the minimum daily charge value
represents the minimum advertising daily charge
if there is no data then the value is null
         daily_cost_max float the maximum daily charge value
represents the maximum advertising daily charge
if there is no data then the value is null
         daily_cost_average float the average daily charge value
represents the average advertising daily charge
if there is no data then the value is null
      mobile array results for mobile
         language string language
         loc_id integer search engine location id
         bid float maximum custom bid
         key string keyword
         match string keywords match-type
         ad_position_min float the minimum ads position
represents the minimum position of the advertisement
if there is no data, then the value is null
         ad_position_max float the maximum ads position
represents the maximum position of the advertisement
if there is no data, then the value is null
         ad_position_average float the average ads position
represents the average position of the advertisement
if there is no data, then the value is null
         cpc_min float the minimum value of cost-per-click
represents the minimum cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
         cpc_max float the maximum value of cost-per-click
represents the maximum cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
         cpc_average float the average value of cost-per-click
represents the average cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
         daily_impressions_min float the minimum daily impressions value
represents the minimum number of daily impressions of the advertisement
if there is no data, then the value is null
         daily_impressions_max float the maximum daily impressions value
represents the maximum number of daily impressions of the advertisement
if there is no data, then the value is null
         daily_impressions_average float the average daily impressions value
represents the average number of daily impressions of the advertisement
if there is no data, then the value is null
         daily_clicks_min float the minimum daily clicks value
represents the minimum number of daily clicks on the advertisement
if there is no data, then the value is null
         daily_clicks_max float the maximum daily clicks value
represents the maximum number of daily clicks on the advertisement
if there is no data, then the value is null
         daily_clicks_average float the average daily clicks value
represents the average number of daily clicks on the advertisement
if there is no data, then the value is null
         daily_cost_min float the minimum daily charge value
represents the minimum daily charge for the advertisement
if there is no data, then the value is null
         daily_cost_max float the maximum daily charge value
represents the maximum daily charge for the advertisement
if there is no data, then the value is null
         daily_cost_average float the average daily charge value
represents the average daily charge for the advertisement
if there is no data then the value is null
      tablet array results for tablet
         language string language
         loc_id integer search engine location id
         bid float maximum custom bid
         key string keyword
         match string keywords match-type
         ad_position_min float the minimum ads position
represents the minimum position of the advertisement
if there is no data, then the value is null
         ad_position_max float the maximum ads position
represents the maximum position of the advertisement
if there is no data, then the value is null
         ad_position_average float the average ads position
represents the average position of the advertisement
if there is no data, then the value is null
         cpc_min float the minimum value of cost-per-click
represents the minimum cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
         cpc_max float the maximum value of cost-per-click
represents the maximum cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
         cpc_average float the average value of cost-per-click
represents the average cost per click (USD) historically paid for the keyword
if there is no data, then the value is null
         daily_impressions_min float the minimum daily impressions value
represents the minimum number of daily impressions of the advertisement
if there is no data, then the value is null
         daily_impressions_max float the maximum daily impressions value
represents the maximum number of daily impressions of the advertisement
if there is no data, then the value is null
         daily_impressions_average float the average daily impressions value
represents the average number of daily impressions of the advertisement
if there is no data, then the value is null
         daily_clicks_min float the minimum daily clicks value
represents the minimum number of daily clicks on the advertisement
if there is no data, then the value is null
         daily_clicks_max float the maximum daily clicks value
represents the maximum number of daily clicks on the advertisement
if there is no data, then the value is null
         daily_clicks_average float the average daily clicks value
represents the average number of daily clicks on the advertisement
if there is no data, then the value is null
         daily_cost_min float the minimum daily charge value
represents the minimum daily charge for the advertisement
if there is no data, then the value is null
         daily_cost_max float the maximum daily charge value
represents the maximum daily charge for the advertisement
if there is no data, then the value is null
         daily_cost_average float the average daily charge value
represents the average daily charge for the advertisement
if there is no data, then the value is null


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
500 “internal error” – some internal error. We did our best not to let this type of error ever happen.

Clickstream


Clickstream data is a sound alternative to Google Ads Keyword Planner for obtaining real search volume metrics. The data is collected via free browser extensions, plugins and software that users willingly install on their PCs. These applications request users’ permission to collect data on their activity on the web. The collected data is then aggregated from all permitted resources and can be used to calculate search volume proceeding from queries that users type in the search engines.

Bulk Clickstream Search Volume


You can get Search Volume values and trends for a bulk of keywords (up to 700) using clickstream data rather than Google Ads. This method allows getting Search Volume metrics on the keywords for which Google doesn’t return data. Bulk Clickstream Search Volume API will supply you with the average number of searches for the specified keyword in the selected search engine and location.

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');

    $post_array[] = array(
        "loc_name_canonical"=> "United States",
        "keys" => array(
            "average page rpm adsense",
            "adsense blank ads how long",
            "leads and prospects"
        )
    );

    $sv_post_result = $client->post('v2/kwrd_sv_batch_clickstream', array('data' => $post_array));
    print_r($sv_post_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";
    exit();
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "task_id": 4232369503,
    "results_time": "2.1886 sec.",
    "results_count": 3,
    "results": [
        {
            "search_engine": "google",
            "loc_id": 2840,
            "key": "leads and prospects",
            "sv": 10,
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 10
                }
            ]
        },
        {
            "search_engine": "google",
            "loc_id": 2840,
            "key": "mazda",
            "sv": 133540,
            "ms": [
                {
                    "year": 2019,
                    "month": 8,
                    "count": 129930
                },
                {
                    "year": 2019,
                    "month": 7,
                    "count": 133970
                },
                {
                    "year": 2019,
                    "month": 6,
                    "count": 131910
                },
                {
                    "year": 2019,
                    "month": 5,
                    "count": 136640
                },
                {
                    "year": 2019,
                    "month": 4,
                    "count": 140540
                },
                {
                    "year": 2019,
                    "month": 3,
                    "count": 153530
                },
                {
                    "year": 2019,
                    "month": 2,
                    "count": 131910
                },
                {
                    "year": 2019,
                    "month": 1,
                    "count": 138780
                },
                {
                    "year": 2018,
                    "month": 12,
                    "count": 136270
                },
                {
                    "year": 2018,
                    "month": 11,
                    "count": 124550
                },
                {
                    "year": 2018,
                    "month": 10,
                    "count": 122670
                },
                {
                    "year": 2018,
                    "month": 9,
                    "count": 121820
                }
            ]
        }
    ]
}

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent through the POST method passing a tasks array. The data should be specified in the data field of this POST array.

Each array element has the following structure:

Field name Type Description
keys array keywords array
required field
You can specify a maximum of 700 keywords per request
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the List of Locations


As a response from the API server, you will receive a JSON array with keywords data in the results field.

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
task_id integer unique task identifier in our system (UInt64)
results_time string execution time
results_count integer number of elements in the results array results
results array results array
      search_engine string search engine
      loc_id integer search engine location id
      key string keyword
keyword is returned decoded %## (plus symbol ‘+’ is decoded to a space character)
      sv integer the average annual search volume rate
      ms array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is null


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field


This API endpoint can provide you with the most relevant queries for various locations within a specific time-range using our Clickstream database. The most relevant queries will be grouped according to their geographic location. The group will be taken for the period of time for which the keywords are retrieved. The group can be defined by a user.

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');

    $post_array[] = array(
        "loc_name_canonical" => "United States",
        "group_limit" => 3,
        "group_type" => "day",
        "start_date" => "2019-06-19",
        "end_date" => "2019-06-20"
    );

    $sv_post_result = $client->post('v2/kwrd_trends_clickstream', array('data' => $post_array));
    print_r($sv_post_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";
    exit();
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "task_id": 2837896973,
    "results_time": "2.8689 sec.",
    "results_count": 6,
    "results": [
        {
            "loc_id": 2840,
            "date": {
                "year": 2019,
                "month": 6,
                "day": 20,
                "week": 25
            },
            "trends": [
                {
                    "key": "summer season",
                    "sv": 21987240
                },
                {
                    "key": "facebook",
                    "sv": 5326060
                },
                {
                    "key": "nba draft",
                    "sv": 2706420
                }
            ]
        },
        {
            "loc_id": 2840,
            "date": {
                "year": 2019,
                "month": 6,
                "day": 19,
                "week": 25
            },
            "trends": [
                {
                    "key": "google maps",
                    "sv": 43426010
                },
                {
                    "key": "netflix",
                    "sv": 26107540
                },
                {
                    "key": "facebook",
                    "sv": 25668290
                }
            ]
        }
    ]
}

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent through the POST method passing a tasks array. The data should be specified in the data field of this POST array.

Each array element has the following structure:

Field name Type Description
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the List of Locations
group_type string trends grouping
required field
possible options:
day – results will be grouped by day
week – results will be grouped by week (corresponds to the integer ISO value of the week)
month – results will be grouped by month
start_date string the grouping’s start date
required field
the sampling will start from the specified datethe date must be in the “year-month-day” format, for example “2019-06-12”
min value: “2018-01-01”
max value: two days before the current date
for example, the current date is 2019-06-24, so the maximum value is 2019-06-22
also, the start_date must indicate a date that is prior to the end_date
end_date string the grouping’s end date
required field
the sampling will end by the specified datethe date format must be “year-month-day”, for example “2019-06-12”
min value: “2018-01-01”
max value: two days before the current date
for example, the current date is 2019-06-24, so the maximum value is 2019-06-22
also, the end_date must indicate a date that is after the start_date
the maximum time range (end_datestart_date) is 31 day
group_limit integer word limit
the maximum number of words in each group (grouping by months, weeks, or days)
default value: 10
max value: 100
group_offset integer offset in the results array of returned keys
default value: 0
max value: 50000


As a response from the API server, you will receive a JSON array with keywords data in the results field.

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
task_id integer unique task identifier in our system (UInt64)
results_time string execution time
results_count integer the number of elements in the results array results
indicates the total number of retrieved keywords
results array results array
      loc_id integer search engine location id
      date array date
the date for which the keywords will be grouped
            year integer year
            month integer month
if the filter is not specified, then the value is null
            week integer ISO week
if the filter is not specified, then the value is null
            day integer day
if the filter is not specified, then the value is null
      trends array trends
keyword array for a certain group
            key string keyword
            sv integer the average search volume rate
the average rate of unique Google search queries that involved the specified keyword as for a certain day/week/year


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field


This API endpoint can provide you with the most relevant queries based on a specific keyword, location and time-range using our Clickstream database. The most relevant queries will be grouped according to their geographic location. The group will be taken for the period of time for which the keywords are retrieved. The group can be defined by a user.

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');

    $post_array[] = array(
        "loc_name_canonical" => "United States",
        "key" => "tea",
        "group_limit" => 3,
        "group_type" => "day",
        "start_date" => "2019-06-19",
        "end_date" => "2019-06-20"
    );

    $sv_post_result = $client->post('v2/kwrd_trends_by_key_clickstream', array('data' => $post_array));
    print_r($sv_post_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";
    exit();
}

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "task_id": 325452996,
    "results_time": "7.2675 sec.",
    "results_count": 6,
    "results": [
        {
            "loc_id": 2840,
            "key": "tea",
            "date": {
                "year": 2019,
                "month": 6,
                "day": 20,
                "week": 25
            },
            "trends": [
                {
                    "key": "tea",
                    "sv": 1550
                },
                {
                    "key": "bubble tea challenge",
                    "sv": 730
                },
                {
                    "key": "boba tea near me",
                    "sv": 550
                }
            ]
        },
        {
            "loc_id": 2840,
            "key": "tea",
            "date": {
                "year": 2019,
                "month": 6,
                "day": 19,
                "week": 25
            },
            "trends": [
                {
                    "key": "tea",
                    "sv": 2000
                },
                {
                    "key": "bubble tea challenge",
                    "sv": 730
                },
                {
                    "key": "bubble tea near me",
                    "sv": 550
                }
            ]
        }
    ]
}

All POST data should be sent in the JSON format (UTF-8 encoding). The keywords are sent through the POST method passing a tasks array. The data should be specified in the data field of this POST array. Each array element should have the following structure:

Field name Type Description
loc_id integer search engine location id
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
loc_name_canonical string full name of a location for search engine
optional field
you must choose one of the fields: loc_id or loc_name_canonical
if you want to get results for international search, the field loc_id or loc_name_canonical should be empty
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the List of Locations
key string keyword
required field
for instance: “tea”
group_type string trends grouping
required field
possible options:
day – results will be grouped by day
week – results will be grouped by week (corresponds to the integer ISO value of the week)
month – results will be grouped by month
start_date string the grouping’s start date
required field
the sampling will start from the specified datethe date must be in the “year-month-day” format, for example “2019-06-12”
min value: “2018-01-01”
max value: two days before the current date
for example, the current date is 2019-06-24, so the maximum value is 2019-06-22
also, the start_date must indicate a date that is prior to the end_date
end_date string the grouping’s end date
required field
the sampling will end by the specified datethe date format must be “year-month-day”, for example “2019-06-12”
min value: “2018-01-01”
max value: two days before the current date
for example, the current date is 2019-06-24, so the maximum value is 2019-06-22
also, the end_date must indicate a date that is after the start_date
the maximum time range (end_datestart_date) is 31 day
group_limit integer word limit
the maximum number of words in each group (grouping by months, weeks, or days)
default value: 10
max value: 100
group_offset integer offset in results array of returned keys
default value: 0
max value: 50000


As a response from the API server, you will receive a JSON array with keywords data in the results field.

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
task_id integer unique task identifier in our system (UInt64)
results_time string execution time
results_count integer the number of elements in the results array results
indicates the total number of retrieved keywords
results array results array
      loc_id integer search engine location id
      key string keyword
keyword is returned decoded %## (plus symbol ‘+’ is decoded to a space character)
      date array date
the date for which the keywords will be grouped
         year integer year
         month integer month
if the filter is not specified, then the value is null
         week integer ISO week
if the filter is not specified, then the value is null
         day integer day
if the filter is not specified, then the value is null
      trends array trends
keyword array for a certain group
         key string keyword
         sv integer the average search volume rate
the average rate of unique Google search queries that involved the specified keyword as for a certain day/week/year


Possible error codes:

Error Code Meaning
400 “post data is not valid. please check this field: field” – please check the parameters specified in the field