NAVNavbar
Logo
php python csharp java

Keywords Finder API

One of the most important parts of website optimization is the creation of a keyword list. It is significant for both SEO and Ads. Using Keyword Finder API, you will be able to create or improve the list of keywords relevant to your project. Also, you can understand what keywords your or competitor’s website is ranking for.

We use in-house keyword database. Actual keywords and SERP volumes of our database can be found on the Keywords Finder API page. we continuously enlarge the database, and other locations and languages will be available soon.

Note: Keywords Finder API v2 has been updated with new functionality and is now available as DataForSEO Labs API v3.

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


Using this method, you will get keywords that are related to the keyword you are going to provide. Also, you can receive the average search volume, search volume trend for the last year (that allows estimating the search volume dynamics), current cost-per-click and competition value for the paid search. Related keywords are provided by Google in SERP based on the search query. Eight keywords can be found at the end of the search engine results page. Also, there is a possibility to get related terms for related keywords, if you specify the related search depth in the depth field.

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();
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "keyword" => "mountain house",
        "country_code" => "US",
        "language" => "en",
        "depth" => 2,
        "limit" => 1,
        "offset" => 0,
        "orderby" => "cpc,desc",
        "filters" => array(
            array("cpc", ">", 0),
            "or",
            array(
                array("search_volume", ">", 0),
                "and",
                array("search_volume", "<=", 1000)
            )
        )
    );

    $get_result = $client->post("v2/kwrd_finder_related_keywords_get", array('data' => $post_array));
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.5441 sec.",
    "results_count": 1,
    "results": {
        "11913049": {
            "post_id": "11913049",
            "task_id": 12937,
            "meta": {
                "keyword": "mountain house",
                "depth": 2,
                "limit": 1,
                "offset": 0,
                "orderby": "cpc,desc",
                "total_count": 71,
                "result_count": 1
            },
            "related": [
                {
                    "key": "freeze dried food reviews",
                    "country_code": "US",
                    "language": "en",
                    "search_volume": 50,
                    "competition": 1,
                    "cpc": 6.746295,
                    "categories": [
                        11889,
                        10113,
                        10081,
                        10082,
                        10422,
                        10010,
                        10014,
                        10015
                    ],
                    "history": [
                        {
                            "month": 2,
                            "year": 2018,
                            "search_volume": 10
                        },
                        {
                            "month": 1,
                            "year": 2018,
                            "search_volume": 10
                        },
                        {
                            "month": 12,
                            "year": 2017,
                            "search_volume": 10
                        },
                        {
                            "month": 11,
                            "year": 2017,
                            "search_volume": 10
                        },
                        {
                            "month": 10,
                            "year": 2017,
                            "search_volume": 40
                        },
                        {
                            "month": 9,
                            "year": 2017,
                            "search_volume": 70
                        },
                        {
                            "month": 8,
                            "year": 2017,
                            "search_volume": 70
                        },
                        {
                            "month": 7,
                            "year": 2017,
                            "search_volume": 70
                        },
                        {
                            "month": 6,
                            "year": 2017,
                            "search_volume": 90
                        },
                        {
                            "month": 5,
                            "year": 2017,
                            "search_volume": 90
                        },
                        {
                            "month": 4,
                            "year": 2017,
                            "search_volume": 110
                        },
                        {
                            "month": 3,
                            "year": 2017,
                            "search_volume": 70
                        }
                    ]
                }
            ]
        }
    }
}

You can specify the search depth, the number of results you want to retrieve, as well as filter and sort the results.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. Each array element has the following structure:

Field name Type Description
keyword string keyword
required field
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
a keyword should be at least 3 characters long
the keywords will be converted to lowercase format
country_code string ISO country code
required field
you can receive the list of available locations by making a separate request to the List of Keywords Finder Locations
the location code is specified in the country_code field
or in the List of Locations
the location code is specified in the loc_country_iso_code field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: US
language string language
required field
you can receive the list of available languages by making a separate request to the List of Keywords Finder Locations
the language code is specified in the language field
or in the List of Locations
the language code is specified in the kwrd_finder_lang field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: en
depth integer keyword search depth
required field
you can specify a level from 1 to 4
estimated number of keywords for each level (maximum):
1 – 8 keywords
2 – 72 keywords
3 – 584 keywords
4 – 4680 keywords
limit integer the maximum number of returned keys
default value: 100
maximum value: 1000
offset integer offset in the results array of returned keys
default value: 0
orderby string results sorting
you can use the following fields to sort the results:
search_volume, competition, cpc
possible sorting types:
asc, desc
you should specify the rules separating them with a comma
for example: competition,asc
you can also sort the results according to several fields at once (no more than three sorting rules at a time).
in this case you should specify the rule sets separating them with a semicolon, for example:
search_volume,desc;cpc,desc
the following rule is applied by default:
search_volume,desc
filters array filters array
if you specify a filter, then the three fields mentioned below must be specified
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions, for example:
["cpc", ">", 0]
[["cpc", ">", 0], "and", ["search_volume", "in", [10,20]]]
[["search_volume", ">", 500], "or", [["cpc", ">", 1], "and", ["cpc", "<", 10]]]
      $field string the name of the filtering field
posible filtering parameters:
key, search_volume, competition, cpc
      $operator string comparison operator
possible operator parameters:
<, <=, >, >=, =, <>, in, not_in, like, not_like

use the following combination of filtering fields and comparison operators:
key:
like, not_like, =, <>
search_volume, competition, cpc:
<, <=, >, >=, =, <>, in, not_in
If you want to filter results array by the key value using operators like or not_like, you can specify the following parameters:
["key", "like", "seo%"]      any values that start with “seo”
["key", "like", "%seo"]      any values that end with “seo”
["key", "like", "%seo%"]    any values that contain”seo”

      $value integer/string/array comparison value
use the following combination of comparison operators and data types:
like, not_like, =, <>:    string
<, <=, >, >=, =, <>:       integer
in, not_in:                       array


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array (concurrent requests)
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
      post_id string the index in the array received in the POST request
      meta array options and common task data
            keyword string keyword received in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            depth integer depth level for related keywords
            limit integer the maximum number of returned keywords
            offset integer offset in the results array of returned keywords
            orderby string results sorting
            total_count integer total amount of results in our database by a specific request
            results_count integer the number of elements in the related array by a specific request
      related array results array of related
            key string related keyword
            country_code string ISO country code
            language string language
            search_volume integer the average search volume
represents either the (approximate) number of searches for the given keyword idea on google.com
            competition float competition
represents the relative amount of competition associated with the given keyword idea in relation to other keywords. This value will be between 0 and 1 (inclusive)
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword
            categories array product and service categories
you can download the full list of possible categories
            history array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geolocations


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
“post data is empty” – specify the parameters for the request
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

Similar Keywords


Using this method, you can receive similar terms for a keyword. Also, you can receive the search volume data for the last month, search volume trend for the last year (that allows estimating the search volume dynamics), current cost-per-click and competition value for the paid search. These keywords are similar to the keyword you have specified or its variants that may be used in the search queries. For example, such keywords as “ice tea net worth”, “green tea ice cream”, “green tea with ice” will be in the results array for “ice tea” keyword.

Get Similar Keywords

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();
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "keyword" => "ice tea",
        "country_code" => "US",
        "language" => "en",
        "limit" => 1,
        "offset" => 0,
        "orderby" => "cpc,desc",
        "filters" => array(
            array("cpc", ">", 0),
            "or",
            array(
                array("search_volume", ">", 0),
                "and",
                array("search_volume", "<=", 1000)
            )
        )
    );

    $get_result = $client->post("v2/kwrd_finder_similar_keywords_get", array('data' => $post_array));
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "12.2924 sec.",
    "results_count": 1,
    "results": {
        "11049": {
            "post_id": "11049",
            "task_id": 12939,
            "meta": {
                "keyword": "ice tea",
                "limit": 1,
                "offset": 0,
                "orderby": "cpc,desc",
                "total_count": 559,
                "result_count": 1
            },
            "similar": [
                {
                    "key": "ice tea quotes",
                    "country_code": "US",
                    "language": "en",
                    "search_volume": 50,
                    "competition": 0.006802721088435374,
                    "cpc": 8.44334,
                    "categories": [
                        10002,
                        10083,
                        10756,
                        13861,
                        10010,
                        10108,
                        10444,
                        11645,
                        10031
                    ],
                    "history": [
                        {
                            "month": 1,
                            "year": 2018,
                            "search_volume": 40
                        },
                        {
                            "month": 12,
                            "year": 2017,
                            "search_volume": 40
                        },
                        {
                            "month": 11,
                            "year": 2017,
                            "search_volume": 20
                        },
                        {
                            "month": 10,
                            "year": 2017,
                            "search_volume": 30
                        },
                        {
                            "month": 9,
                            "year": 2017,
                            "search_volume": 40
                        },
                        {
                            "month": 8,
                            "year": 2017,
                            "search_volume": 50
                        },
                        {
                            "month": 7,
                            "year": 2017,
                            "search_volume": 50
                        },
                        {
                            "month": 6,
                            "year": 2017,
                            "search_volume": 110
                        },
                        {
                            "month": 5,
                            "year": 2017,
                            "search_volume": 90
                        },
                        {
                            "month": 4,
                            "year": 2017,
                            "search_volume": 50
                        },
                        {
                            "month": 3,
                            "year": 2017,
                            "search_volume": 50
                        },
                        {
                            "month": 2,
                            "year": 2017,
                            "search_volume": 70
                        }
                    ]
                }
            ]
        }
    }
}

You can specify the number of results you want to retrieve, filter and sort them.

All POST data should be sent in the JSON format (UTF-8 encoding). All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. Each array element has the following structure:

Field name Type Description
keyword string keyword
required field
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
a keyword should be at least 3 characters long
the keywords will be converted to lowercase format
country_code string ISO country code
optional field
you can receive the list of available locations by making a separate request to the List of Keywords Finder Locations
the location code is specified in the country_code field
or in the List of Locations
the location code is specified in the loc_country_iso_code field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: US
if you don’t specify a country_code, the results will be returned for all available locations
language string language
you can receive the list of available languages by making a separate request to the List of Keywords Finder Locations
the language code is specified in the language field
or in the List of Locations
the language code is specified in the kwrd_finder_lang field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: en
if you don’t specify a language, the results will be returned for all avaialbe languages
limit integer the maximum number of returned keys
default value: 100
maximum value: 1000
offset integer offset in the results array of returned keys
default value: 0
orderby string results sorting
you can use the following fields to sort the results:
search_volume, competition, cpc
possible sorting types:
asc, desc
you should specify the rules separating them with a comma
for example: competition,asc
you can also sort the results according to several fields at once (no more than three sorting rules at a time).
in this case you should specify the rules sets separating them with a semicolon, for example:
search_volume,desc;cpc,desc
the following rule is applied by default:
search_volume,desc
filters array filters array
if you specify a filter, then the three fields mentioned below must be specified
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions, for example:
["cpc", ">", 0]
[["cpc", ">", 0], "and", ["search_volume", "in", [10,20]]]
[["search_volume", ">", 500], "or", [["cpc", ">", 1], "and", ["cpc", "<", 10]]]
      $field string the name of the filtering field
posible filtering parameters:
key, search_volume, competition, cpc
      $operator string comparison operator
possible operator parameters:
<, <=, >, >=, =, <>, in, not_in, like, not_like

use the following combination of filtering fields and comparison operators:
key:
like, not_like, =, <>
search_volume, competition, cpc:
<, <=, >, >=, =, <>, in, not_in
If you want to filter results array by the key value using operators like or not_like, you can specify the following parameters:
["key", "like", "seo%"] any values that start with “seo”
["key", "like", "%seo"] any values that end with “seo”
["key", "like", "%seo%"] any values that contain”seo”

      $value integer/string/array comparison value
use the following combination of comparison operators and data types:
like, not_like, =, <>: string
<, <=, >, >=, =, <>: integer
in, not_in: array


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array (concurrent requests)
results array results array
      post_id string the index in the array received in the POST request
      task_id integer unique task identifier in our system (UInt64)
      meta array options and common task data
         keyword string keyword received in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
         limit integer the maximum number of returned keywords
         offset integer offset in the results array of returned keywords
         orderby string results sorting
         total_count integer total amount of results in our database by a specific request
         result_count integer the number of elements in the similar array by a specific request
      similar array results array of similar
         key string similar keyword
         country_code string ISO country code
         language string language
         search_volume integer the average search volume
represents the (approximate) number of searches for the given keyword idea on google.com
         competition float competition
represents the relative amount of competition associated with the given keyword idea in relation to other keywords. This value will be between 0 and 1 (inclusive)
         cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword
         categories array product and service categories
you can download the full list of possible categories
         history array monthly searches
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geolocations


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
“post data is empty” – specify the parameters for the request
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

Ranked Keywords


Using this method, you can get keywords for which a website is ranked. Also, you will get rankings and more essential data for this keyword in SERP.

The updated data for this method is available starting from the 12th day of a month.

Get Ranked Keywords

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();  
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "domain" => "dataforseo.com",
        "country_code" => "US",
        "language" => "en",
        "limit" => 1,
        "offset" => 0,
        "orderby" => "position,asc",
        "filters" => array(
            array("cpc", ">", 0),
            "and",
            array("search_volume", ">=", 1000)
        )
    );

    $get_result = $client->post("v2/kwrd_finder_ranked_keywords_get", array('data' => $post_array));
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.4582 sec.",
    "results_count": 1,
    "results": {
        "11049": {
            "post_id": "11049",
            "task_id": 12942,
            "meta": {
                "domain": "dataforseo.com",
                "limit": 1,
                "offset": 0,
                "orderby": "position,asc",
                "total_count": 84,
                "actual_metric": {
                    "organic_count": 29,
                    "paid_count": 0,
                    "etv": 101,
                    "pos1": 0,
                    "pos2_3": 0,
                    "pos4_10": 0,
                    "pos11_20": 0,
                    "pos21_30": 4,
                    "pos31_40": 4,
                    "pos41_50": 0,
                    "pos51_60": 9,
                    "pos61_70": 4,
                    "pos71_80": 6,
                    "pos81_90": 1,
                    "pos91_100": 1,
                    "paid_pos1": 0,
                    "paid_pos2_3": 0,
                    "paid_pos4_10": 0,
                    "paid_pos11_20": 0,
                    "paid_pos21_100": 0,
                    "impressions_etv": 39
                },
                "result_count": 1
            },
            "ranked": [
                {
                    "key": "serps rank checker",
                    "exact_domain": "dataforseo.com",
                    "country_code": "US",
                    "language": "en",
                    "position": 22,
                    "url": "https://dataforseo.com/apis/serp-api",
                    "relative_url": "/apis/serp-api",
                    "results_count": 65400,
                    "etv": 2,
                    "traffic_cost": 16.75442,
                    "competition": 0,
                    "cpc": 8.37721,
                    "date": "2018-03-16T00:00:00+00:00",
                    "extra": "",
                    "search_volume": 1000,
                    "spell": "",
                    "title": "SERP rank position checker API ⓴⓲ SERP analysis and keyword ...",
                    "snippet": "DataForSEO ➤➤➤ SERP API ➤➤➤ Google SERP Rankings Checker API ✓✓✓ Great Speed, Clear Stats, Simple Pricing. Try for free now!",
                    "categories": [
                        10004,
                        10007,
                        10019,
                        10168,
                        10276,
                        10296
                    ],
                    "impressions_etv": 7,
                    "daily_impressions_avg": 1.090000033378601,
                    "ads_pos1_cpc": 160.17999267578125,
                    "ads_pos1_daily_clicks": 0.07999999821186066,
                    "ads_pos1_daily_cost": 13.300000190734863
                }
            ]
        }
    }
}

You can specify the number of results you want to retrieve, filter and sort them.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. Each array element has the following structure:

Field name Type Description
domain string domain
required field
a domain should be specified without http:// and www
country_code string ISO country code
you can receive the list of available locations by making a separate request to the List of Keywords Finder Locations
the location code is specified in the country_code field
or in the List of Locations
the location code is specified in the loc_country_iso_code field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: US
if you don’t specify a country_code, the results will be returned for all locations
language string language
you can receive the list of available languages by making a separate request to the List of Keywords Finder Locations
the language code is specified in the language field
or in the List of Locations
the language code is specified in the kwrd_finder_lang field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: en
if you don’t specify a language, the results will be returned for all languages
type string SERP type
can have the following values: organic, paid
default value: organic
limit integer the maximum number of returned keys
default value: 100
maximum value: 1000
offset integer offset in the results array of returned keys
default value: 0
orderby string results sorting
you can use the following fields to sort the results:
search_volume, competition, cpc
possible sorting types:
asc, desc
you should specify the rules separating them with a comma
for example: competition,asc
you can also sort the results according to several fields at once (no more than three sorting rules at a time).
in this case you should specify the rules sets separating them with a semicolon, for example:
search_volume,desc;cpc,desc
the following rule is applied by default:
position,asc
filters array filters array
if you specify a filter, then the three fields mentioned below must be specified
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions, for example:
["cpc", ">", 0]
[["cpc", ">", 0], "and", ["search_volume", "in", [10,20]]]
[["search_volume", ">", 500], "or", [["cpc", ">", 1], "and", ["cpc", "<", 10]]]
      $field string the name of the filtering field
posible filtering parameters:
key, search_volume, competition, cpc
      $operator string comparison operator
possible operator parameters:
<, <=, >, >=, =, <>, in, not_in, like, not_like

use the following combination of filtering fields and comparison operators:
key:
like, not_like, =, <>
search_volume, competition, cpc:
<, <=, >, >=, =, <>, in, not_in
If you want to filter results array by the key value using operators like or not_like, you can specify the following parameters:
["key", "like", "seo%"] any values that start with “seo”
["key", "like", "%seo"] any values that end with “seo”
["key", "like", "%seo%"] any values that contain”seo”

      $value integer/string/array comparison value
use the following combination of comparison operators and data types:
like, not_like, =, <>: string
<, <=, >, >=, =, <>: integer
in, not_in: array


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array (concurrent requests)
results array results array
      post_id string the index in the array received in the POST request
      task_id integer unique task identifier in our system (UInt64)
      meta array options and common task data
            domain string the specified domain
            limit integer the maximum number of returned keywords
            offset integer offset in the results array of returned keywords
            orderby string results sorting
            total_count integer total amount of results in our database by a specific request
            result_count integer the number of elements in the ranked array by a specific request
            actual_metric array actual metrics for the specified domain
                  organic_count integer number of organic results in SERP
results will be available if you have set organic in the type field
                  paid_count integer the number of paid results in SERP
results will be available if you have set paid in the type field
                  etv integer estimated traffic to the domain based on organic and paid SERP data in the system
                  pos1 integer the number of organic SERP that contain the domain at the first position
                  pos2_3 integer the number of organic SERP that contain the domain at the second and third position
                  pos4_10 integer the number of organic SERP that contain the domain at the 4-10th position
                  pos11_20 integer the number of organic SERP that contain the domain at the 11-20th position
                  pos21_30 integer the number of organic SERP that contain the domain at the 21-30th position
                  pos31_40 integer the number of organic SERP that contain the domain at the 31-40th position
                  pos41_50 integer the number of organic SERP that contain the domain at the 41-50th position
                  pos51_60 integer the number of organic SERP that contain the domain at the 51-60th position
                  pos61_70 integer the number of organic SERP that contain the domain at the 61-70th position
                  pos71_80 integer the number of organic SERP that contain the domain at the 71-80th position
                  pos81_90 integer the number of organic SERP that contain the domain at the 81-90th position
                  pos91_100 integer the number of organic SERP that contain the domain at the 91-100th position
                  paid_pos1 integer the number of paid SERP that contain the domain at the first position
                  paid_pos2_3 integer the number of paid SERP that contain the domain at the second and third position
                  paid_pos4_10 integer the number of paid SERP that contain the domain at the 4-10th position
                  paid_pos11_20 integer the number of paid SERP that contain the domain at the 11-20th position
                  paid_pos21_100 integer the number of paid SERP that contain the domain at the 21-100th position
                  impressions_etv integer estimated traffic value based on daily impressions
based on Keywords Data API – Ads Traffic for Keywords at a $999 bid, using the match=exact mode
      ranked array results array with ranked keywords
            key string keyword in SERP
            country_code string ISO country code
            language string language
            exact_domain string exact domain
can be a subdomain
            position integer position in SERP
            url string relevant full URL in SERP
            relative_url string relative path and query from URL
            results_count integer total number of results in SERP
            etv integer estimated traffic value based on the search volume and the domain position
            traffic_cost float traffic cost
the value is calculated as ETV*CPC
            competition float Google AdWords competition value
            cpc float cost per click from Google AdWords
            date string date of the latest update
            extra string extra elements in SERP
can be equal to:
answer_box, app, blog, books, carousel, definition_block, discussions, featured_snippet, images, knowledge_graph, maps, news, patents, places, recipes, shopping, videos
            search_volume integer the number of searches per month
            spell string search engine auto-correction
            title string title of current SERP result
            snippet string the snippet of current SERP result
            categories array product and service categories
you can download the full list of possible categories
            impressions_etv integer estimated traffic value based on daily impressions
based on Keywords Data API – Ads Traffic for Keywords at a $999 bid, using the match=exact mode
            daily_impressions_avg float represents the average number of advertising daily impressions
based on Keywords Data API – Ads Traffic for Keywords at a $999 bid, using the match=exact mode
            ads_pos1_cpc float represents the average cost per click (USD) historically paid for the keyword
based on Keywords Data API – Ads Traffic for Keywords at a $999 bid, using the match=exact mode
            ads_pos1_daily_clicks float represents the average number of daily ad clicks
based on Keywords Data API – Ads Traffic for Keywords at a $999 bid, using the match=exact mode
            ads_pos1_daily_cost float represents the average daily cost per click (USD) historically paid for the keyword
based on Keywords Data API – Ads Traffic for Keywords at a $999 bid, using the match=exact mode


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
“post data is empty” – specify the parameters for the request
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

Keywords for Terms


Using this option, you can retrieve suggestions for the specified keywords. In addition to the keywords, you will also receive search volume for the last month, search volume trend for the previous 12 months (that allows estimating the search volume dynamics), current cost-per-click and competition level for the paid search. You also can set a number of keywords which you want to get using the limit field.

Get Keywords for Terms

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();  
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "keywords" => array("seo"),
        "country_code" => "US",
        "language" => "en",
        "limit" => 20
    );

    $get_result = $client->post("v2/kwrd_finder_kwrd_for_terms", array('data' => $post_array));
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.7020 sec.",
    "results_count": 1,
    "results": {
        "358941": {
            "post_id": "358941",
            "task_id": 891186,
            "meta": {
                "country_code": "US",
                "language": "en",
                "keywords": [
                    "seo"
                ],
                "limit": 20,
                "sort_by": "relevance",
                "result_count": 20
            },
            "result": [
                {
                    "key": "seo",
                    "country_code": "US",
                    "language": "en",
                    "search_volume": 135000,
                    "competition": 0.3620891386896943,
                    "cpc": 16.288592,
                    "history": [
                        {
                            "month": 2,
                            "year": 2019,
                            "search_volume": 135000
                        },
                        {
                            "month": 1,
                            "year": 2019,
                            "search_volume": 135000
                        },
                        {
                            "month": 12,
                            "year": 2018,
                            "search_volume": 110000
                        },
                        {
                            "month": 11,
                            "year": 2018,
                            "search_volume": 110000
                        },
                        {
                            "month": 10,
                            "year": 2018,
                            "search_volume": 135000
                        },
                        {
                            "month": 9,
                            "year": 2018,
                            "search_volume": 110000
                        },
                        {
                            "month": 8,
                            "year": 2018,
                            "search_volume": 110000
                        },
                        {
                            "month": 7,
                            "year": 2018,
                            "search_volume": 110000
                        },
                        {
                            "month": 6,
                            "year": 2018,
                            "search_volume": 110000
                        },
                        {
                            "month": 5,
                            "year": 2018,
                            "search_volume": 135000
                        },
                        {
                            "month": 4,
                            "year": 2018,
                            "search_volume": 135000
                        },
                        {
                            "month": 3,
                            "year": 2018,
                            "search_volume": 135000
                        }
                    ],
                    "categories": [
                        10004,
                        10007,
                        10276,
                        11088,
                        12376,
                        13152,
                        13316,
                        13418
                    ]
                },
                {
                    "key": "get google to crawl your website",
                    "country_code": "US",
                    "language": "en",
                    "search_volume": 10,
                    "competition": 0.07142857142857142,
                    "cpc": 0,
                    "history": [
                        {
                            "month": 12,
                            "year": 2018,
                            "search_volume": 10
                        },
                        {
                            "month": 11,
                            "year": 2018,
                            "search_volume": 10
                        },
                        {
                            "month": 10,
                            "year": 2018,
                            "search_volume": 10
                        },
                        {
                            "month": 9,
                            "year": 2018,
                            "search_volume": 10
                        },
                        {
                            "month": 8,
                            "year": 2018,
                            "search_volume": 0
                        },
                        {
                            "month": 7,
                            "year": 2018,
                            "search_volume": 10
                        },
                        {
                            "month": 6,
                            "year": 2018,
                            "search_volume": 10
                        },
                        {
                            "month": 5,
                            "year": 2018,
                            "search_volume": 10
                        },
                        {
                            "month": 4,
                            "year": 2018,
                            "search_volume": 10
                        },
                        {
                            "month": 3,
                            "year": 2018,
                            "search_volume": 10
                        },
                        {
                            "month": 2,
                            "year": 2018,
                            "search_volume": 10
                        },
                        {
                            "month": 1,
                            "year": 2018,
                            "search_volume": 10
                        }
                    ],
                    "categories": [
                        10004,
                        10007,
                        10276,
                        11088,
                        12376,
                        13152,
                        13316,
                        13418
                    ]
                }
            ]
        }
    }
}

You can specify the number of results you want to retrieve, filter and sort them.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. Each array element has the following structure:

Field name Type Description
country_code string ISO country code
required field
you can receive the list of available locations by making a separate request to the List of Keywords Finder Locations
the location code is specified in the country_code field
or in the List of Locations
the location code is specified in the loc_country_iso_code field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: US
language string language
required field
you can receive the list of available languages by making a separate request to the List of Keywords Finder Locations
the language code is specified in the language field
or in the List of Locations
the language code is specified in the kwrd_finder_lang field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: en
keywords array array of keywords
required field
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
each keyword should be at least 3 characters long
the keywords will be converted to lowercase format
a maximum of 200 keywords can be specified
limit integer the maximum number of returned keys
optional field
default value: 700
maximum value: 1000
sort_by string results sorting column
optional field
can have the following values: “sv”, “relevance”
default value: “relevance”
close_variants boolean close variants
optional field
specify the true value to receive only the results which are highly relevant to the provided keywords
default value: false


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array (concurrent requests)
results array results array
      post_id string the index in the array received in the POST request
      task_id integer unique task identifier in our system (UInt64)
      meta array options and common task data
            keywords array specified keywords
            limit integer the maximum number of returned keywords
            sort_by string results sorting
            result_count integer the number of elements in result array by a specific request
      result array results array of keywords
            key string keyword
            country_code string ISO country code
            language string language
            search_volume integer the number of searches per month
            competition float Google AdWords competition value
            cpc float cost per click from Google AdWords
            history array searches history
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geolocations.
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

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
“post data is empty” – specify the parameters for the request
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

SERP Competitors


Using this option, you can retrieve SERP competitors for specified keywords.

Get SERP Competitors

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();  
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "keywords" => array("phone", "buy"),
        "country_code" => "US",
        "language" => "en",
        "limit" => 20
    );

    $get_result = $client->post("v2/kwrd_finder_serp_competitors", array('data' => $post_array));
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1363 sec.",
    "results_count": 1,
    "results": {
        "874654654": {
            "post_id": "874654654",
            "task_id": 1066830,
            "meta": {
                "country_code": "US",
                "language": "en",
                "keywords": [
                    "phone",
                    "buy"
                ],
                "match_subdomains": true,
                "type": "organic",
                "limit": 20,
                "offset": 0,
                "orderby": "rating,desc",
                "result_count": 20
            },
            "domains": [
                {
                    "domain": "www.verizonwireless.com",
                    "avg_position": 18.5,
                    "median_position": 18.5,
                    "keywords_count": 2,
                    "rating": 163,
                    "etv": 9523,
                    "visibility": 0.4
                },
                {
                    "domain": "www.wsj.com",
                    "avg_position": 21,
                    "median_position": 21,
                    "keywords_count": 2,
                    "rating": 158,
                    "etv": 1747,
                    "visibility": 0.3
                },
                {
                    "domain": "zoom.us",
                    "avg_position": 25.5,
                    "median_position": 25.5,
                    "keywords_count": 2,
                    "rating": 149,
                    "etv": 875,
                    "visibility": 0
                },
                {
                    "domain": "www.microsoft.com",
                    "avg_position": 28.5,
                    "median_position": 28.5,
                    "keywords_count": 2,
                    "rating": 143,
                    "etv": 905,
                    "visibility": 0.05
                },
                {
                    "domain": "www.t-mobile.com",
                    "avg_position": 38,
                    "median_position": 38,
                    "keywords_count": 2,
                    "rating": 124,
                    "etv": 17362,
                    "visibility": 0.6
                }
            ]
        }
    }
}

You can specify the number of results you want to retrieve and sort them.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. Each array element has the following structure:

Field name Type Description
country_code string ISO country code
required field
you can receive the list of available locations by making a separate request to the List of Keywords Finder Locations
the location code is specified in the country_code field
or in the List of Locations
the location code is specified in the loc_country_iso_code field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: US
language string language
required 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
keywords array keywords aray
required field
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
a keyword should be at least 3 characters long
keywords will be converted to lowercase format
a maximum of 200 keywords can be specified
match_subdomains boolean match subdomains
optional field
if you specify a false value in the field, the subdomains will be ignored when grouping
default value: true
type string SERP type
can have the following values: organic, paid
default value: organic
limit integer the maximum number of returned results
optional field
default value: 100
maximum value: 1000
offset integer offset in the results array of returned keys
default value: 0
orderby string results sorting
possible fields that can be used to sort the results:
avg_position, median_position, keywords_count, rating, etv, visibility
possible sorting types:
asc, desc
use comma to separate the rules, for instance:
etv,desc
you can also sort the results according to several fields at once (no more than three sorting rules at a time); in this case, you should use a semicolon to separate the sets of rules, for example:
etv,desc;rating,desc
by default the following rule is applied:
rating,desc
filters array filters array
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions, for example:
["etv", ">", 1000]
[["etv", ">", 1000], "and", ["visibility", ">", 0]]
[["etv", ">", 1000], "and", [["visibility", ">", 0], "and", ["visibility", "<", 0.5]]]
The following three fields must be specified if you apply a filter
      $field string the name of the filtering field
posible filtering parameters:
avg_position, median_position, keywords_count, rating, etv, visibility
      $operator string comparison operator
possible operator parameters:
<, <=, >, >=, =, <>

use the following combination of filtering fields and comparison operators:
avg_position, median_position, keywords_count, rating, etv, visibility:
<, <=, >, >=, =, <>

      $value integer comparison value
use the following combination of comparison operators and data types:
<, <=, >, >=, =, <>:     integer


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array (concurrent requests)
results array results array
      post_id string the index in the array received in the POST request
      task_id integer unique task identifier in our system (UInt64)
      meta array options and common task data
            country_code string the code of the specified country
            language string the specified language
            keywords array the specified keywords
            match_subdomains boolean the specified matching subdomains
            type string the specified SERP type
            limit integer the maximum number of returned results
            offset integer the specified offset in the results array
            orderby string results sorting
            result_count integer the number of elements in the domains array by a specific request
      domains array results array
            domain string grouping field, can be a domain or subdomain
            avg_position float the average domain position in SERP intersections
            median_position float the median domain position in SERP intersections
            keywords_count integer intersected keywords count
            rating integer calculated as the sum (100 – position)
            etv integer estimated traffic value summary
            visibility float calculated as the sum of keywords positions
Keywords with positions in the range from 1 to 10 are assigned the visibility index from 1 to 0.1, respectively. Keywords with positions in the range from 11 to 20 have the fixed visibility index of 0.05. Keywords with positions from 20 to 100 have the visibility index equal to 0


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
“post data is empty” – specify the parameters for the request
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

Relevant Pages


Using this method you can get SERP metrics for the relevant website pages based on a specific location.

The updated data for this method is available starting from the 12th of a month.

Get Relevant Pages

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();  
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "domain" => "rankactive.com",
        "country_code" => "US",
        "language" => "en",
        "limit" => 3
    );

    $get_result = $client->post("v2/kwrd_finder_relevant_pages_get", array('data' => $post_array));
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1752 sec.",
    "results_count": 1,
    "results": {
        "11913049": {
            "post_id": "11913049",
            "task_id": 12947,
            "meta": {
                "domain": "rankactive.com",
                "limit": 3,
                "offset": 0,
                "orderby": "organic_count,desc",
                "total_count": 19,
                "result_count": 3
            },
            "relevant_pages": [
                {
                    "page_address": "rankactive.com/products/rank-tracker",
                    "country_code": "US",
                    "language": "en",
                    "organic_count": 217,
                    "paid_count": 0,
                    "impressions_etv": 9,
                    "etv": 161,
                    "pos1": 0,
                    "pos2_3": 0,
                    "pos4_10": 3,
                    "pos11_20": 34,
                    "pos21_30": 64,
                    "pos31_40": 39,
                    "pos41_50": 20,
                    "pos51_60": 17,
                    "pos61_70": 18,
                    "pos71_80": 10,
                    "pos81_90": 9,
                    "pos91_100": 3,
                    "paid_pos1": 0,
                    "paid_pos2_3": 0,
                    "paid_pos4_10": 0,
                    "paid_pos11_20": 0,
                    "paid_pos21_100": 0
                },
                {
                    "page_address": "rankactive.com/lp/rank-tracker/google-keyword-position-checker-api",
                    "country_code": "US",
                    "language": "en",
                    "organic_count": 26,
                    "paid_count": 0,
                    "impressions_etv": 9,
                    "etv": 3,
                    "pos1": 0,
                    "pos2_3": 0,
                    "pos4_10": 4,
                    "pos11_20": 4,
                    "pos21_30": 7,
                    "pos31_40": 2,
                    "pos41_50": 1,
                    "pos51_60": 5,
                    "pos61_70": 1,
                    "pos71_80": 1,
                    "pos81_90": 0,
                    "pos91_100": 1,
                    "paid_pos1": 0,
                    "paid_pos2_3": 0,
                    "paid_pos4_10": 0,
                    "paid_pos11_20": 0,
                    "paid_pos21_100": 0
                },
                {
                    "page_address": "rankactive.com/",
                    "country_code": "US",
                    "language": "en",
                    "organic_count": 15,
                    "paid_count": 0,
                    "impressions_etv": 9,
                    "etv": 13,
                    "pos1": 0,
                    "pos2_3": 0,
                    "pos4_10": 0,
                    "pos11_20": 1,
                    "pos21_30": 3,
                    "pos31_40": 1,
                    "pos41_50": 0,
                    "pos51_60": 1,
                    "pos61_70": 3,
                    "pos71_80": 2,
                    "pos81_90": 1,
                    "pos91_100": 3,
                    "paid_pos1": 0,
                    "paid_pos2_3": 0,
                    "paid_pos4_10": 0,
                    "paid_pos11_20": 0,
                    "paid_pos21_100": 0
                }
            ]
        }
    }
}

You can specify the number of results you want to retrieve, filter and sort them.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. Each array element has the following structure:

Field name Type Description
domain string domain
required field
a domain should be specified without http:// and www
country_code string ISO country code
you can receive the list of available locations by making a separate request to the List of Keywords Finder Locations
the location code is specified in the country_code field
or in the List of Locations
the location code is specified in the loc_country_iso_code field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: US
if you don’t specify a location, the results will be returned for all locations
language string language
you can receive the list of available languages by making a separate request to the List of Keywords Finder Locations
the language code is specified in the language field
or in the List of Locations
the language code is specified in the kwrd_finder_lang field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: en
if you don’t specify a language, the results will be returned for all languages
type string SERP type
can have the following values: organic, paid
default value: organic
limit integer maximum number of returned pages
default value: 100
maximum value: 1000
offset integer offset in the results array of returned pages
default value: 0
orderby string results sorting
possible fields that can be used to sort the results:
organic_count, paid_count, etv
possible sorting types:
asc, desc
you should specify the rules separating them with a comma
for example:
etv,asc
you can also sort the results according to several fields at once (no more than three sorting rules at a time).
in this case you should specify the rules sets separating them with a semicolon, for example:
etv,desc;organic_count,desc
by default there is such rule applied:
organic_count,desc
filters array filters array
if you specify a filter then the three fields mentioned below must be specified
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions, for example:
["paid_count", ">", 0]
[["etv", ">", 10], "and", ["paid_count", ">", 0]]
[["etv", ">", 10], "and", [["paid_count", ">", 0], "and", ["organic_count", ">", 10]]]
      $field string the name of the filtering field
posible filtering parameters:
page_address,organic_count, paid_count, etv
      $operator string comparison operator
possible operator parameters:
<, <=, >, >=, =, <>, in, not_in, like, not_like

use the following combination of filtering fields and comparison operators:
page_address:
like, not_like, =, <>
organic_count, paid_count, etv:
<, <=, >, >=, =, <>, in, not_in

      $value integer/string/array comparison value
use the following combination of comparison operators and data types:
like, not_like, =, <>:    string
<, <=, >, >=, =, <>:       integer
in, not_in:                       array


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array (concurrent requests)
results array results array
      post_id string the index in the array received in the POST request
      task_id integer unique task identifier in our system (UInt64)
      meta array options and common task data
            domain string the specified domain
            limit integer the maximum number of returned keywords
            offset integer offset in the results array of returned keywords
            orderby string results sorting
            total_count integer total amount of results in our database by a specific request
            result_count integer number of elements in the relevant_pages array by a specific request
      relevant_pages array results array of relevant_pages
            page_address string relevant page link
            country_code string ISO country code
            language string language
            organic_count integer the number of organic results in SERP
results will be available if you have set organic in the type field
            paid_count integer the number of paid results in SERP
results will be available if you have set paid in the type field
            impressions_etv integer estimated traffic value based on daily impressions
based on Keywords Data API – Ads Traffic for Keywords at a $999 bid, using the match=exact mode
            etv integer estimated traffic to the domain based on organic and paid SERP data in the system
            pos1 integer the number of organic SERP that contain the domain at the first position
            pos2_3 integer the number of organic SERP that contain the domain at the second and third position
            pos4_10 integer the number of organic SERP that contain the domain at the 4-10th position
            pos11_20 integer the number of organic SERP that contain the domain at the 11-20th position
            pos21_30 integer the number of organic SERP that contain the domain at the 21-30th position
            pos31_40 integer the number of organic SERP that contain the domain at the 31-40th position
            pos41_50 integer the number of organic SERP that contain the domain at the 41-50th position
            pos51_60 integer the number of organic SERP that contain the domain at the 51-60th position
            pos61_70 integer the number of organic SERP that contain the domain at the 61-70th position
            pos71_80 integer the number of organic SERP that contain the domain at the 71-80th position
            pos81_90 integer the number of organic SERP that contain the domain at the 81-90th position
            pos91_100 integer the number of organic SERP that contain the domain at the 91-100th position
            paid_pos1 integer the number of paid SERP that contain the domain at the first position
            paid_pos2_3 integer the number of paid SERP that contain the domain at the second and third position
            paid_pos4_10 integer the number of paid SERP that contain the domain at the 4-10th position
            paid_pos11_20 integer the number of paid SERP that contain the domain at the 11-20th position
            paid_pos21_100 integer the number of paid SERP that contain the domain at the 21-100th position


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
“post data is empty” – specify the parameters for the request
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

Subdomains


Using this method you can get SERP data for subdomains of a website based on a specific location.

The updated data for this method is available starting from the 12th day of a month.

Get Subdomains

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();  
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "domain" => "dataforseo.com",
        "country_code" => "US",
        "language" => "en",
        "limit" => 3
    );

    $get_result = $client->post("v2/kwrd_finder_subdomains_get", array('data' => $post_array));
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1327 sec.",
    "results_count": 1,
    "results": {
        "11913049": {
            "post_id": "11913049",
            "task_id": 12949,
            "meta": {
                "domain": "dataforseo.com",
                "limit": 3,
                "offset": 0,
                "orderby": "organic_count,desc",
                "total_count": 1,
                "result_count": 3
            },
            "subdomains": [
                {
                    "exact_domain": "docs.dataforseo.com",
                    "country_code": "US",
                    "language": "en",
                    "organic_count": 4,
                    "paid_count": 0,
                    "etv": 0,
                    "pos1": 0,
                    "pos2_3": 0,
                    "pos4_10": 0,
                    "pos11_20": 0,
                    "pos21_30": 0,
                    "pos31_40": 0,
                    "pos41_50": 0,
                    "pos51_60": 1,
                    "pos61_70": 1,
                    "pos71_80": 1,
                    "pos81_90": 1,
                    "pos91_100": 0,
                    "paid_pos1": 0,
                    "paid_pos2_3": 0,
                    "paid_pos4_10": 0,
                    "paid_pos11_20": 0,
                    "paid_pos21_100": 0
                }
            ]
        }
    }
}

You can specify the number of results you want to retrieve, filter and sort them.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. Each array element has the following structure:

Field name Type Description
domain string domain
required field
a domain should be specified without http:// and www
country_code string ISO country code
you can receive the list of available locations by making a separate request to the List of Keywords Finder Locations
the location code is specified in the country_code field
or in the List of Locations
the location code is specified in the loc_country_iso_code field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: US
if you don’t specify a country_code, the results will be returned for all locations
language string language
you can receive the list of available languages by making a separate request to the List of Keywords Finder Locations
the language code is specified in the language field
or in the List of Locations
the language code is specified in the kwrd_finder_lang field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: en
if you don’t specify a language, the results will be returned for all languages
type string SERP type
can have the following values: organic, paid
default value: organic
limit integer the maximum number of returned domains
default value: 100
maximum value: 1000
offset integer offset in the results array of returned domains
default value: 0
orderby string results sorting
possible fields that can be used to sort the results:
organic_count, paid_count, etv
possible sorting types:
asc, desc
you should specify the rules separating them with a comma
for example: etv,asc
you can also sort the results according to several fields at once (no more than three sorting rules at a time).
in this case you should specify the rules sets separating them with a semicolon, for example:
etv,desc;organic_count,desc
by default there is such rule applied:
organic_count,desc
filters array filters array
if you specify a filter, then the three fields mentioned below must be specified
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions, for example:
["paid_count", ">", 0]
[["etv", ">", 10], "and", ["paid_count", ">", 0]]
[["etv", ">", 10], "and", [["paid_count", ">", 0], "and", ["organic_count", ">", 10]]]
      $field string the name of the filtering field
posible filtering parameters:
exact_domain,organic_count, paid_count, etv
      $operator string comparison operator
possible operator parameters:
<, <=, >, >=, =, <>, in, not_in, like, not_like

use the following combination of filtering fields and comparison operators:
exact_domain:
like, not_like, =, <>
organic_count, paid_count, etv:
<, <=, >, >=, =, <>, in, not_in

      $value integer/string/array comparison value
use the following combination of comparison operators and data types:
like, not_like, =, <>:    string
<, <=, >, >=, =, <>:       integer
in, not_in:                       array


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
       code integer error code
       message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array (concurrent requests)
results array results array
       post_id string the index in the array received in the POST request
       task_id integer unique task identifier in our system (UInt64)
       meta array options and common task data
            domain string the specified domain
            limit integer the maximum number of returned keywords
            offset integer offset in the results array of returned keywords
            orderby string results sorting
            total_count integer total amount of results in our database by a specific request
            result_count integer the number of elements in subdomains array by a specific request
      subdomains array the results array of subdomains
            exact_domain string the exact domain
            country_code string ISO country code
            language string language
            organic_count integer the number of organic results in SERP
the results will be available if you have set organic in the type field
            paid_count integer number of paid results in SERP
the results will be available if you have set paid in the type field
            etv integer estimated traffic to the domain based on organic and paid SERP data in the system
            pos1 integer the number of organic SERP that contain the domain at the first position
            pos2_3 integer the number of organic SERP that contain the domain at the second and third position
            pos4_10 integer the number of organic SERP that contain the domain at the 4-10th position
            pos11_20 integer the number of organic SERP that contain the domain at the 11-20th position
            pos21_30 integer the number of organic SERP that contain the domain at the 21-30th position
            pos31_40 integer the number of organic SERP that contain the domain at the 31-40th position
            pos41_50 integer the number of organic SERP that contain the domain at the 41-50th position
            pos51_60 integer the number of organic SERP that contain the domain at the 51-60th position
            pos61_70 integer the number of organic SERP that contain the domain at the 61-70th position
            pos71_80 integer the number of organic SERP that contain the domain at the 71-80th position
            pos81_90 integer the number of organic SERP that contain the domain at the 81-90th position
            pos91_100 integer the number of organic SERP that contain the domain at the 91-100th position
            paid_pos1 integer the number of paid SERP that contain the domain at the first position
            paid_pos2_3 integer the number of paid SERP that contain the domain at the second and third position
            paid_pos4_10 integer the number of paid SERP that contain the domain at the 4-10th position
            paid_pos11_20 integer the number of paid SERP that contain the domain at the 11-20th position
            paid_pos21_100 integer the number of paid SERP that contain the domain at the 21-100th position


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
“post data is empty” – specify the parameters for the request
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

Competitors Domain


Using this option, you can get information about competitor domains for the specified site, which will be determined by the intersection of keywords.

Get Competitors Domain

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();  
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "domain" => "dataforseo.com",
        "country_code" => "US",
        "language" => "en",
        "limit" => 5
    );

    $get_result = $client->post("v2/kwrd_finder_domain_competitors", array('data' => $post_array));
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "5.2832 sec.",
    "results_count": 1,
    "results": {
        "874654654": {
            "post_id": "874654654",
            "task_id": 1113680,
            "meta": {
                "country_code": "US",
                "language": "en",
                "domain": "dataforseo.com",
                "type": "organic",
                "limit": 5,
                "orderby": "intersections,desc",
                "result_count": 5
            },
            "competitors": [
                {
                    "domain": "dataforseo.com",
                    "intersections": 916,
                    "pos_sum": 56325,
                    "avg_pos": 61.49017467248908,
                    "metrics": {
                        "organic_count": 916,
                        "paid_count": 9,
                        "etv": 663,
                        "impressions_etv": 70,
                        "pos1": 3,
                        "pos2_3": 7,
                        "pos4_10": 23,
                        "pos11_20": 21,
                        "pos21_30": 50,
                        "pos31_40": 82,
                        "pos41_50": 98,
                        "pos51_60": 145,
                        "pos61_70": 129,
                        "pos71_80": 121,
                        "pos81_90": 123,
                        "pos91_100": 114,
                        "paid_pos1": 3,
                        "paid_pos2_3": 5,
                        "paid_pos4_10": 1,
                        "paid_pos11_20": 0,
                        "paid_pos21_100": 0
                    }
                },
                {
                    "domain": "quora.com",
                    "intersections": 824,
                    "pos_sum": 25976,
                    "avg_pos": 31.524271844660195,
                    "metrics": {
                        "organic_count": 32274509,
                        "paid_count": 0,
                        "etv": 216701838,
                        "impressions_etv": 70,
                        "pos1": 560100,
                        "pos2_3": 1288017,
                        "pos4_10": 4817374,
                        "pos11_20": 5763842,
                        "pos21_30": 4612861,
                        "pos31_40": 3614436,
                        "pos41_50": 2940681,
                        "pos51_60": 2478975,
                        "pos61_70": 2087977,
                        "pos71_80": 1725691,
                        "pos81_90": 1403220,
                        "pos91_100": 981335,
                        "paid_pos1": 0,
                        "paid_pos2_3": 0,
                        "paid_pos4_10": 0,
                        "paid_pos11_20": 0,
                        "paid_pos21_100": 0
                    }
                },
                {
                    "domain": "moz.com",
                    "intersections": 773,
                    "pos_sum": 11076,
                    "avg_pos": 14.328589909443727,
                    "metrics": {
                        "organic_count": 288127,
                        "paid_count": 380,
                        "etv": 3380708,
                        "impressions_etv": 70,
                        "pos1": 3752,
                        "pos2_3": 5318,
                        "pos4_10": 19557,
                        "pos11_20": 25837,
                        "pos21_30": 26214,
                        "pos31_40": 28344,
                        "pos41_50": 30794,
                        "pos51_60": 31381,
                        "pos61_70": 31121,
                        "pos71_80": 30266,
                        "pos81_90": 29686,
                        "pos91_100": 25857,
                        "paid_pos1": 122,
                        "paid_pos2_3": 243,
                        "paid_pos4_10": 15,
                        "paid_pos11_20": 0,
                        "paid_pos21_100": 0
                    }
                },
                {
                    "domain": "google.com",
                    "intersections": 761,
                    "pos_sum": 22402,
                    "avg_pos": 29.437582128777922,
                    "metrics": {
                        "organic_count": 87318958,
                        "paid_count": 6079,
                        "etv": 3440879886,
                        "impressions_etv": 70,
                        "pos1": 536915,
                        "pos2_3": 570902,
                        "pos4_10": 2843155,
                        "pos11_20": 7069719,
                        "pos21_30": 7558212,
                        "pos31_40": 8244961,
                        "pos41_50": 8918941,
                        "pos51_60": 9761893,
                        "pos61_70": 10772621,
                        "pos71_80": 11361769,
                        "pos81_90": 11114253,
                        "pos91_100": 8565617,
                        "paid_pos1": 4418,
                        "paid_pos2_3": 1476,
                        "paid_pos4_10": 185,
                        "paid_pos11_20": 0,
                        "paid_pos21_100": 0
                    }
                },
                {
                    "domain": "ahrefs.com",
                    "intersections": 685,
                    "pos_sum": 17087,
                    "avg_pos": 24.944525547445256,
                    "metrics": {
                        "organic_count": 82321,
                        "paid_count": 0,
                        "etv": 1417521,
                        "impressions_etv": 70,
                        "pos1": 1769,
                        "pos2_3": 2648,
                        "pos4_10": 7451,
                        "pos11_20": 7201,
                        "pos21_30": 7660,
                        "pos31_40": 7615,
                        "pos41_50": 7954,
                        "pos51_60": 8022,
                        "pos61_70": 8081,
                        "pos71_80": 8139,
                        "pos81_90": 8324,
                        "pos91_100": 7457,
                        "paid_pos1": 0,
                        "paid_pos2_3": 0,
                        "paid_pos4_10": 0,
                        "paid_pos11_20": 0,
                        "paid_pos21_100": 0
                    }
                }
            ]
        }
    }
}

You can specify the number of results you want to retrieve and sort them.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. Each array element has the following structure:

Field name Type Description
country_code string ISO country code
required field
you can receive the list of available locations by making a separate request to the List of Keywords Finder Locations
the location code is specified in the country_code field
or in the List of Locations
the location code is specified in the loc_country_iso_code field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: US
language string language
required 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
domain string domain
required field
a domain should be specified without http://https:// and www
type string SERP type
can have the following values: organicpaid
default value: organic
limit integer the maximum number of returned results
optional field
default value: 100
maximum value: 1000
orderby string results sorting
you can use the following fields to sort the results:
intersectionspos_sumavg_pos
possible sorting types:
ascdesc
you should specify the rules separating them with a comma
for example:
intersections,desc
you can also sort the results according to several fields at once (no more than three sorting rules at a time).
in this case you should specify the rules sets separating them with a semicolon, for example:
intersections,desc;pos_sum,desc
the following rule is applied by default:
intersections,desc


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array (concurrent requests)
results array results array
      post_id string the index in the array received in the POST request
      task_id integer unique task identifier in our system (UInt64)
      meta array options and common task data
            country_code string the specified country code
            language string the specified language
            domain string the specified domain
            type string the specified SERP type
            limit integer the specified maximum number of returned results
            orderby string the specified results sorting
            result_count integer the number of elements in the competitors array by a specific request
      competitors array result array
            domain string competing domain name
            intersections integer count of keywords intersections
            pos_sum integer sum of the positions of a competing domain
            avg_pos float the average position of a competing domain
            metrics array domain metrics information
                  organic_count integer the number of organic results in SERP
the results will be available if you have set organic in the type field
                  paid_count integer the number of paid results in SERP
the results will be available if you have set paid in the type field
                  etv integer estimated traffic to the domain based on organic and paid SERP data in the system
                  impressions_etv integer estimated traffic value based on daily impressions
based on Keywords Data API – Ads Traffic for Keywords at a $999 bid, using the match=exact mode
                  pos1 integer the number of keywords for the domain that are ranking 1 in organic SERP
                  pos2_3 integer the number of keywords for the domain that are ranking 2-3 in organic SERP
                  pos4_10 integer the number of keywords for the domain that are ranking 4-10 in organic SERP
                  pos11_20 integer the number of keywords for the domain that are ranking 11-20 in organic SERP
                  pos21_30 integer the number of keywords for the domain that are ranking 21-30 in organic SERP
                  pos31_40 integer the number of keywords for the domain that are ranking 31-40 in organic SERP
                  pos41_50 integer the number of keywords for the domain that are ranking 41-50 in organic SERP
                  pos51_60 integer the number of keywords for the domain that are ranking 51-60 in organic SERP
                  pos61_70 integer the number of keywords for the domain that are ranking 61-70 in organic SERP
                  pos71_80 integer the number of keywords for the domain that are ranking 71-80 in organic SERP
                  pos81_90 integer the number of keywords for the domain that are ranking 81-90 in organic SERP
                  pos91_100 integer the number of keywords for the domain that are ranking 91-100 in organic SERP
                  paid_pos1 integer the number of keywords for the domain that are ranking 1 in paid SERP
                  paid_pos2_3 integer the number of keywords for the domain that are ranking 2-3 in paid SERP
                  paid_pos4_10 integer the number of keywords for the domain that are ranking 4-10 in paid SERP
                  paid_pos11_20 integer the number of keywords for the domain that are ranking 11-20 in paid SERP
                  paid_pos21_100 integer the number of keywords for the domain that are ranking 21-100 in paid SERP


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
“post data is empty” – specify the parameters for the request
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

Categories For Domain


Using this option, you can check the categories of keywords for which a domain is ranking.

The updated data for this method is available starting from the 12th day of a month.

Get Categories For Domain

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();  
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "domain" => "hide.co.uk",
        "country_code" => "GB",
        "language" => "en",
        "limit" => 10,
        "orderby" => "organic_count,desc"
    );

    $get_result = $client->post("v2/kwrd_finder_categories_for_domain_get", array('data' => $post_array));
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.7265 sec.",
    "results_count": 1,
    "results": {
        "11913049": {
            "post_id": "11dfg913049",
            "task_id": 1157987462,
            "meta": {
                "domain": "hide.co.uk",
                "limit": 10,
                "offset": 0,
                "orderby": "organic_count,desc",
                "type": "organic",
                "total_count": 39,
                "result_count": 10
            },
            "categories": [
                {
                    "category": [],
                    "country_code": "GB",
                    "language": "en",
                    "organic_count": 493,
                    "paid_count": 0,
                    "organic_traffic_cost": 3085.219878,
                    "paid_traffic_cost": 0,
                    "etv": 3687,
                    "impressions_etv": 70,
                    "date": "2019-05-16 00:00:00+00:00",
                    "pos1": 42,
                    "pos2_3": 3,
                    "pos4_10": 19,
                    "pos11_20": 34,
                    "pos21_30": 44,
                    "pos31_40": 41,
                    "pos41_50": 41,
                    "pos51_60": 43,
                    "pos61_70": 57,
                    "pos71_80": 59,
                    "pos81_90": 47,
                    "pos91_100": 63,
                    "paid_pos1": 0,
                    "paid_pos2_3": 0,
                    "paid_pos4_10": 0,
                    "paid_pos11_20": 0,
                    "paid_pos21_100": 0
                },
                {
                    "category": [
                        10020
                    ],
                    "country_code": "GB",
                    "language": "en",
                    "organic_count": 161,
                    "paid_count": 0,
                    "organic_traffic_cost": 7338.505013,
                    "paid_traffic_cost": 0,
                    "etv": 6308,
                    "impressions_etv": 70,
                    "date": "2019-05-16 00:00:00+00:00",
                    "pos1": 7,
                    "pos2_3": 0,
                    "pos4_10": 4,
                    "pos11_20": 10,
                    "pos21_30": 11,
                    "pos31_40": 16,
                    "pos41_50": 17,
                    "pos51_60": 21,
                    "pos61_70": 18,
                    "pos71_80": 18,
                    "pos81_90": 18,
                    "pos91_100": 21,
                    "paid_pos1": 0,
                    "paid_pos2_3": 0,
                    "paid_pos4_10": 0,
                    "paid_pos11_20": 0,
                    "paid_pos21_100": 0
                },
                {
                    "category": [
                        10169
                    ],
                    "country_code": "GB",
                    "language": "en",
                    "organic_count": 98,
                    "paid_count": 0,
                    "organic_traffic_cost": 19012.519,
                    "paid_traffic_cost": 0,
                    "etv": 9801,
                    "impressions_etv": 70,
                    "date": "2019-05-16 00:00:00+00:00",
                    "pos1": 1,
                    "pos2_3": 0,
                    "pos4_10": 5,
                    "pos11_20": 8,
                    "pos21_30": 13,
                    "pos31_40": 11,
                    "pos41_50": 4,
                    "pos51_60": 8,
                    "pos61_70": 13,
                    "pos71_80": 11,
                    "pos81_90": 14,
                    "pos91_100": 10,
                    "paid_pos1": 0,
                    "paid_pos2_3": 0,
                    "paid_pos4_10": 0,
                    "paid_pos11_20": 0,
                    "paid_pos21_100": 0
                }
            ]
        }
    }
}

You can specify the number of results you want to retrieve and sort them.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. Each array element has the following structure:

Field name Type Description
country_code string ISO country code
required field
you can receive the list of available locations by making a separate request to the List of Keywords Finder Locations
the location code is specified in the country_code field
or in the List of Locations
the location code is specified in the loc_country_iso_code field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: US
language string language
required field
you can receive the list of available languages by making a separate request to the List of Keywords Finder Locations
the language code is specified in the language field
or in the List of Locations
the language code is specified in the kwrd_finder_lang field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: en
domain string domain
required field
a domain should be specified without http://https:// and www
type string SERP type
can have the following values: organicpaid
default value: organic
full_tuple boolean ranked keywords categories
If full_tuple: true, you will get data based on the full list of categories.
by default, the value is false which means you will get the root category data only.
limit integer the maximum number of returned results
optional field
default value: 100
maximum value: 1000
offset integer offset in the results array of returned keys
default value: 0
orderby string results sorting
you can use the following fields to sort the results:
organic_countpaid_countorganic_traffic_costpaid_traffic_costetvpos1pos2_3pos4_10pos11_20pos21_30pos31_40pos41_50pos51_60pos61_70pos71_80pos81_90pos91_100paid_pos1paid_pos2_3paid_pos4_10paid_pos11_20paid_pos21_100
possible sorting types:
ascdesc
you should specify the rules separating them with a comma
for example:
organic_count,asc
you can also sort the results according to several fields at once (no more than three sorting rules at a time).
in this case you should specify the rule sets separating them with a semicolon, for example:
organic_count,desc;etv,desc
the following rule is applied by default:
etv,desc
filters array array with filters
if you specify a filter, then the three fields mentioned below must be specified
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions, for example:
["pos1", ">", 0]
[["etv", ">", 0], "and", ["pos1", "in", [10,20]]]
[["etv", ">", 1000], "and", [["pos1", ">", 0], "and", ["organic_count", ">", 30]]]
      $field string the name of the filtered field
posible filtering parameters:
organic_countpaid_countorganic_traffic_costpaid_traffic_costpos1pos2_3pos4_10pos11_20pos21_30pos31_40pos41_50pos51_60pos61_70pos71_80pos81_90pos91_100paid_pos1paid_pos2_3paid_pos4_10paid_pos11_20paid_pos21_100etv
      $operator string comparison operator
possible operator parameters:
<<=>>==<>innot_in
      $value integer/string/array comparison value
use the following combination of comparison operators and data types:
<<=>>==<>:     integer
innot_in:                       array


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array (concurrent requests)
results array results array
      post_id string the index in the array received in the POST request
      task_id integer unique task identifier in our system (UInt64)
      meta array options and common task data
            domain string the specified domain
            limit integer the specified maximum number of returned results
            offset integer offset in the results array of returned keys
            orderby string the specified results sorting
            type string the specified SERP type
            total_count integer total amount of results in our database by a specific request
            result_count integer the number of elements in the categories array by a specific request
      categories array result array
            category array product and service categories
you can download the full list of possible categories
            country_code string the specified country code
            language string the specified language
            organic_count integer the number of organic results in SERP
            paid_count integer the number of paid results in SERP
            organic_traffic_cost float the value is calculated as ETV*CPC for organic resuls
            paid_traffic_cost float the value is calculated as ETV*CPC for paid resuls
            etv integer estimated montly traffic volume for the domain based on the search volume values and keywords rankings
            impressions_etv integer estimated daily traffic volume for a domain based on daily impression values and keywords rankings
based on Keywords Data API – Ads Traffic for Keywords at a $999 bid, using the match=exact mode
            date string date of the latest update
            pos1 integer the number of organic SERP that contain the domain at the first position
            pos2_3 integer the number of organic SERP that contain the domain at the second and third position
            pos4_10 integer the number of organic SERP that contain the domain at the 4-10th position
            pos11_20 integer the number of organic SERP that contain the domain at the 11-20th position
            pos21_30 integer the number of organic SERP that contain the domain at the 21-30th position
            pos31_40 integer the number of organic SERP that contain the domain at the 31-40th position
            pos41_50 integer the number of organic SERP that contain the domain at the 41-50th position
            pos51_60 integer the number of organic SERP that contain the domain at the 51-60th position
            pos61_70 integer the number of organic SERP that contain the domain at the 61-70th position
            pos71_80 integer the number of organic SERP that contain the domain at the 71-80th position
            pos81_90 integer the number of organic SERP that contain the domain at the 81-90th position
            pos91_100 integer the number of organic SERP that contain the domain at the 91-100th position
            paid_pos1 integer the number of paid SERP that contain the domain at the first position
            paid_pos2_3 integer the number of paid SERP that contain the domain at the second and third position
            paid_pos4_10 integer the number of paid SERP that contain the domain at the 4-10th position
            paid_pos11_20 integer the number of paid SERP that contain the domain at the 11-20th position
            paid_pos21_100 integer the number of paid SERP that contain the domain at the 21-100th position


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
“post data is empty” – specify the parameters for the request
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

Keywords For Categories


Using this option, you can get keywords for the specified categories.

Get Keywords For Categories

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();  
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "categories" => array(12193, 12191),
        "country_code" => "US",
        "language" => "en",
        "limit" => 10
    );

    $get_result = $client->post("v2/kwrd_finder_keywords_for_category", array('data' => $post_array));
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.4121 sec.",
    "results_count": 1,
    "results": {
        "25113049": {
            "post_id": "25113049",
            "task_id": 1258444,
            "meta": {
                "categories": [
                    12193,
                    12191
                ],
                "country_code": "US",
                "language": "en",
                "limit": 10,
                "offset": 0,
                "orderby": "search_volume,desc",
                "total_count": 1026,
                "result_count": 10
            },
            "similar": [
                {
                    "key": "computing",
                    "date": "2019-05-20",
                    "search_volume": 301000,
                    "competition": 0.9997535909226722,
                    "cpc": 1.526451,
                    "history": [
                        {
                            "month": 3,
                            "year": 2019,
                            "search_volume": 301000
                        },
                        {
                            "month": 2,
                            "year": 2019,
                            "search_volume": 301000
                        },
                        {
                            "month": 1,
                            "year": 2019,
                            "search_volume": 368000
                        },
                        {
                            "month": 12,
                            "year": 2018,
                            "search_volume": 368000
                        },
                        {
                            "month": 11,
                            "year": 2018,
                            "search_volume": 450000
                        },
                        {
                            "month": 10,
                            "year": 2018,
                            "search_volume": 368000
                        },
                        {
                            "month": 9,
                            "year": 2018,
                            "search_volume": 368000
                        },
                        {
                            "month": 8,
                            "year": 2018,
                            "search_volume": 368000
                        },
                        {
                            "month": 7,
                            "year": 2018,
                            "search_volume": 301000
                        },
                        {
                            "month": 6,
                            "year": 2018,
                            "search_volume": 301000
                        },
                        {
                            "month": 5,
                            "year": 2018,
                            "search_volume": 301000
                        },
                        {
                            "month": 4,
                            "year": 2018,
                            "search_volume": 301000
                        }
                    ],
                    "categories": [
                        10019,
                        10168,
                        10883,
                        12187,
                        12191,
                        12193
                    ]
                },
                {
                    "key": "dell optiplex",
                    "date": "2019-05-23",
                    "search_volume": 14800,
                    "competition": 0.9998667066546703,
                    "cpc": 1.538783,
                    "history": [
                        {
                            "month": 3,
                            "year": 2019,
                            "search_volume": 18100
                        },
                        {
                            "month": 2,
                            "year": 2019,
                            "search_volume": 18100
                        },
                        {
                            "month": 1,
                            "year": 2019,
                            "search_volume": 18100
                        },
                        {
                            "month": 12,
                            "year": 2018,
                            "search_volume": 18100
                        },
                        {
                            "month": 11,
                            "year": 2018,
                            "search_volume": 18100
                        },
                        {
                            "month": 10,
                            "year": 2018,
                            "search_volume": 18100
                        },
                        {
                            "month": 9,
                            "year": 2018,
                            "search_volume": 14800
                        },
                        {
                            "month": 8,
                            "year": 2018,
                            "search_volume": 14800
                        },
                        {
                            "month": 7,
                            "year": 2018,
                            "search_volume": 14800
                        },
                        {
                            "month": 6,
                            "year": 2018,
                            "search_volume": 12100
                        },
                        {
                            "month": 5,
                            "year": 2018,
                            "search_volume": 14800
                        },
                        {
                            "month": 4,
                            "year": 2018,
                            "search_volume": 14800
                        }
                    ],
                    "categories": [
                        10019,
                        10168,
                        10883,
                        12187,
                        12191,
                        12193
                    ]
                },
                {
                    "key": "dell optiplex 7010",
                    "date": "2019-05-23",
                    "search_volume": 8100,
                    "competition": 1,
                    "cpc": 0.742031,
                    "history": [
                        {
                            "month": 3,
                            "year": 2019,
                            "search_volume": 8100
                        },
                        {
                            "month": 2,
                            "year": 2019,
                            "search_volume": 8100
                        },
                        {
                            "month": 1,
                            "year": 2019,
                            "search_volume": 9900
                        },
                        {
                            "month": 12,
                            "year": 2018,
                            "search_volume": 8100
                        },
                        {
                            "month": 11,
                            "year": 2018,
                            "search_volume": 8100
                        },
                        {
                            "month": 10,
                            "year": 2018,
                            "search_volume": 8100
                        },
                        {
                            "month": 9,
                            "year": 2018,
                            "search_volume": 6600
                        },
                        {
                            "month": 8,
                            "year": 2018,
                            "search_volume": 6600
                        },
                        {
                            "month": 7,
                            "year": 2018,
                            "search_volume": 6600
                        },
                        {
                            "month": 6,
                            "year": 2018,
                            "search_volume": 6600
                        },
                        {
                            "month": 5,
                            "year": 2018,
                            "search_volume": 6600
                        },
                        {
                            "month": 4,
                            "year": 2018,
                            "search_volume": 6600
                        }
                    ],
                    "categories": [
                        10019,
                        10168,
                        10883,
                        12187,
                        12191,
                        12193
                    ]
                }
            ]
        }
    }
}

You can specify the number of results you want to retrieve and sort them.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. Each array element has the following structure:

Field name Type Description
country_code string ISO country code
required field
you can receive the list of available locations by making a separate request to the List of Keywords Finder Locations
the location code is specified in the country_code field
or in the List of Locations
the location code is specified in the loc_country_iso_code field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: US
language string language
required field
you can receive the list of available languages by making a separate request to the List of Keywords Finder Locations
the language code is specified in the language field
or in the List of Locations
the language code is specified in the kwrd_finder_lang field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: en
categories array product and service categories
required field
you can download the full list of possible categories
intersections boolean category intersection mode
optional field
If you specify more than one category, you can use the intersection mode.
By default intersections: true, which means that you will get only the keywords that appear in each of the specified categories. If you set it to false, you will receive all keywords that appear in the specified categories, regardless of their intersections.
limit integer the maximum number of returned results
optional field
default value: 100
maximum value: 1000
offset integer offset in results array of returned keys
optional field
default value: 0
orderby string results sorting
optional field
you can use the following fields to sort the results:
keysearch_volumecompetitioncpc
possible sorting types:
ascdesc
you should specify the rules separating them with a comma
for example:
competition,asc
you can also sort the results according to several fields at once (no more than three sorting rules at a time).
in this case you should specify the rules sets separating them with a semicolon, for example:
competition,desc;cpc,desc
the following rule is applied by default:
search_volume,desc
filters array filters array
optional field
if you specify a filter, then the three fields mentioned below must be specified
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions, for example:
["search_volume", ">", 0]
[["search_volume", ">", 0], "and", ["search_volume", "in", [10,20]]]
[["cpc", ">", 0], "and", [["search_volume", ">", 0], "and", ["search_volume", "<", 500]]]
      $field string the name of the filtered field
posible filtering parameters:
keysearch_volumecompetitioncpc
      $operator string comparison operator
possible operator parameters:
<<=>>==<>innot_inlikenot_like
use the following combination of filtering fields and comparison operators:
key:
likenot_like=<>
search_volumecompetitioncpc:
<<=>>==<>innot_in
      $value integer/string/array comparison value
use the following combination of comparison operators and data types:
likenot_like=<>:    string
<<=>>==<>:     integer
innot_in:                       array


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array (concurrent requests)
results array results array
      post_id string the index in the array received in the POST request
      task_id integer unique task identifier in our system (UInt64)
      meta array options and common task data
            categories array the specified categories
            country_code string the specified country code
            language string the specified language
            limit integer the specified maximum number of returned results
            offset integer offset in the results array of returned keys
            orderby string the specified results sorting
            total_count integer total amount of results in our database by a specific request
            result_count integer the number of elements in the similar array by a specific request
      similar array result array
            key string keyword
keyword for the specified category
            date string date of the latest update
            search_volume integer average search volume
represents the (approximate) number of searches for the given keyword idea on google.com
            competition float competition
represents the relative amount of competition associated with the given keyword idea, in relation to other keywords. Can have the values between 0 and 1 inclusive
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword
            history array searches history
represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geolocations.
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


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
“post data is empty” – specify the parameters for the request
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

Ranked Domains By Category

Using this option, you can check what domains are ranking for specific categories.

The updated data for this method is available starting from the 12th day of a month.

Get Ranked Domains By Category

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();  
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "categories" => array(13841),
        "country_code" => "GB",
        "language" => "en",
        "limit" => 10,
        "orderby" => "organic_count,desc"
    );

    $get_result = $client->post("v2/kwrd_finder_ranked_domains_by_category_get", array('data' => $post_array));
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.7265 sec.",    
    "results_count": 1,
    "results": {
        "113154235149": {
            "post_id": "113154235149",
            "task_id": 3291258337,
            "meta": {
                "categories": [
                    13841
                ],
                "limit": 10,
                "offset": 0,
                "orderby": "organic_count,desc",
                "type": "organic",
                "total_count": 31726,
                "result_count": 10
            },
            "domains": [
                {
                    "category": 13841,
                    "domain": "indiatimes.com",
                    "country_code": "GB",
                    "language": "en",
                    "organic_count": 4,
                    "paid_count": 0,
                    "organic_traffic_cost": 157760.534941,
                    "paid_traffic_cost": 0,
                    "etv": 85228,
                    "date": "2019-05-23 00:00:00+00:00",
                    "domain_metric": {
                        "organic_count": 870504,
                        "paid_count": 0,
                        "organic_traffic_cost": 8787321.818178,
                        "etv": 9268770,
                        "date": "2019-04-01 00:00:00+00:00",
                        "pos1": 5451,
                        "pos2_3": 15162,
                        "pos4_10": 74164,
                        "pos11_20": 93668,
                        "pos21_30": 86435,
                        "pos31_40": 87517,
                        "pos41_50": 87439,
                        "pos51_60": 87486,
                        "pos61_70": 87673,
                        "pos71_80": 87338,
                        "pos81_90": 85928,
                        "pos91_100": 72243,
                        "paid_pos1": 0,
                        "paid_pos2_3": 0,
                        "paid_pos4_10": 0,
                        "paid_pos11_20": 0,
                        "paid_pos21_100": 0
                    }
                },
                {
                    "category": 13841,
                    "domain": "khanacademy.org",
                    "country_code": "GB",
                    "language": "en",
                    "organic_count": 3,
                    "paid_count": 0,
                    "organic_traffic_cost": 209.997052,
                    "paid_traffic_cost": 0,
                    "etv": 151,
                    "date": "2019-05-23 00:00:00+00:00",
                    "domain_metric": {
                        "organic_count": 292688,
                        "paid_count": 1,
                        "organic_traffic_cost": 1940359.58822,
                        "etv": 2828379,
                        "date": "2019-04-01 00:00:00+00:00",
                        "pos1": 5555,
                        "pos2_3": 11405,
                        "pos4_10": 38827,
                        "pos11_20": 42585,
                        "pos21_30": 28704,
                        "pos31_40": 23617,
                        "pos41_50": 22234,
                        "pos51_60": 22804,
                        "pos61_70": 24175,
                        "pos71_80": 24963,
                        "pos81_90": 25806,
                        "pos91_100": 22013,
                        "paid_pos1": 1,
                        "paid_pos2_3": 0,
                        "paid_pos4_10": 0,
                        "paid_pos11_20": 0,
                        "paid_pos21_100": 0
                    }
                }
            ]
        }
    }
}

You can specify the number of results you want to retrieve and sort them.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. Each array element has the following structure:

Field name Type Description
categories array product and service categories
you can download the full list of possible categories
country_code string ISO country code
required field
you can receive the list of available locations by making a separate request to the List of Keywords Finder Locations
the location code is specified in the country_code field
or in the List of Locations
the location code is specified in the loc_country_iso_code field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: US
language string language
required field
you can receive the list of available languages by making a separate request to the List of Keywords Finder Locations
the language code is specified in the language field
or in the List of Locations
the language code is specified in the kwrd_finder_lang field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: en
type string SERP type
can have the following values: organic, paid
default value: organic
limit integer the maximum number of returned results
optional field
default value: 100
maximum value: 1000
offset integer offset in the results array of returned keys
default value: 0
orderby string results sorting
you can use the following fields to sort the results:
domain,organic_count, paid_count, organic_traffic_cost, paid_traffic_cost, etv
possible sorting types:
asc, desc
you should specify the rules separating them with a comma
for example:
organic_count,asc
you can also sort the results according to several fields at once (no more than three sorting rules at a time).
in this case you should specify the rules sets separating them with a semicolon, for example:
organic_count,desc;etv,desc
the following rule is applied by default:
etv,desc
filters array filters array
if you specify a filter, then the three fields mentioned below must be specified
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions, for example:
["organic_count", ">", 0]
[["etv", ">", 0], "and", ["organic_count", "in", [10,20]]]
[["etv", ">", 1000], "and", [["organic_count", ">", 0], "and", ["organic_count", "<", 30]]]
      $field string the name of filtering field
posible filtering parameters:
domain, organic_count, paid_count, organic_traffic_cost, paid_traffic_cost, etv
      $operator string comparison operator
possible operator parameters:
<, <=, >, >=, =, <>, in, not_in, like, not_like

use the following combination of filtering fields and comparison operators:
domain:
like, not_like
organic_count, paid_count, organic_traffic_cost, paid_traffic_cost, etv:
<, <=, >, >=, =, <>, in, not_in

if you want to filter the results array by the key value using operators like or not_like, you can specify the following:
["key", "like", "seo%"]      any values that start with “seo”
["key", "like", "%seo"]      any values that end with “seo”
["key", "like", "%seo%"]    any values that have “seo” in any position

      $value integer/string/array comparison value
use the following combination of comparison operators and data types:
<, <=, >, >=, =, <>:       integer
in, not_in:                       array
like, not_like:                string


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array (concurrent requests)
results array results array
      post_id string the index in the array received in the POST request
      task_id integer unique task identifier in our system (UInt64)
      meta array options and common task data
            categories array the specified categories
            limit integer the specified maximum number of returned results
            offset integer offset in the results array of returned keys
            orderby string the specified results sorting
            type string the specified SERP type
            total_count integer total amount of results in our database by a specific request
            result_count integer the number of elements in the similar array by a specific request
      domains array results array
            category string the specified category
            domain string domain
            country_code string the specified country code
            language string the specified language
            organic_count integer the number of organic results in SERP for a specific category
            paid_count integer the number of paid results in SERP for a specific category
            organic_trafic_cost float the value is calculated as ETV*CPC for organic resuls for a specific category
            paid_trafic_cost float the value is calculated as ETV*CPC for paid resuls for a specific category
            etv integer estimated traffic to the domain based on organic and paid SERP data in the system for a specific category
            date string the current date
            domain_metric array domain metric
                  organic_count integer total number of organic results in SERP for a specific category
                  paid_count integer total number of paid results in SERP for a specific category
                  organic_trafic_cost float the value is calculated as ETV*CPC for total organic resuls
                  paid_trafic_cost float the value is calculated as ETV*CPC for total paid resuls
                  etv integer total estimated traffic to the domain based on organic and paid SERP data in the system
                  date string date of the latest update
                  pos1 integer the number of organic SERP that contain the domain at the first position
                  pos2_3 integer the number of organic SERP that contain the domain at the second and third position
                  pos4_10 integer the number of organic SERP that contain the domain at the 4-10th position
                  pos11_20 integer the number of organic SERP that contain the domain at the 11-20th position
                  pos21_30 integer the number of organic SERP that contain the domain at the 21-30th position
                  pos31_40 integer the number of organic SERP that contain the domain at the 31-40th position
                  pos41_50 integer the number of organic SERP that contain the domain at the 41-50th position
                  pos51_60 integer the number of organic SERP that contain the domain at the 51-60th position
                  pos61_70 integer the number of organic SERP that contain the domain at the 61-70th position
                  pos71_80 integer the number of organic SERP that contain the domain at the 71-80th position
                  pos81_90 integer the number of organic SERP that contain the domain at the 81-90th position
                  pos91_100 integer the number of organic SERP that contain the domain at the 91-100th position
                  paid_pos1 integer the number of paid SERP that contain the domain at the first position
                  paid_pos2_3 integer the number of paid SERP that contain the domain at the second and third position
                  paid_pos4_10 integer the number of paid SERP that contain the domain at the 4-10th position
                  paid_pos11_20 integer the number of paid SERP that contain the domain at the 11-20th position
                  paid_pos21_100 integer the number of paid SERP that contain the domain at the 21-100th position


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
“post data is empty” – specify the parameters for the request
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

Domain Intersection


Using this method, you will receive keywords that any two domains share in organic search. This method allows identifying competing domains through keyword intersections, compare intersecting keyword’s rankings of competing domains and assess the importance of these keywords according to the search volume, competition, and cost-per-click values.

Get Domain Intersection

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

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

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();
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "country_code" => "US",
        "language" => "en",
        "domain1" => "similarweb.com",
        "domain2" => "dataforseo.com",
        "limit" => 3,
        "filters" => array(
            array("domain_1_pos", "<", 10), 
            "and",
            array("url_2", "like", "/pricing%")
        )       
    );

    $get_result = $client->post("v2/kwrd_finder_domain_intersection_get", array('data' => $post_array));
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.9636 sec.",
    "results_count": 1,
    "results": {
        "11913041": {
            "post_id": "11913041",
            "task_id": 20498638,
            "meta": {
                "domain1": "similarweb.com",
                "domain2": "dataforseo.com",
                "country_code": "US",
                "language": "en",
                "limit": 3,
                "offset": 0,
                "orderby": "search_volume,desc",
                "type": "organic",
                "total_count": 7,
                "result_count": 3
            },
            "intersection": [
                {
                    "keyword": "similarweb pricing",
                    "search_volume": 170,
                    "competition": 0.094285,
                    "cpc": 1.60243,
                    "domain_1_pos": 1,
                    "domain_2_pos": 21,
                    "url_1": "https://www.similarweb.com/corp/pricing/",
                    "url_2": "https://dataforseo.com/pricing"
                },
                {
                    "keyword": "similarweb price",
                    "search_volume": 170,
                    "competition": 0.094285,
                    "cpc": 1.60243,
                    "domain_1_pos": 1,
                    "domain_2_pos": 19,
                    "url_1": "https://www.similarweb.com/corp/pricing/",
                    "url_2": "https://dataforseo.com/pricing"
                },
                {
                    "keyword": "similar web pricing",
                    "search_volume": 170,
                    "competition": 0.094285,
                    "cpc": 1.60243,
                    "domain_1_pos": 1,
                    "domain_2_pos": 29,
                    "url_1": "https://www.similarweb.com/corp/pricing/",
                    "url_2": "https://dataforseo.com/pricing"
                }
            ]
        }
    }
}

You can specify the number of results you want to retrieve, filter and sort them.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field. Each array element has the following structure:

Field name Type Description
domain1 string first domain
required field
a domain should be specified without http:// and www
domain2 string second domain
required field
a domain should be specified without http:// and www
country_code string ISO country code
required field
you can receive the list of available locations by making a separate request to the List of Keywords Finder Locations
the location code is specified in the country_code field
or in the List of Locations
the location code is specified in the loc_country_iso_code field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: US
language string language
required field
you can receive the list of available languages by making a separate request to the List of Keywords Finder Locations
the language code is specified in the language field
or in the List of Locations
the language code is specified in the kwrd_finder_lang field;
you can see if it is available for Keywords Finder API in the kwrd_finder: true field
for example: en
intersection boolean intersection mode
optional field
If you specify intersection: true, you will get the keywords for which both domains have results within the same SERP. If you specify intersection:false, you will get only the results for the keywords that present for the first domain only.
default value: true
type string SERP type
can have the following values: organic, paid
default value: organic
limit integer the maximum number of returned keys
default value: 100
maximum value: 1000
offset integer offset in the results array of returned keys
default value: 0
maximum value: 50000
orderby string sorting of results
you can use the following fields to sort the results:
keyword,search_volume, competition, cpc, domain_1_pos, domain_2_pos, url_1, url_2
possible sorting types:
asc, desc
you should specify the rules separating them with a comma
for example:
competition,asc
you can also sort the results according to several fields at once (no more than three sorting rules at a time).
in this case you should specify the rules sets separating them with a semicolon, for example:
search_volume,desc;cpc,desc
the following rule is applied by default:
search_volume,desc
filters array filters array
if you specify a filter, then the three fields mentioned below must be specified
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions, for example:
["cpc", ">", 0]
[["cpc", ">", 0], "and", ["search_volume", "in", [10,20]]]
[["search_volume", ">", 500], "or", [["cpc", ">", 1], "and", ["cpc", "<", 10]]]
      $field string the name of the filtering field
posible filtering parameters:
keyword,search_volume, competition, cpc, domain_1_pos, domain_2_pos, url_1, url_2
      $operator string comparison operator
possible operator parameters:
<, <=, >, >=, =, <>, in, not_in, like, not_like

use the following combination of filtering fields and comparison operators:
keyword,search_volume, competition, cpc, url_1, url_2:
like, not_like, =, <>
search_volume, competition, cpc, domain_1_pos, domain_2_pos:
<, <=, >, >=, =, <>, in, not_in
If you want to filter the results array by the keyword value using like or not_like operators, you can use the following parameters:
["keyword", "like", "seo%"]      any values that start with “seo”
["keyword", "like", "%seo"]      any values that end with “seo”
["keyword", "like", "%seo%"]    any values that contain “seo”

      $value integer/string/array comparison value
use the following combination of comparison operators and data types:
like, not_like, =, <>:    string
<, <=, >, >=, =, <>:       integer
in, not_in:                       array


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

Description of the fields in the results array:

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array (concurrent requests)
results array results array
      post_id string the index in the array received in the POST request
      task_id integer unique task identifier in our system (UInt64)
      meta array options and common task data
            domain1 string the first specified domain
            domain2 string the second specified domain
            country_code string ISO country code
            language string language
            limit integer the maximum number of returned keywords
            offset integer offset in the results array of returned keywords
            orderby string results sorting
            type string SERP type
            total_count integer total amount of results in our database by a specific request
            result_count integer the number of elements in the intersection array by a specific request
      intersection array results array of the intersection array
            keyword string intersecting keyword
            search_volume integer the average search volume
represents the (approximate) number of searches for the given keyword idea on google.com
            competition float competition
represents the relative amount of competition associated with the given keyword idea, in relation to other keywords. Can have values between 0 and 1 inclusive
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword
            domain_1_pos integer position of the first domain in SERP
            domain_2_pos integer position of the second domain in SERP
            url_1 string first URL
the first specified domain’s page ranking for the identified intersecting keyword
            url_2 string second URL
the second specified domain’s page ranking for the identified intersecting keyword


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
“post data is empty” – specify the parameters for the request
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

Suggested Keywords


Using this method, you can get a list of suggested keywords that Google shows in the drop-down list when a user is typing his search query in the address bar of the Google Chrome browser. By default, letters of the English alphabet and numbers (0-9) are being added to your keyword. Therefore, you are getting the full list of all possible variants in which the specified keyword is included.

For example, our system adds all the letters of the Latin alphabet one by one for the keyword ice tea, and after that the same process is repeated with numbers: ice teaice tea aice tea bice tea c … ice tea 1ice tea 2 etc.

As a result, a user gets data similar to the following:

“search_query”: ice tea
“suggestion”: ice tea flavoursice tea rapperice tea south africaiced tea recipeice tea wife

“search_query”: ice tea a
“suggestion”: ice tea actorice tea and cocoice tea and coco babyice tea and vodkaice tea and lemonade

“search_query”: ice tea b
“suggestion”: iced tea brandsice tea benefitsice tea businessiced tea bottling processiced tea brands south africa

“search_query”: ice tea c
“suggestion”: iced tea cocktailsiced tea concentrateiced tea concentrate south africaiced tea caloriesice tea container

“search_query”: ice tea 1
“suggestion”: icetea 1.0icetea 1.3icetea 1.3 pspicetea 1.0 free downloadicetea 1.3 download

“search_query”: ice tea 2
“suggestion”: ice tea 2liced tea 2 quartsiced tea 21 day fixiced tea 2016ice tea 2 go bottle

etc.

Set a task and retrieve the results when our system has them collected. On average, it takes about 15-30 minutes to receive the results.

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

    $post_array = array();
    $my_unq_id = mt_rand(0,30000000); //your unique ID. we will return it with all results. you can set your database ID, string, etc.

    $post_array[$my_unq_id] = array(
        "keyword" => "stone",
        "se_id" => 4790       
    );

    $post_result = $client->post('v2/kwrd_finder_suggest_tasks_post', array('data' => $post_array));
    print_r($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",
    "results_time": "0.0633 sec.",
    "results_count": 1,
    "results": {
        "11913049": {
            "keyword": "stone",
            "post_id": 11913049,            
            "task_id": 7580
        }
    }
}

To set a task, you should specify a keyword. Also, you can add different alphabets or specific symbols from any alphabet.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into the data field.

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
keyword string keyword
required field
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
a keyword should be at least 3 characters long
the keywords will be converted to lowercase format
se_id integer search engine id
optional field, if you specify se_name and se_language
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
also, when the information about set task is returned, you will get the se_id
you must choose a search engine with the word “suggested” included into the “se_name” field
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_name by making a separate request to the List of Search Engines
you must choose a search engine with the word “suggested” included into the “se_name” field
example: “google.com suggested”
se_language string search engine language
optional field if you specify se_id
required field if se_id is not specified
you can get the list of available search engines with se_language by making a separate request to the List of Search Engines
example: “English”
language array alphabet symbols
the default alphabet the letters of which will be added to a keyword is «en»
you can specify a maximum of 3 alphabets at once
shortening of languages is based on the ISO 639-1 standard; possible variants of alphabets:
af, sq, sm, ar, az, eu, be, bn, bh, bs, bg, ca, zh-TW, hr, cs, da, nl, en, eo, et, fo, fi, fr, fy, gl, ka, de, el, gu, iw, hi, hu, is, id, ia, ga, it, ja, jw, kn, ko, la, lv, lt, mk, ms, ml, mt, mr, ne, no, nn, oc, fa, pl, pt-BR, pt-PT, pa, ro, ru, gd, sr, si, sk, sl, es, su, sw, sv, tl, ta, te, th, ti, tr, uk, ur, uz, vi, cy, xh, zu
if you want to specify an alphabet, you should add it to the array, for example:
["en","pl"]
besides an alphabet, numeric symbols will be added by defaul:
1 2 3 4 5 6 7 8 9
if you don’t need numeric symbols, you should specify false value for the numbers parameter
numbers boolean indicates whether the numeric symbols are added to the keyword
numeric characters will be added by default
in case you want to disable it, you should set false for this parameter
symbols array symbols that will be added to a keyword
a maximum of 30 symbols can be added at once
you should specify the symbols that you want to add in the array, for example:
["a","b","c","d","e"]
if you specify the symbols, the numbers and language parameters will be ignored.
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 Suggested Results for obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$task_id’ string as a $task_id variable and ‘$post_id’ as $post_id variable. We will set the necessary values before sending the request. For example:
http://your-server.com/pingscript?taskId=$task_id
http://your-server.com/pingscript?taskId=$task_id&postId=$post_id


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

Description of the fields in the results array:

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


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
“post data is empty” – specify the parameters to set a task
“this task id is used within another function, check the task id” – check if the task_id is relevant to the API you’ve used
“such the task does not exist” – check the task_id of the task
“task id is empty or not valid” – specify the task_id
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.

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_finder_suggest_tasks_get
    $tasks_get_result = $client->get('v2/kwrd_finder_suggest_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.0947 sec.",
    "results_count": 4,
    "results": [
        {
            "task_id": 7734,
            "data": true
        },
        {
            "task_id": 7730,
            "data": true
        },
        {
            "task_id": 7706,
            "data": true
        },
        {
            "task_id": 7702,
            "data": true
        }
    ]
}

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.

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

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array the informational array of the error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array results array of tasks setting
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
      data boolean true – the task is completed, you can collect its results
false – the task wasn’t completed due to an error that occured in the process

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

    $task_id = 473;
    $get_result = $client->get('v2/kwrd_finder_suggest_tasks_get/' . $task_id);
    print_r($get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0871 sec.",
    "results_count": 1,
    "keyword": "stone",
    "task_id": 473,
    "parameters": {
        "se_id": 4802,
        "symbols": [
            "a",
            "b",
            "c"
        ]
    },
    "total_count": 78,
    "suggestions": [
        {
            "number": 1,
            "relevance": 1050,
            "search_query": "stone a",
            "suggestion": "stone age"
        },
        {
            "number": 2,
            "relevance": 602,
            "search_query": "stone a",
            "suggestion": "stone and strand"
        },
        {
            "number": 3,
            "relevance": 600,
            "search_query": "stone a",
            "suggestion": "stone arch bridge"
        },
        {
            "number": 20,
            "relevance": 700,
            "search_query": "stone b",
            "suggestion": "stone brewery"
        },
        {
            "number": 21,
            "relevance": 601,
            "search_query": "stone b",
            "suggestion": "stone bridge"
        },
        {
            "number": 39,
            "relevance": 1250,
            "search_query": "stone",
            "suggestion": "= 6.35029318 kilograms"
        },
        {
            "number": 61,
            "relevance": 750,
            "search_query": "stone c",
            "suggestion": "stone cold lyrics"
        },
        {
            "number": 62,
            "relevance": 602,
            "search_query": "stone c",
            "suggestion": "stone crab"
        },
        {
            "number": 63,
            "relevance": 600,
            "search_query": "stone c",
            "suggestion": "stone creek"
        }
    ]
}

To get the results thst our system has collected, specify the task_id.

As a response of API server, you will receive an array with the list of completed results in the suggestions 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
results_time string execution time, seconds
results_count string the number of elements in the results array
keyword string keyword received in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ is decoded to a space character)
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 fo

parameters array task parameters
total_count integer the number of elements in the suggestions array
suggestions array results array of suggestions
      number integer number in the list
      relevance integer relevance of a keyword from the search_query field
as a rule, the range is 500-2000; the higher the value is, the more relevant is the keyword from the result array
      search_query string generated search query
      suggestion string suggested keyword
keyword suggested by Google for the search_query request


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
“post data is empty” – specify the parameters to set a task
“this task id is used within another function, check the task id” – check if the task_id is relevant to the API you’ve used
“such the task does not exist” – check the task_id of the task
“task id is empty or not valid” – specify the task_id
500 “init error, please contact support” – some internal error.
if you see this type of error, please contact our support team.
We did our best to avoid this type of error.