NAVNavbar
Logo
php python csharp java

Rank Tracker API

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

The simplified data processing flow looks as follows:

The setting of tasks is handled through a few distributed client streams. At the same time, a few other client streams are constantly requesting our service to obtain completed tasks from the queue. This is the most simple method of using Rank Tracker API.

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

For high-priority tasks, results are delivered faster.

Setting Rank Tasks

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

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

$post_array = array();

// example #1 - simplest
// you set only a website URL and a search engine URL.
// This search engine URL string will be searched, compared to our internal parameters
// and used as:
// "se_id", "loc_id", "key_id" ( actual and fresh list can be found here: "se_id":
// https://api.dataforseo.com/v2/cmn_se , "loc_id": https://api.dataforseo.com/v2/cmn_locations ) (see example #3 for details)
// If a task was set successfully, this *_id will be returned in results: 'v2/rnk_tasks_post' so you can use it.
// The setting of a task can fail, if you set not-existent search engine, for example.
// Disadvantages: You cannot work with "map pack", "maps", "mobile"
$my_unq_id = mt_rand(0, 30000000); // your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "site" => "dataforseo.com",
    "url" => "https://www.google.co.uk/search?q=seo%20data%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
);

// example #2 - will return results faster than #1, but is simpler than example #3
// All parameters should be set in the text format.
// All data will be will be searched, compared to our internal parameters
// and used as:
// "se_id", "loc_id", "key_id" ( actual and
// fresh list can be found here: "se_id": https://api.dataforseo.com/v2/cmn_se ,
// "loc_id": https://api.dataforseo.com/v2/cmn_locations )
// If a task was set successfully, this *_id will be returned in results: 'v2/rnk_tasks_post' so you can use it.
// The setting of a task can fail, if you set not-existent search engine, for example.
// Disadvantages: The process of search and comparison of provided data to our internal parameters may take some time.
$my_unq_id = mt_rand(0, 30000000); // your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "site" => "dataforseo.com",
    "se_name" => "google.co.uk",
    "se_language" => "English",
    "loc_name_canonical" => "London,England,United Kingdom",
    "key" => mb_convert_encoding("seo data api", "UTF-8")
    //,"pingback_url" => "http://your-domain.com/pingback_url_example.php?task_id=$task_id" //see pingback_url_example.php script
);

// example #3 - the fastest one. All parameters should be set in our internal format.
// Actual and fresh list can be found here: "se_id": https://api.dataforseo.com/v2/cmn_se ,
// "loc_id": https://api.dataforseo.com/v2/cmn_locations
$my_unq_id = mt_rand(0, 30000000); // your unique ID. we will return it with all results. you can set your database ID, string, etc.
$post_array[$my_unq_id] = array(
    "priority" => 1,
    "site" => "dataforseo.com",
    "se_id" => 22,
    "loc_id" => 1006886,
    "key_id" => 62845222
    //,"postback_url" => "http://your-domain.com/postback_url_example.php" //see postback_url_example.php script
);

// This example has a 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
if (count($post_array) > 0) {
    try {
        // POST /v2/rnk_tasks_post/$tasks_data
        // $tasks_data must by array with key 'data'
        $task_post_result = $client->post('/v2/rnk_tasks_post', array('data' => $post_array));
        print_r($task_post_result);

        //do something with post results

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 3,
    "results": {
        "11913258": {
            "post_id": "11913258",
            "post_key": "seo data api",
            "post_site": "dataforseo.com",
            "task_id": 380342739,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 62845222,
            "status": "ok"
        },
        "11913049": {
            "post_id": "11913049",
            "post_key": "seo data api",
            "post_site": "dataforseo.com",
            "task_id": 380342739,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 62845222,
            "status": "ok"
        },
        "20469414": {
            "post_id": "20469414",
            "post_key": "seo data api",
            "post_site": "dataforseo.com",
            "task_id": 380342741,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 62845222,
            "status": "ok"
        }
    }
}

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

We are positive that you will be able to choose the best-fitting way of task setting.

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. We recommend to set up to 100 tasks at a time. Such limits were set due to the variations of task setting methods that you may use.

If you use the url field, then the processing of each task will take more time. However, if you use our system identifiers (se_id, loc_id, key_id), the processing of tasks will be faster, and you can set more than 100 tasks at a time.

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

Description of the fields for setting a task :

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

site string a domain to find rankings for in SERPs
required field
you can use wildcard (‘*’) character to specify the search pattern in SERP. But if you decide to use a wildcard and include subdomains in the search, then you should also specify it using wildcard.
examples:
“example.com” (search for the exact domain)
“example.com/” (search for the exact URL)
“example.com/eng/*” (search for the example.com domain and all its URLs which start with ‘/eng/’, such as ‘example.com/eng/index.html’ and ‘example.com/eng/help/’, etc.)
*.example.com/eng/*” (search for example.com and all its subdomain with URLs, which start with ‘/eng/’, such as: ‘m.example.com/eng/index.html’ and ‘m.example.com/eng/some_url/’, etc.)
url string direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
se_id integer search engine id
optional field, if you specify se_name
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_id by making a separate request to the List of Search Engines
also, when the information about set task is returned, you will get the se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields: se_id or se_name
you can get the list of available search engines with their se_name by making a separate request to the List of Search Engines
example: “google.co.uk”
se_language string search engine language
required field if se_id is not specified
you can get the list of available search engines with their se_language by making a separate request to the List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you must choose one of the fields: loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_id by making a separate request to the List of Locations
when the information about the set task is returned, you will get loc_id
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Criteria ID in the loc_id field
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields loc_id or loc_name_canonical
you can receive the list of available locations of search engines with their loc_name_canonical by making a separate request to the
List of Locations
please note that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify the appropriate Canonical Name in the loc_name_canonical field
example: “London,England,United Kingdom”
key_id integer keyword id
optional field if you specify key
when you set a task for the first time you won’t be able to know this field. But if you plan to collect rankings for this keyword, we recommend saving the key_id returned after the task was set, and use this field to get the results later on.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”if this field contains ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’ then the charge per task will be multiplied by 10.
se_param_add string additional parameters of search query
optional field
for example, if you want to disable auto-correction of the search query misspelling for google, you should use the “&nfpr=1” parameter
Get the list of available parameters and additional details here.
postback_url string return URL for sending task results
optional field
if you specify the postback URL there will be no need to use Get Rank Tasks Results for obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$task_id’ string as a $task_id variable and ‘$post_id’ as $post_id variable. We will set the necessary values before sending the request. For example:
http://your-server.com/pingscript?taskId=$task_id
http://your-server.com/pingscript?taskId=$task_id&postId=$post_id


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

Here are some examples:

  1. There is an identifier in your system that corresponds to a task that you set to collect data, for example, 100500. When you set the task you send it in the data array with 100500 index, e.g.: "{"data":{"100500":{"priority":1,"se_name":"google.co.uk","se_language":"English","loc_name_canonical":"London,England,United Kingdom","key":"online rank tracker"}}}"
    When you get a result of this task, 100500 will be returned in the post_id field, and you will be able to associate the received result with the task specified in your system.
  2. You may also want to associate other kinds of data in your system. For instance:
    • a keyword has id=1238 at your system,
    • a search engine has id=43289,
    • a location id=97435,
    • a language id=2,
    • a user for whom you want to complete this task has id=9999.

    Since the index of a task in the data array can be specified as a string, you can create this index using any symbol as a delimiter that fits you the most to send the information mentioned above as a post_id. For instance, let’s see how it will look like if we use # as a delimiter. The index that includes all the necessary data will have this value 1238#43289#97435#2#9999. As a result, the request for setting a task will look like this: "{"data":{"1238#43289#97435#2#9999":{"priority":1,"se_name":"google.co.uk","se_language":"English","loc_name_canonical":"London,England,United Kingdom","key":"online rank tracker"}}}"
    When you get the result of this task, you will be able to put in order the string to get the values you need. It will make the integration with our service easier for you.

As a response of 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
      task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
      status string results of this task setting
“ok” – 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
      post_id string the index in the array received in the POST request
      post_site string site received in the POST request
      post_key string key received in the POST request
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
      se_id integer search engine id
if status=“ok”, then this field will be always filled
you can use it for matching your search engines with the DataForSEO List of Search Engines
      loc_id integer search engine location id
if status=“ok”, then this field will always be filled
if status=“ok”, then this field will be always filled
you can use it for matching your search engines with the DataForSEO List of Search Engines
      key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task


Possible error codes:

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

Get Rank Tasks Results

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

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

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

/*
#1 - get ALL ready results
recommended use of getting results:
run this script by cron with 10-60 streams, every minute with random delay 0-30 sec.
usleep(mt_rand(0,30000000));
*/
try {
    //GET /v2/rnk_tasks_get
    $task_get_result = $client->get('v2/rnk_tasks_get');
    print_r($task_get_result);

    //do something with results

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

/*
#2 - get one result by task_id
*/
try {

    // GET /api/v1/tasks_get/$task_id
    $task_get_result = $client->get('v2/rnk_tasks_get/123456789');
    print_r($task_get_result);

    //do something with result

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

$client = null;
?>

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0549 sec.",
    "results_count": 3,
    "results": {
        "organic": [
            {
                "post_id": "11913258",
                "task_id": 380342739,
                "se_id": 22,
                "loc_id": 1006886,
                "key_id": 62845222,
                "post_key": "seo data api",
                "post_site": "dataforseo.com",
                "result_datetime": "2018-03-13 16:18:12 +02:00",
                "result_position": 3,
                "result_url": "https://dataforseo.com/",
                "result_title": "SEO software API ⓴⓲. API for agencies. Best SEO data API provider.",
                "result_snippet_extra": "",
                "result_snippet": "DataForSEO ➤➤➤ SEO Software API ➤➤➤ SEO API data Provider built for SEO-Software companies and agencies. ✓✓✓ Great Speed, Clear Stats, Simple Pricing. Try for free now!",
                "results_count": 11500000,
                "result_extra": "",
                "result_spell": "",
                "result_spell_type": "",
                "result_se_check_url": "https://google.co.uk/search?q=seo%20data%20api&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            },
            {
                "post_id": "11913049",
                "task_id": 380342739,
                "se_id": 22,
                "loc_id": 1006886,
                "key_id": 62845222,
                "post_key": "seo data api",
                "post_site": "dataforseo.com",
                "result_datetime": "2018-03-13 16:18:12 +02:00",
                "result_position": 3,
                "result_url": "https://dataforseo.com/",
                "result_title": "SEO software API ⓴⓲. API for agencies. Best SEO data API provider.",
                "result_snippet_extra": "",
                "result_snippet": "DataForSEO ➤➤➤ SEO Software API ➤➤➤ SEO API data Provider built for SEO-Software companies and agencies. ✓✓✓ Great Speed, Clear Stats, Simple Pricing. Try for free now!",
                "results_count": 11500000,
                "result_extra": "",
                "result_spell": "",
                "result_spell_type": "",
                "result_se_check_url": "https://google.co.uk/search?q=seo%20data%20api&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            },
            {
                "post_id": "20469414",
                "task_id": 380342739,
                "se_id": 22,
                "loc_id": 1006886,
                "key_id": 62845222,
                "post_key": "seo data api",
                "post_site": "dataforseo.com",
                "result_datetime": "2018-03-13 16:18:12 +02:00",
                "result_position": 3,
                "result_url": "https://dataforseo.com/",
                "result_title": "SEO software API ⓴⓲. API for agencies. Best SEO data API provider.",
                "result_snippet_extra": "",
                "result_snippet": "DataForSEO ➤➤➤ SEO Software API ➤➤➤ SEO API data Provider built for SEO-Software companies and agencies. ✓✓✓ Great Speed, Clear Stats, Simple Pricing. Try for free now!",
                "results_count": 11500000,
                "result_extra": "",
                "result_spell": "",
                "result_spell_type": "",
                "result_se_check_url": "https://google.co.uk/search?q=seo%20data%20api&hl=en&gl=GB&gws_rd=cr&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS"
            }
        ],
        "paid": [
        ]
    }
}

You can use three different methods for receiving results:

  1. GET https://api.dataforseo.com/v2/rnk_tasks_get
    you will receive all completed results that have not been collected yet.
  2. GET https://api.dataforseo.com/v2/rnk_tasks_get/$task_id
    after you’ve set a task, there will be a unique identifier returned to you in the response from our service. It is specified in the task_id field. You will be able to use it within 30 days to pick up the results of the task.
  3. When setting a task (Setting Rank Tasks) you’ve specified pingback_url or postback_url. As soon as the task is completed we will send a GET request to the URL you’ve specified as pingback_url or a POST request with its results to the URL you’ve specified as postback_url when the task was set. Watch the video to learn more about using pingbacks and postbacks with DataForSEO APIs.

Description of the fields for sending a request:

Field name Type Description
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


As a response of the API server, you will receive an array in the results field containing rank tracker 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
      organic array results array of organic SERP
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time. You are charged for each GET request for receiving the results.
            post_id string the index of the array received in the POST array
            post_site string site received in the POST array
            post_key string keyreceived in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            se_id integer search engine id
you can use it for matching your search engines with the DataForSEO List of Search Engines
            loc_id integer search engine location id
if status=“ok”, then this field will be always filled
you can use it for matching your search engines with the DataForSEO List of Search Engines
            key_id integer unique keyword identifier in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when setting a task
            result_position integer position in SERP
            result_datetime string date and time when the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
            result_url string relevant URL in SERP
            result_title string snippet header in SERP
            result_snippet_extra string the enhanced snippet in SERP
For example: ratings, price, author, etc
            result_snippet string snippet in SERP
            results_count integer total number of results in SERP
            result_extra string additional (extra) elements in SERP
all extra elements in the string are separated by commas, e.g.: top_stories, featured_snippet, people_also_ask, local_pack, carousel, images, map, video, twitter, app, shopping, google_flights, jobs, answer_box, related_search, knowledge_graph, google_review, mention
            result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
            result_spell_type string type of auto-correction
types of hints: did_you_mean, showing_results_for, no_results_found_for
            result_se_check_url string direct URL to search engine results
You can use it to make sure that we provided exact results
      paid array results array of paid SERP
this array will be available in the future
as for now, all the data in this field will always have an empty array
            task_id integer unique task identifier in our system (UInt64)
you will be able to use it within 30 days to request the results of the task at any time
            post_id string the index of the array received in the POST array
            post_site string site received in the POST array
            post_key string key received in the POST array
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            se_id integer search engine id
you can use it for matching your search engines with the DataForSEO List of Search Engines
            loc_id integer search engine location id
you can use it for matching your search engines with the DataForSEO List of Search Engines
            key_id integer keyword id in our system
if you plan to use this keyword in the future we recommend you to save this id and use it as key_id when you setting a task
            result_position integer position in SERP
            result_datetime string date and time when the result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified in your profile settings is used
            result_url string relevant URL in SERP
            result_title string snippet header in SERP
            result_snippet_extra string the enhanced snippet in SERP
For example: ratings, price, author, etc
            result_snippet string snippet in SERP
            results_count integer total number of results in SERP
             result_extra string additional (extra) elements in SERP
all extra elements in the string are separated by commas, e.g.: top_stories, featured_snippet, people_also_ask, local_pack, carousel, images, map, video, twitter, app, shopping, google_flights, jobs, answer_box, related_search, knowledge_graph, google_review, mention
            result_spell string search engine auto-correction
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine
            result_spell_type string type of auto-correction
types of hints: did_you_mean, showing_results_for, no_results_found_for
            result_se_check_url string direct URL to search engine results
you can use it to make sure that we provided exact results