NAVNavbar
Logo
php python csharp java

Common API

Here we’ve collected datasources that you’ll need to use to work with DataForSEO APIs effectively.

List of Search Engines

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

    $se_get_result = $client->get('v2/cmn_se');
    print_r($se_get_result);

    //do something with se

} 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.0339 sec.",
    "results_count": 2127,
    "results": [
        {
            "se_id": 37,
            "se_name": "google.com.af",
            "se_country_iso_code": "AF",
            "se_country_name": "Afghanistan",
            "se_language": "Pashto",
            "se_localization": "ps-af"
        },
        {
            "se_id": 1444,
            "se_name": "google.com.af map pack",
            "se_country_iso_code": "AF",
            "se_country_name": "Afghanistan",
            "se_language": "Pashto",
            "se_localization": "ps-af"
        },

        {
            "se_id": 2122,
            "se_name": "google.co.zw news",
            "se_country_iso_code": "ZW",
            "se_country_name": "Zimbabwe",
            "se_language": "Zulu",
            "se_localization": "zu-zw"
        }
    ]
}

By calling this API, you will receive the list of search engines you can use with Rank Tracker API and SERP API.

As a response of the API server you will get the JSON array in the results field of which there will be the information about available search engines.

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array informational array of the error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string number of elements in the  results array
results array array of search engines
            se_id integer search engine id
            se_name string search engine domain
            se_country_name string country for the search engine
            se_country_iso_code string ISO country code for the search engine
            se_language string language for the search engine
            se_localization string locale (search engine language + language of the search engine interface)

List of Locations

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

    $loc_get_result = $client->get('v2/cmn_locations');
    print_r($loc_get_result);

    //do something with locations

} 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.0392 sec.",
    "results_count": 44932,
    "results": [
        {
            "loc_id": 2020,
            "loc_id_parent": null,
            "loc_name": "Andorra",
            "loc_name_canonical": "Andorra",
            "loc_type": "Country",
            "loc_country_iso_code": "AD",
            "dma_region": false,
            "kwrd_finder": false,
            "kwrd_finder_lang": ""
        },

        {
            "loc_id": 2840,
            "loc_id_parent": null,
            "loc_name": "United States",
            "loc_name_canonical": "United States",
            "loc_type": "Country",
            "loc_country_iso_code": "US",
            "dma_region": false,
            "kwrd_finder": true,
            "kwrd_finder_lang": "en"
        },

        {
            "loc_id": 200662,
            "loc_id_parent": 21176,
            "loc_name": "Abilene-Sweetwater, TX",
            "loc_name_canonical": "Abilene-Sweetwater, TX,Texas,United States",
            "loc_type": "DMA Region",
            "loc_country_iso_code": "US",
            "dma_region": true,
            "kwrd_finder": false,
            "kwrd_finder_lang": ""
        },

        {
           "loc_id": 9070777,
           "loc_id_parent": 20036,
           "loc_name": "0812",
           "loc_name_canonical": "0812,Northern Territory,Australia",
           "loc_type": "Postal Code",
           "loc_country_iso_code": "AU",
           "dma_region": false,
           "kwrd_finder": false,
           "kwrd_finder_lang": ""
       },

        {
            "loc_id": 2716,
            "loc_id_parent": null,
            "loc_name": "Zimbabwe",
            "loc_name_canonical": "Zimbabwe",
            "loc_type": "Country",
            "loc_country_iso_code": "ZW",
            "dma_region": false,
            "kwrd_finder": false,
            "kwrd_finder_lang": ""
        }
    ]
}

By calling this API you will receive the list of locations available for use with Rank Tracker APISERP API and Keywords Data API (‘Postal Code’ not supported).

Due to the big volume of data included in the response, we recommend using compression to get the list of locations. The link will look as follows: https://api.dataforseo.com/v2/cmn_locations.gzip

We use Google Geographical Targeting, that’s why you can use it as a data source. To choose a location use gadw_Target_Type that is relevant ‘Autonomous Community’, ‘Borough’, ‘City’, ‘Country’, ‘County’, ‘Governorate’, ‘Municipality’, ‘Postal Code’, ‘Prefecture’, ‘Province’, ‘Region’, ‘State’, ‘Territory’, ‘Union Territory’. Please note ‘Postal Code’ is not supported in Keywords Data API.

You can also download the full list of supported locations in the CSV format, (last updated 2019-08-20).

The keywords are retrieved through the GET method with the following parameters:

Field name Type Description
country_iso_code string ISO country code
optional field
ISO country code which will be used for filtering


As a response of the API server you will get a JSON array in the results field of which there will be the information about available locations.

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the errorarray for more details
error array informational array about error
only if status=“error”
the list of possible errors can be found below
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string number of elements in the results array
results array array of locations
            loc_id integer location id
            loc_id_parent integer parent location id
            loc_name string location name
            loc_name_canonical string full name of the location
            loc_type string location type
            loc_country_iso_code string ISO country code of the location
            dma_region boolean location can be used as a DMA Region
            kwrd_finder boolean a location can be used in Keywords Finder API
            kwrd_finder_lang string languages that can be used in Keywords Finder API for this location

List of Keywords Finder Locations

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

    $status_result = $client->get('v2/cmn_locations_stat_kwrd_finder');
    print_r($status_result);

    //do something with the 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.7730 sec.",
    "results_count": 6,
    "results": [
        {
            "loc_id": 2840,
            "loc_name_canonical": "United States",
            "country_code": "US",
            "language": "en",
            "count": 158397916
        },
        {
            "loc_id": 2826,
            "loc_name_canonical": "United Kingdom",
            "country_code": "GB",
            "language": "en",
            "count": 31516738
        },
        {
            "loc_id": 2276,
            "loc_name_canonical": "Germany",
            "country_code": "DE",
            "language": "de",
            "count": 22880504
        },
        {
            "loc_id": 2392,
            "loc_name_canonical": "Japan",
            "country_code": "JP",
            "language": "ja",
            "count": 18259682
        },
        {
            "loc_id": 2124,
            "loc_name_canonical": "Canada",
            "country_code": "CA",
            "language": "en",
            "count": 16954179
        },
        {
            "loc_id": 2250,
            "loc_name_canonical": "France",
            "country_code": "FR",
            "language": "fr",
            "count": 16789621
        }
    ]
}

As a response of the API server you will get a JSON array in the results field of which there will be the information about available locations and count of keywords in the Keywords Finder API.

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array informational array of the error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string number of elements in the results array
results array array of Keywords Finder API locations
            loc_id integer location id
            loc_name_canonical string location canonical name
            country_code string ISO country code of location
value can be used in the country_code field to get results via Keywords Finder API
            language string language for this location
value can be used in the language field to get results via Keywords Finder API
            count integer count of keywords in our database

List of Clickstream Locations

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

    $status_result = $client->get('v2/cmn_locations_clickstream');
    print_r($status_result);

    //do something with the 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.7730 sec.",
    "results_count": 5,
    "results": [
        {
            "loc_id": 2840,
            "loc_name_canonical": "United States",
            "country_code": "US"
        },
        {
            "loc_id": 2826,
            "loc_name_canonical": "United Kingdom",
            "country_code": "GB"
        },
        {
            "loc_id": 2276,
            "loc_name_canonical": "Germany",
            "country_code": "DE"
        },
        {
            "loc_id": 2124,
            "loc_name_canonical": "Canada",
            "country_code": "CA"
        },
        {
            "loc_id": 2250,
            "loc_name_canonical": "France",
            "country_code": "FR"
        }
    ]
}

As a response of the API server you will get a JSON array in the results field of which there will be information about available locations and count of keywords in Clickstream Keywords Data API.

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array informational array of the error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string the number of elements in the results array
results array array of clickstream locations
            loc_id integer location id
            loc_name_canonical string location canonical name
            country_code string ISO country code of location

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

    $key_get_result = $client->get('v2/cmn_key_id/online%20rank%20checker');
    print_r($key_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.0115 sec.",
    "results_count": 1,
    "results": [
        {
            "key_id": 1095202
        }
    ]
}

You can receive keyword’s key_id from our database (if there is no such keyword, it will be added and key_id created and returned). You will be able to use the returned key_id in Rank Tracker API and SERP API. Keyword’s key_id is unique and can’t be changed.

As a response of the API server you will receive a JSON array in the results field of which there will be the array of this keyword’s key_id.

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string number of the elements in the results array
results array array of keyword id integers
            key_id integer keyword id

User

Instead ‘login’ and ‘password’ use your credentials.

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

    $user_get_result = $client->get('v2/cmn_user');
    print_r($user_get_result);

    //do something with the 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.0173 sec.",
    "results_count": 1,
    "results": [
        {
            "login": "superlogin",
            "timezone": "Europe\/London",
            "rate_limit_per_minute": 1000,
            "rate": 1,
            "rate_max": 123,
            "credit": 99999999,
            "balance": 99987531.5,
            "count_total": 12467.5,
            "count_rnk": 1466,
            "count_srp": 9149.5,
            "count_kwrd": 3047,
            "count_pg": 0,
            "count_cmp": 0,
            "price": {
                "apiRnk": {
                    "rnk_tasks_post": {
                        "priority_low": {
                            "price_type": "per_result",
                            "price": 1
                        },
                        "priority_normal": {
                            "price_type": "per_result",
                            "price": 1
                        },
                        "priority_high": {
                            "price_type": "per_result",
                            "price": 2
                        },
                        "priority_vip": {
                            "price_type": "per_result",
                            "price": 5
                        }
                    }
                },
                "apiSrp": {
                    "srp_tasks_post": {
                        "priority_low": {
                            "price_type": "per_result",
                            "price": 0
                        },
                        "priority_normal": {
                            "price_type": "per_result",
                            "price": 0
                        },
                        "priority_high": {
                            "price_type": "per_result",
                            "price": 2
                        },
                        "priority_vip": {
                            "price_type": "per_result",
                            "price": 5
                        }
                    },
                    "srp_100": {
                        "priority_low": {
                            "price_type": "per_request",
                            "price": 1
                        },
                        "priority_normal": {
                            "price_type": "per_request",
                            "price": 1
                        },
                        "priority_high": {
                            "price_type": "per_request",
                            "price": 1
                        },
                        "priority_vip": {
                            "price_type": "per_request",
                            "price": 1
                        }
                    },
                    "srp_tasks_get": {
                        "priority_low": {
                            "price_type": "per_request",
                            "price": 1
                        },
                        "priority_normal": {
                            "price_type": "per_request",
                            "price": 1
                        },
                        "priority_high": {
                            "price_type": "per_request",
                            "price": 1
                        },
                        "priority_vip": {
                            "price_type": "per_request",
                            "price": 1
                        }
                    }
                },
                "apiKwrd": {
                    "kwrd_for_domain": {
                        "priority_low": {
                            "price_type": "per_request",
                            "price": 100
                        },
                        "priority_normal": {
                            "price_type": "per_request",
                            "price": 100
                        },
                        "priority_high": {
                            "price_type": "per_request",
                            "price": 100
                        },
                        "priority_vip": {
                            "price_type": "per_request",
                            "price": 100
                        }
                    },
                    "kwrd_sv": {
                        "priority_low": {
                            "price_type": "per_result",
                            "price": 5
                        },
                        "priority_normal": {
                            "price_type": "per_result",
                            "price": 5
                        },
                        "priority_high": {
                            "price_type": "per_result",
                            "price": 5
                        },
                        "priority_vip": {
                            "price_type": "per_result",
                            "price": 5
                        }
                    }
                },
                "apiCmp": {
                    "cmp_get": {
                        "priority_low": {
                            "price_type": "per_request",
                            "price": 10
                        },
                        "priority_normal": {
                            "price_type": "per_request",
                            "price": 10
                        },
                        "priority_high": {
                            "price_type": "per_request",
                            "price": 10
                        },
                        "priority_vip": {
                            "price_type": "per_request",
                            "price": 10
                        }
                    }
                },
                "apiMtr": {
                    "mtr_moz_post": {
                        "priority_low": {
                            "price_type": "per_result",
                            "price": 1
                        },
                        "priority_normal": {
                            "price_type": "per_result",
                            "price": 1
                        },
                        "priority_high": {
                            "price_type": "per_result",
                            "price": 2
                        },
                        "priority_vip": {
                            "price_type": "per_result",
                            "price": 5
                        }
                    },
                    "mtr_maj_post": {
                        "priority_low": {
                            "price_type": "per_result",
                            "price": 1
                        },
                        "priority_normal": {
                            "price_type": "per_result",
                            "price": 1
                        },
                        "priority_high": {
                            "price_type": "per_result",
                            "price": 2
                        },
                        "priority_vip": {
                            "price_type": "per_result",
                            "price": 5
                        }
                    }
                }
            }
        }
    ]
}

As a response of the API server you will get a JSON array in the results field of which there will be information about the current user.

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”,check the error array for more details
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string number of elements in the  results array
results array array of details about the current user
      login string your login
      timezone string your time zone
can be set in the settings of your profile
      rate_limit_per_minute integer limit of any requests per minute
this limit is used for load balancing on our servers
      rate integer current number of requests per a minute
      rate_max integer maximum number of requests per minute for last 24 hours
      credit integer total amount of credits passed to your account
      balance integer current balance of your account
creditcount_total
      count_total integer total amount of spent credits
count_rnk+count_srp+count_kwrd+count_pg
      count_rnk integer amount of credits spent on Rank Tracker API
      count_srp integer amount of credits spent on SERP API
      count_kwrd integer amount of credits spent on Keywords Data API
      count_pg integer amount of credits spent on On-Page API
      price array
         $api array API abbreviation
         $api_function array API function
         $priority array task priority
         price_type string charge type
can take the following values:
per_result – charge for every row in result array
per_request – charge for GET or POST request
         price string the cost in credits

Get AdWords Status

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

    $status_result = $client->get('v2/cmn_adwords_status');
    print_r($status_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.0339 sec.",
    "results_count": 1,
    "results": [
        {
            "actual_data": true
        }
    ]
}

As a response of the API server you will get a JSON array in the results field of which there will be the information about status relevance of the keywords Google AdWords API returned.

Field name Type Description
status string general result
“ok” – successful
“error” – error
if status=“error”, check the error array for more details
error array informational array about error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string number of elements in the results arrays
results array arrays with the Google Ads (AdWords) status
            actual_data boolean true – if the information is actual, false – otherwise