NAV Navbar
Logo
php csharp python

Introduction

Welcome to DataForSEO API!

DataForSEO API uses REST technology for interchanging data between your application and our service. The data exchange is made by the HTTP protocol. The benefit of this method is widespread occurrence of the HTTP protocol that’s why REST API can be used almost for all programming languages.

You can create REST class by yourself or find ready to use ones to use this technology. We can provide you with ready to use classes:

Language Description
PHP Simple Rest Client PHP REST Client build with cURL. Author Fabio Agostinho Boris.
Python Simple Rest Client Python REST Client. Author DataForSEO.
C# DataForSEO Client C# DataForSEO Ready Client. Author DataForSEO.

We will show PHP and Python examples of these classes usage.

You can download usage examples from our website:

Language Description
PHP Examples PHP examples.
Python Examples Python examples.
C# Examples C# examples.
POSTMAN Examples POSTMAN examples.
POSTMAN Documenter Online POSTMAN Documenter.

All data exchange should be UTF-8 encoded.

Also, all responses of our service are returned in the JSON format by default. We also support responses in the XML format. For this, in the end of the request you should specify .xml.

For example,
https://api.dataforseo.com/v2/cmn_user.xml
instead of the standard
https://api.dataforseo.com/v2/cmn_user

Authentication

To authorize, use this code:

<?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/login
    $client = new RestClient('https://api.dataforseo.com/', null, 'login', 'password');

    //do something

} 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();
}
?>
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task cmn_key_id()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };

            // do something
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")

#do something

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

First of all, you should register at our service and then you will be able to use your login and password to start using our API service.

DataForSEO API uses technology Basic Authentication.

It provides you with a possibility to use our API almost for all programming languages.

Rank Tracker API

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

The data will look like:

The tasks setting is made by few clients streams. At the same time few other clients streams constantly request our service to pick completed tasks from queue.

It is the most simplified and widespread method of work with Rank Tracker API.

You also can receive results of completed tasks using task_id or we can send them by ourselves as soon as they are ready if you specify postback_url or pingback_url when setting a task.

The time of results delivery depends on task priority and overall system load. Usually, it takes a short time (2 minutes on average per day). However, it might be longer in the span of 1 a.m. to 6 a.m. GMT.

The time of results delivery is less for those tasks which priority is high.

Setting Rank Tasks

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

<?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/login
    $client = new RestClient('https://api.dataforseo.com/', null, 'login', 'password');
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
    exit();
}


$post_array = array();

//for example, some data selection cycle for tasks
for ($i = 0; $i < 3; $i++) {

    // example #1 - the simplest one
    // 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
    $post_array[$my_unq_id] = array(
    "priority" => 1,
    "site" => "ranksonic.com",
    "url" => "https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
    );

    // 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 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. will be returned with all results
    $post_array[$my_unq_id] = array(
    "priority" => 1,
    "site" => "ranksonic.com",
    "se_name" => "google.co.uk",
    "se_language" => "English",
    "loc_name_canonical"=> "London,England,United Kingdom",
    "key" => mb_convert_encoding("online rank checker", "UTF-8")
    );

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

    //This example has a cycle of up to 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
    if (count($post_array) > 99) {
        try {
            // POST /v2/rnk_tasks_post/$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";
        }
    }
}

if (count($post_array) > 0) {
    try {
        // POST /v2/rnk_tasks_post/$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

    } 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;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task rnk_tasks_post()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var rnd = new Random();
            var postObject = new Dictionary<int, object>
            {
                [rnd.Next(1, 30000000)] = new
                {
                    priority = 1,
                    site = "ranksonic.com",
                    url = "https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
                },
                [rnd.Next(1, 30000000)] = new
                {
                    priority = 1,
                    site = "ranksonic.com",
                    se_name = "google.co.uk",
                    se_language = "English",
                    loc_name_canonical = "London,England,United Kingdom",
                    key = "online rank checker"
                },
                [rnd.Next(1, 30000000)] = new
                {
                    priority = 1,
                    site = "ranksonic.com",
                    se_id = 22,
                    loc_id = 1006886,
                    key_id = 1095202
                }
            };
            var taskPostResponse = await httpClient.PostAsync("v2/rnk_tasks_post", new StringContent(JsonConvert.SerializeObject(new { data = postObject })));
            var obj = JsonConvert.DeserializeObject<dynamic>(await taskPostResponse.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
            {
                foreach (var result in obj.results)
                {
                    var taskState = ((IEnumerable<dynamic>)result).First();
                    if (taskState.status == "error")
                        Console.WriteLine($"Error in task with post_id {taskState.post_id}. Code: {taskState.error.code} Message: {taskState.error.message}");
                    Console.WriteLine(taskState);
                }
            }
        }
    }
}
from random import Random
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")
rnd = Random()
post_data = dict()
post_data[rnd.randint(1, 30000000)] = dict(
    priority=1,
    site="ranksonic.com",
    url="https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
)
post_data[rnd.randint(1, 30000000)] = dict(
    priority=1,
    site="ranksonic.com",
    se_name="google.co.uk",
    se_language="English",
    loc_name_canonical="London,England,United Kingdom",
    key="online rank checker"
)
post_data[rnd.randint(1, 30000000)] = dict(
    priority=1,
    site="ranksonic.com",
    se_id=22,
    loc_id=1006886,
    key_id=1095202
)

response = client.post("/v2/rnk_tasks_post", dict(data=post_data))
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 9,
    "results": {
        "11913049": {
            "post_id": 11913049,
            "post_key": "",
            "post_site": "ranksonic.com",
            "task_id": 404227822,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "20469414": {
            "post_id": 20469414,
            "post_key": "online rank checker",
            "post_site": "ranksonic.com",
            "task_id": 404227823,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "6273173": {
            "post_id": 6273173,
            "post_key": "",
            "post_site": "ranksonic.com",
            "task_id": 404227824,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "27408598": {
            "post_id": 27408598,
            "post_key": "",
            "post_site": "ranksonic.com",
            "task_id": 404227825,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "19840083": {
            "post_id": 19840083,
            "post_key": "online rank checker",
            "post_site": "ranksonic.com",
            "task_id": 404227826,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "6054604": {
            "post_id": 6054604,
            "post_key": "",
            "post_site": "ranksonic.com",
            "task_id": 404227827,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "8626195": {
            "post_id": 8626195,
            "post_key": "",
            "post_site": "ranksonic.com",
            "task_id": 404227828,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "18786140": {
            "post_id": 18786140,
            "post_key": "online rank checker",
            "post_site": "ranksonic.com",
            "task_id": 404227829,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "13056693": {
            "post_id": 13056693,
            "post_key": "",
            "post_site": "ranksonic.com",
            "task_id": 404227830,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        }
    }
}

When we were developing the mechanism of tasks 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 tasks settings it may seem that the process is difficult, but the things are simpler than you think.

We are sure that you will be able to pick the way of task setting that fits you the most.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using POST method when array of tasks is sent in data field. We recommend to set up to 100 tasks at a time. Such limit was set because of the variations of tasks settings that you will use. If you use the field url then the processing of each task will take more time. If you use our identifiers (se_id, loc_id, key_id) then the processing of tasks will be made faster and you can set more than 100 elements at a time. Each of array elements has such structure:

Name of a field Type Description
priority integer execution priority
optional field
can have such values:
1 - normal execution priority (set by default)
2 - high execution priority
site string a website domain which rankings should be searched for in the SERP
required field
you can use wildcard (‘*’) to specify the search mask in the SERP. But if you decide to use a wildcard and want to include subdomains to the search then you should also specify it using wildcard.
examples:
   “example.com” (standard search)
   “example.com/eng/*” (search example.com and URLs which start with ‘/eng/’ in the SERP, such as ‘example.com/eng/index.html’ and ‘example.com/eng/help/’ etc)
   “*.example.com/eng/*” (search example.com and all its subdomain with URLs which start with ‘/eng/’ in the SERP such as ‘m.example.com/eng/index.html’ and ‘example.com/eng/some_url/’ etc.)
url string direct URL of a search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Such method is the most difficult for our API processing and you should exactly specify language and location in the URL. We don’t recommend to use this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20
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
the list of available search engines with their se_id you can get by separate request List of Search Engines
also, when the information about set task is returned you will get se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields se_id or se_name
the list of available search engines with se_name you can get by separate request List of Search Engines
example: “google.co.uk”
se_language string search engine language
required field if se_id is not specified
the list of available search engines with their se_language you can get by separate request List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you must choose one of the fields loc_id or loc_name_canonical
the list of available locations of search engines with their loc_id you can receive by separate request List of Locations
when the information about set task is returned you will get loc_id
please notice that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify in the field loc_id appropriate Criteria ID
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields loc_id or loc_name_canonical
the list of available locations of search engines with their loc_name_canonical you can receive by separate request List of Locations
please notice that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify in the field loc_name_canonical approriate to Canonical Name
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 you to save key_id returned after the task was set and use this field in the future.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”.

if this field contains ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘cache:’, ‘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 misspelling in the search query for google, you can specify “&nfpr=1”
postback_url string return URL for sending task results
optional field
if you specify this URL there will be no need to pick up tasks using Get Rank Tasks Results. We will send a result of a completed task by POST request for URL as soon as a task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use string ‘$task_id’ as $task_id variable and ‘$post_id’ as $post_id variable. we will set necessary values before sending of a request. for example:
  http://your-server.com/pingscript?taskId=$task_id
  http://your-server.com/pingscript?taskId=$task_id&postId=$post_id

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

Here are some examples:

  1. There is an identifier at your system of a task that you set to collect data, let it be 100500. When you set the task you send it in the data array with 100500 index like here: "{"data":{"100500":{"priority":1,"site":"ranksonic.com","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 at your system.
  2. You want to associate other kinds of data at your system. For instance:
    • a keyword has id=1238 at your system,
    • a search engine id=43289,
    • a location id=97435,
    • a language id=2,
    • a user for whom you want to complete this task has id=9999.

    Since the index of a task in the data array can be specified as a string, you can create this index using any symbol as a delimiter that fits you most to send the information mentioned above as a post_id. For instance, let’s see how it will look like if we use # as a delimiter. The index that includes all necessary data will have this value 1238#43289#97435#2#9999. As a result, the request for setting of a task will look like this: "{"data":{"1238#43289#97435#2#9999":{"priority":1,"site":"ranksonic.com","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 API server you will receive JSON array in the field results of which there will be an information appropriate to the set tasks.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information of array error error
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the array of results results
results array results array of tasks setting
            task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time.
            status string results of this task setting
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information of array error error
            error array informational array of error
only if status=“error”
the list of possible errors can be found below.
                  code integer error code
                  message string text description of an error
            post_id string index in the array received in a POST request
            post_site string site received in a POST request
            post_key string key received in a POST request
if you send key_id without passing key it will be empty
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 finding relations between your and our search engines.
            loc_id integer search engine location id
if status=“ok”, then this field will always be filled
You can use it for finding relations between your and our 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 when you set a task as key_id

Possible errors 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 nonexistent se_id or a search engine wasn’t found by specified se_name
404 “not found or not enough data: location” - you’ve specified nonexistent loc_id or a location of a search engine wasn’t found by specified loc_name_canonical
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 field data. POST data should be represented as an array and added to the field data: array(‘data’ => $post_array_for_tasks)
501 “invalid data” - Data in the field data isn’t an array with the required structure.
500 “internal error” - some internal error. We did our best to not let this type of error ever happen.

Get Rank Tasks Results

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

<?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/login
    $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;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task rnk_tasks_get()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = {Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}
            };

            var response = await httpClient.GetAsync("v2/rnk_tasks_get");
            var obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else if (obj.results_count != 0)
            {
                foreach (var result in obj.results)
                {
                    var resultItem = ((IEnumerable<dynamic>) result).First();
                    Console.WriteLine(resultItem);
                }
            }
            else
                Console.WriteLine("no results");

            var taskid = 123456789;
            response = await httpClient.GetAsync($"v2/rnk_tasks_get/{taskid}");
            obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else if (obj.results_count != 0)
            {
                foreach (var result in obj.results)
                {
                    var resultItem = ((IEnumerable<dynamic>)result).First();
                    Console.WriteLine(resultItem);
                }
            }
            else
                Console.WriteLine("no results");
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")
response = client.get("/v2/rnk_tasks_get")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0549 sec.",
    "results_count": 3,
    "results": {
        "organic": [
            {
                "post_id": 2833944,
                "task_id": 405460981,
                "se_id": 22,
                "loc_id": 1006886,
                "key_id": 1095202,
                "post_key": null,
                "post_site": "ranksonic.com",
                "result_datetime": "2016-12-13 15:33:07 +02:00",
                "result_position": 2,
                "result_url": "https:\/\/ranksonic.com\/",
                "result_title": "RankSonic ⓴⓰ - Rank Tracking SEO software. Website ranking SEO ...",
                "result_snippet_extra": "Rating: 4.6 - ‎6,054 reviews",
                "result_snippet": "⓴⓰ Rank Tracking SEO Software - Keyword Google online search engine seo \n... Check what potential your keywords have to evaluate their competition level.",
                "results_count": 4690000,
                "result_extra": "videos",
                "result_spell": "",
                "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
            },
            {
                "post_id": 22195544,
                "task_id": 405460979,
                "se_id": 22,
                "loc_id": 1006886,
                "key_id": 1095202,
                "post_key": "online rank checker",
                "post_site": "ranksonic.com",
                "result_datetime": "2016-12-13 15:32:58 +02:00",
                "result_position": 2,
                "result_url": "https:\/\/ranksonic.com\/",
                "result_title": "RankSonic ⓴⓰ - Rank Tracking SEO software. Website ranking SEO ...",
                "result_snippet_extra": "Rating: 4.6 - ‎6,054 reviews",
                "result_snippet": "⓴⓰ Rank Tracking SEO Software - Keyword Google online search engine seo \n... Check what potential your keywords have to evaluate their competition level.",
                "results_count": 4810000,
                "result_extra": "videos",
                "result_spell": "",
                "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
            },
            {
                "post_id": 9084390,
                "task_id": 405460980,
                "se_id": 22,
                "loc_id": 1006886,
                "key_id": 1095202,
                "post_key": null,
                "post_site": "ranksonic.com",
                "result_datetime": "2016-12-13 15:32:58 +02:00",
                "result_position": 2,
                "result_url": "https:\/\/ranksonic.com\/",
                "result_title": "RankSonic ⓴⓰ - Rank Tracking SEO software. Website ranking SEO ...",
                "result_snippet_extra": "Rating: 4.6 - ‎6,054 reviews",
                "result_snippet": "⓴⓰ Rank Tracking SEO Software - Keyword Google online search engine seo \n... Check what potential your keywords have to evaluate their competition level.",
                "results_count": 4690000,
                "result_extra": "videos",
                "result_spell": "",
                "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
            }
        ],
        "paid": [
        ]
    }
}

You can receive results in three different ways:

  1. GET https://api.dataforseo.com/v2/rnk_tasks_get
    you will receive all complete results that have not been picked up.
  2. GET https://api.dataforseo.com/v2/rnk_tasks_get/$task_id
    after you’ve set a task there will be unique identifier returned to you in the response of our service. It is specified in the field task_id. You will be able to use it within 30 days to pick 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 GET request to the URL you’ve specified as pingback_url or POST request with its results to the URL you specified as postback_url when the task was set.

You will receive array from the API server in the field results where you will find rank tracker results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information of array error error
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the array of results results
results array results array of tasks
      organic array results array of organic SERP
            task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time.
            post_id string index in the array received in a POST array
            post_site string site received in a POST array
            post_key string keyreceived in a POST array
if you send key_id without passing keyit will be empty
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 finding relations between your and our search engines.
            loc_id integer search engine location id
You can use it for finding relations between your and our 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 when you set a task as key_id
            result_position integer position in the SERP
            result_datetime string date and time when a result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
time zone specified at your profile settings is used
            result_url string relevant URL in the SERP
            result_title string snippet header in the SERP
            result_snippet_extra string additional snippet in the SERP
ratings, price, author, etc
            result_snippet string snippet in the SERP
            results_count integer total number of results in the SERP
            result_extra string additional elements in the SERP
you can see such items separated by commas: app, blog, books, carousel, definition_block, discussions, images, knowledge_graph, maps, news, patents, places, recipes, shopping, videos
            result_spell string auto correction of a search engine
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engine
            result_se_check_url string direct URL to search engine results
You can use it to make sure that we provide exact results
      paid array results array of paid SERP
It will be available in the future, for now all the data in this field will always have empty array.
            task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time.
            post_id string index in the array received in a POST array
            post_site string site received in a POST array
            post_key string keyreceived in a POST array
if you send key_id without passing keyit will be empty
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 finding relations between your and our search engines.
            loc_id integer search engine location id
You can use it for finding relations between your and our 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 when you set a task as key_id
            result_position integer position in the SERP
            result_datetime string date and time when a result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
time zone specified at your profile settings is used
            result_url string relevant URL in the SERP
            result_title string snippet header in the SERP
            result_snippet_extra string additional snippet in the SERP
ratings, price, author, etc
            result_snippet string snippet in the SERP
            results_count integer total number of results in the SERP
            result_extra string additional elements in the SERP
you can see such items separated by commas: app, blog, books, carousel, definition_block, discussions, images, knowledge_graph, maps, news, patents, places, recipes, shopping, videos
            result_spell string auto correction of a search engine
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engine
            result_se_check_url string direct URL to search engine results
You can use it to make sure that we provide exact results

SERP API

SERP API provides you with a possibility to receive SERP (Top 100) results of specified search engines according to a certain keyword.

The operating principle of SERP API is similar to Rank Tracker API. The main difference is that you don’t receive all complete results at once - you receive a list of task_id which results are complete, after you can receive each result separately. This is due to the fact that each of tasks has huge data amount.

The time of results delivery depends on task priority and overall system load. Usually, it takes a short time (2 minutes on average per day). However, it might be longer in the span of 1 a.m. to 6 a.m. GMT.

The time of results delivery is less for those tasks which priority is high.

Setting SERP Tasks

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

<?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/login
    $client = new RestClient('https://api.dataforseo.com/', null, 'login', 'password');
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP code: {$e->getHttpCode()}\n";
    print "Error code: {$e->getCode()}\n";
    print "Message: {$e->getMessage()}\n";
    print  $e->getTraceAsString();
    echo "\n";
    exit();
}


$post_array = array();

//for example, some data selection cycle for tasks
for ($i = 0; $i < 3; $i++) {

    // 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,
    "url" => "https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
    );

    // 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,
    "se_name" => "google.co.uk",
    "se_language" => "English",
    "loc_name_canonical"=> "London,England,United Kingdom",
    "key" =>  mb_convert_encoding("online rank checker", "UTF-8")
    );

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

    //This example has a cycle of up to 3 elements, but in the case of large number of tasks - send up to 100 elements per POST request
    if (count($post_array) > 99) {
        try {
            // POST /v2/srp_tasks_post/$data
            // $tasks_data must by array with key 'data'
            $task_post_result = $client->post('v2/srp_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";
        }
    }
}

if (count($post_array) > 0) {
    try {
        // POST /v2/srp_tasks_post/$data
        // $tasks_data must by array with key 'data'
        $task_post_result = $client->post('v2/srp_tasks_post', array('data' => $post_array));
        print_r($task_post_result);

        //do something with post results

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

$client = null;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task srp_tasks_post()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var rnd = new Random(); //you can set as "index of post_data" your ID, string, etc. we will return it with all results.
            var postObject = new Dictionary<int, object>
            {
                [rnd.Next(1, 30000000)] = new
                {
                    priority = 1,
                    url = "https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
                },
                [rnd.Next(1, 30000000)] = new
                {
                    priority = 1,
                    se_name = "google.co.uk",
                    se_language = "English",
                    loc_name_canonical = "London,England,United Kingdom",
                    key = "online rank checker"
                },
                [rnd.Next(1, 30000000)] = new
                {
                    priority = 1,
                    se_id = 22,
                    loc_id = 1006886,
                    key_id = 1095202
                }
            };
            var taskPostResponse = await httpClient.PostAsync("v2/srp_tasks_post", new StringContent(JsonConvert.SerializeObject(new {data = postObject})));
            var obj = JsonConvert.DeserializeObject<dynamic>(await taskPostResponse.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
            {
                foreach (var result in obj.results)
                {
                    var taskState = ((IEnumerable<dynamic>) result).First();
                    if (taskState.status == "error")
                        Console.WriteLine($"Error in task with post_id {taskState.post_id}. Code: {taskState.error.code} Message: {taskState.error.message}");
                    Console.WriteLine(taskState);
                }
            }
        }
    }
}
from random import Random
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")
rnd = Random() #you can set as "index of post_data" your ID, string, etc. we will return it with all results.
post_data = dict()
post_data[rnd.randint(1, 30000000)] = dict(
    priority=1,
    url="https://www.google.co.uk/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
)
post_data[rnd.randint(1, 30000000)] = dict(
    priority=1,
    se_name="google.co.uk",
    se_language="English",
    loc_name_canonical="London,England,United Kingdom",
    key="online rank checker"
)
post_data[rnd.randint(1, 30000000)] = dict(
    priority=1,
    se_id=22,
    loc_id=1006886,
    key_id=1095202
)

response = client.post("/v2/srp_tasks_post", dict(data=post_data))
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6490 sec.",
    "results_count": 9,
    "results": {
        "11913049": {
            "post_id": 11913049,
            "post_key": "",
            "task_id": 404227822,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "20469414": {
            "post_id": 20469414,
            "post_key": "online rank checker",
            "task_id": 404227823,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "6273173": {
            "post_id": 6273173,
            "post_key": "",
            "task_id": 404227824,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "27408598": {
            "post_id": 27408598,
            "post_key": "",
            "task_id": 404227825,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "19840083": {
            "post_id": 19840083,
            "post_key": "online rank checker",
            "task_id": 404227826,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "6054604": {
            "post_id": 6054604,
            "post_key": "",
            "task_id": 404227827,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "8626195": {
            "post_id": 8626195,
            "post_key": "",
            "task_id": 404227828,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "18786140": {
            "post_id": 18786140,
            "post_key": "online rank checker",
            "task_id": 404227829,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        },
        "13056693": {
            "post_id": 13056693,
            "post_key": "",
            "task_id": 404227830,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "status": "ok"
        }
    }
}

All POST data should be sent in the JSON format (UTF-8 encoding). Task setting is made by the POST method, passing array of tasks in data field. We recommend to set up to 100 tasks at a time. Such limit was set because of the variations of tasks settings that you will use. If you use the field url then the processing of each task will take more time. If you use our identifiers (se_id, loc_id, key_id), then the processing of tasks will be made faster and you can set more than 100 elements at a time. Each of array elements has such structure.

You also can receive results of completed tasks using task_id or we can send them by ourselves as soon as they are ready if you specify postback_url or pingback_url when setting a task.

Name of a field Type Description
priority integer execution priority
optional field
can have such values:
1 - normal execution priority (set by default)
2 - high execution priority
url string direct URL of a search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Such method is the most difficult for our API processing and you should exactly specify language and location in the URL. We don’t recommend to use this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20
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
the list of available search engines with se_id you can get by separate request List of Search Engines
also, when the information about set task is returned you will get se_id
se_name string search engine domain
optional field if you specify se_id
you must choose one of the fields se_id or se_name
the list of available search engines with se_name you can get by separate request List of Search Engines
example: “google.co.uk”
se_language string search engine language
required field if se_id is not specified
the list of available search engines with se_language you can get by separate request List of Search Engines
example: “English”
loc_id integer search engine location id
optional field if you specify loc_name_canonical
you must choose one of the fields loc_id or loc_name_canonical
the list of available locations of search engines with loc_id you can get by separate request List of Locations
also when the information about set task is returned you will get loc_id
please notice that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify loc_id appropriate Criteria ID
loc_name_canonical string full name of search engine location
optional field if you specify loc_id
you must choose one of the fields loc_id or loc_name_canonical
the list of available locations of search engines with loc_name_canonical you can get by separate List of Locations
please notice that we use Google Geographical Targeting including such types of locations as Country State Region Municipality City, that’s why you can specify loc_name_canonical appropriate Canonical Name
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 you to save key_id returned after the task was set and use this field in the future.
key string keyword
optional field if you specify key_id
UTF-8 encoding
all %## will be decoded (plus symbol ‘+’ will be decoded to a space character)
if you need to use the “%” symbol for your key, please specify it as “%25”

if this field contains ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘cache:’, ‘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 instance, if you want to disable auto correction of misspelling in the search query for google, you can specify “&nfpr=1”
postback_url string return URL for sending task results
optional field
if you specify this URL there will be no need to pick up tasks using Get Rank Tasks Results. We will send a result of a completed task by POST request for URL as soon as a task is completed.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use string ‘$task_id’ as $task_id variable and ‘$post_id’ as $post_id variable. we will set necessary values before sending of a request. for example:
  http://your-server.com/pingscript?taskId=$task_id
  http://your-server.com/pingscript?taskId=$task_id&postId=$post_id

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

Here are some examples:

  1. There is an identifier at your system of a task that you set to collect data, let it be 100500. When you set the task you send it in the data array with 100500 index like here: "{"data":{"100500":{"priority":1,"se_name":"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 at your system.
  2. You want to associate other kinds of data at your system. For instance:
    • a keyword has id=1238 at your system,
    • a search engine id=43289,
    • a location id=97435,
    • a language id=2,
    • a user for whom you want to complete this task has id=9999.

    Since the index of a task in the data array can be specified as a string, you can create this index using any symbol as a delimiter that fits you most to send the information mentioned above as a post_id. For instance, let’s see how it will look like if we use # as a delimiter. The index that includes all necessary data will have this value 1238#43289#97435#2#9999. As a result, the request for setting of a task will look like this: "{"data":{"1238#43289#97435#2#9999":{"priority":1,"se_name":"google.co.uk","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 API server you will receive JSON array in the field results of which there will be an information appropriate to the set tasks.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information of array error error
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of error
results_time string execution time, seconds
results_count string *number of elements in the array of results results
results array results array of tasks setting
            task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time.
            status string results of this task setting
“ok” - success
“error” - error
if status=“error”, then you can see more detailed information of array error error
            error array informational array of error
only if status=“error”
the list of possible errors can be found below.
                  code integer error code
                  message string text description of error
            post_id string index in the array received in a POST request
            post_key string key received in a POST request
if you send key_id without passing key it will be empty
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 finding relations between your and our search engines.
            loc_id integer search engine location id
if status=“ok”, then this field will be always filled
You can use it for finding relations between your and our 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 when you set a task as key_id

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

Get SERP Completed Tasks

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

<?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/login
    $client = new RestClient('https://api.dataforseo.com', null, 'login', 'password');

    // #1 - get task_id list of ALL ready results
    //GET /v2/srp_tasks_get
    $tasks_get_result = $client->get('v2/srp_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;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task srp_tasks_get()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var completedTasksResponse = await httpClient.GetAsync("v2/srp_tasks_get");
            var completedTasksObj = JsonConvert.DeserializeObject<dynamic>(await completedTasksResponse.Content.ReadAsStringAsync());
            if (completedTasksObj.status == "error")
                Console.WriteLine($"error. Code: {completedTasksObj.error.code} Message: {completedTasksObj.error.message}");
            else if (completedTasksObj.results_count != 0)
            {
                foreach (var result in completedTasksObj.results)
                {
                    var completedTask = ((IEnumerable<dynamic>)result).First();
                    Console.WriteLine(completedTask);
                }
            }
            else
                Console.WriteLine("No completed tasks");
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")
response = client.get("/v2/srp_tasks_get")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0120 sec.",
    "results_count": 1,
    "results": [
        {
            "task_id": 107,
            "post_id": 11577837,
            "post_key": null,
            "se_id": 22,
            "loc_id": 1006886,
            "key_id": 1095202,
            "results_count": 4690000,
            "result_extra": "videos",
            "result_spell": "",
            "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
        }
    ]
}

You will get the list of complete results, that you haven’t collected yet. After you collect a result the task will be removed from this list.

If you specify pingback_url or postback_url you can skip usage of srp_tasks_get to get the list of completed tasks. Our system send you GET request to the pingback_url or send POST request with results to the postback_url.

As a response of API server you will receive array in the field resultsof which there will be a list of complete results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information of array error error
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the array of results results
results array results array of tasks
            task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time
            post_id string index in the array received in a POST array
            post_key string key received in a POST array
if you send key_idwithout passing key, then it will be empty
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 finding relations between your and our search engines
            loc_id integer search engine location id
You can use it for finding relations between your and our 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 when you set a task as key_id
            results_count integer total number of results in the SERP
            result_extra string additional elements in the SERP
you can see such items separated by commas: app, blog, books, carousel, featured_snippet, discussions, images, knowledge_graph, maps, news, patents, places, recipes, shopping, videos
            result_spell string auto correction of a search engine
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engine
            result_se_check_url string direct URL to search engine results
You can use it to make sure that we provide exact results

Get SERP Results by task_id

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

<?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/login
    $client = new RestClient('https://api.dataforseo.com', null, 'login', 'password');

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

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

$client = null;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task srp_tasks_get_by_task_id()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var completedTasksResponse = await httpClient.GetAsync("v2/srp_tasks_get");
            var completedTasksObj = JsonConvert.DeserializeObject<dynamic>(await completedTasksResponse.Content.ReadAsStringAsync());
            if (completedTasksObj.status == "error")
                Console.WriteLine($"error. Code: {completedTasksObj.error.code} Message: {completedTasksObj.error.message}");
            else if (completedTasksObj.results_count != 0)
            {
                foreach (var result in completedTasksObj.results)
                {
                    var completedTask = ((IEnumerable<dynamic>)result).First();
                    var serpResponse = await httpClient.GetAsync($"v2/srp_tasks_get/{completedTask.task_id}");
                    var serpObj = JsonConvert.DeserializeObject<dynamic>(await serpResponse.Content.ReadAsStringAsync());
                    if (serpObj.status == "error")
                        Console.WriteLine($"error. Code: {serpObj.error.code} Message: {serpObj.error.message}");
                    foreach (var serpResult in serpObj.results)
                        Console.WriteLine(((IEnumerable<dynamic>)serpResult).First());
                }
            }
            else
                Console.WriteLine("No completed tasks");
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")
completed_tasks_response = client.get("/v2/srp_tasks_get")
if completed_tasks_response["status"] == "error":
    print("error. Code: %d Message: %s" % (completed_tasks_response["error"]["code"], completed_tasks_response["error"]["message"]))
else:
    results = completed_tasks_response["results"]
    print(results)
    for result_id in results:
        result = results[result_id]
        srp_response = client.get("/v2/srp_tasks_get/%d" % (result["task_id"]))
        if srp_response["status"] == "error":
            print("error. Code: %d Message: %s" % (srp_response["error"]["code"], srp_response["error"]["message"]))
        else:
            print(srp_response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0135 sec.",
    "results_count": 100,
    "results": {
            "organic": [
                {
                    "post_id": 2833944,
                    "task_id": 405460981,
                    "se_id": 22,
                    "loc_id": 1006886,
                    "key_id": 1095202,
                    "post_key": null,
                    "result_datetime": "2016-12-19 14:41:33 +02:00",
                    "result_position": 1,
                    "result_url": "https:\/\/serps.com\/tools\/rank-checker\/",
                    "result_title": "Free Keyword Rank Checker - Google & Yahoo | SERPs.com",
                    "result_snippet_extra": "",
                    "result_snippet": "International and local keyword rankings. Check keyword rankings positions in Google or Yahoo from over 100 country and language combinations.",
                    "results_count": 4690000,
                    "result_extra": "videos",
                    "result_spell": "",
                    "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
                },
                {
                    "post_id": 2833944,
                    "task_id": 405460981,
                    "se_id": 22,
                    "loc_id": 1006886,
                    "key_id": 1095202,
                    "post_key": null,
                    "result_datetime": "2016-12-19 14:41:33 +02:00",
                    "result_position": 2,
                    "result_url": "https:\/\/ranksonic.com\/",
                    "result_snippet_extra": "Rating: 4.6 - ‎6,054 reviews",
                    "result_title": "RankSonic ⓴⓰ - Rank Tracking SEO software. Website ranking SEO ...",
                    "result_snippet": "⓴⓰ Rank Tracking SEO Software ? Keyword Google online search engine seo \n... Check what potential your keywords have to evaluate their competition level.",
                    "results_count": 4690000,
                    "result_extra": "videos",
                    "result_spell": "",
                    "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
                },


                {
                    "post_id": 2833944,
                    "task_id": 405460981,
                    "se_id": 22,
                    "loc_id": 1006886,
                    "key_id": 1095202,
                    "post_key": null,
                    "result_datetime": "2016-12-19 14:41:33 +02:00",
                    "result_position": 99,
                    "result_url": "http:\/\/www.prcheckingtool.com\/",
                    "result_title": "PR Checking Tool - Website Ranking Checker",
                    "result_snippet_extra": "",
                    "result_snippet": "It is a simple yet powerful tool checking the online ranking of different websites. If you think that its sole utilization is for web ranking only then you are wrong as it ...",
                    "results_count": 4690000,
                    "result_extra": "videos",
                    "result_spell": "",
                    "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
                }
        ],


        "paid": [
                {
                    "post_id": 2833944,
                    "task_id": 405460981,
                    "se_id": 22,
                    "loc_id": 1006886,
                    "key_id": 1095202,
                    "post_key": null,
                    "result_datetime": "2016-12-19 14:41:33 +02:00",
                    "result_position": 1,
                    "result_url": "https:\/\/www.seorankmonitor.com\/",
                    "result_title": "SEO Rank Monitor - The Most Complete Rank Checker",
                    "result_snippet_extra": "",
                    "result_snippet": "Everything you need to keep your Website Ranked High - Start a Free Trial Now!",
                    "results_count": 4690000,
                    "result_extra": "videos",
                    "result_spell": "",
                    "result_se_check_url": "https:\/\/google.co.uk\/search?q=online%20rank%20checker&hl=en&gl=GB&uule=w+CAIQICIdTG9uZG9uLEVuZ2xhbmQsVW5pdGVkIEtpbmdkb20"
                }
        ],
        "extra": {
            "related": [
                [
                    "what is seo and how it works",
                    "seo definition",
                    "seo google",
                    "how to do seo",
                    "seo wiki",
                    "seo tutorial",
                    "seo tutorial",
                    "seo company"                    
                ]
            ]
        }
    }
}

As a response of API server you will receive array in the field resultsof which there will be a list of complete results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information of array error error
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the array of results results
results array results array of tasks setting
      organic array results array of organic SERP
            task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time. You are charged for each GET request for results receiving.
            post_id string index in the array received in a POST array
            se_id integer search engine id
in the future you will be able to use it within 30 days to request results of this task any time.
            loc_id integer search engine location id
You can use it for finding relations between your and our 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 when you set a task as key_id
            post_key string keyreceived in a POST array
if you send key_id without passing keyit will be empty
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            result_position integer position in the SERP
            result_datetime string date and time when a result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified at your profile settings is used
            result_url string relevant URL in the SERP
            result_title string snippet header in the SERP
            result_snippet_extra string additional snippet in the SERP
ratings, price, author, etc
            result_snippet string snippet in the SERP
            results_count integer total number of results in the SERP
            result_extra string additional elements in the SERP
you can see such items separated by commas: app, blog, books, carousel, featured_snippet, discussions, images, knowledge_graph, maps, news, patents, places, recipes, shopping, videos
            result_spell string auto correction of a search engine
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engine
            result_se_check_url string direct URL to search engine results
You can use it to make sure that we provide exact results
      paid array results array of paid SERP
            task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time.
            post_id string index in the array received in a POST array
            se_id integer search engine id
in the future you will be able to use it within 30 days to request results of this task any time.
            loc_id integer search engine location id
You can use it for finding relations between your and our 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 when you set a task as key_id
            post_key string keyreceived in a POST array
if you send key_id without passing keyit will be empty
keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)
            result_position integer position in the SERP
            result_datetime string date and time when a result was received
in the format “year-month-date:minutes:GMT_difference_hours:GMT_difference_minutes”
for example: “2016-12-13 15:30:34 +02:00”
the time zone specified at your profile settings is used
            result_url string relevant URL in the SERP
            result_title string snippet header in the SERP
            result_snippet_extra string additional snippet in the SERP
ratings, price, author, etc
            result_snippet string snippet in the SERP
            results_count integer total number of results in the SERP
            result_extra string additional elements in the SERP
you can see such items separated by commas: app, blog, books, carousel, featured_snippet, discussions, images, knowledge_graph, maps, news, patents, places, recipes, shopping, videos
            result_spell string auto correction of a search engine
if a search engine provided results for a keyword that was corrected, we will specify the keyword corrected by a search engine
            result_se_check_url string direct URL to search engine results
You can use it to make sure that we provide exact results
      extra array results array of extra SERP elements
extra SERP elements are available only for google search engine
            related array array of ‘related search queries’ strings
this array will be present if the element is in the SERP

Possible errors codes

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

Keywords Data API

Keywords Data API is a toolkit that was created for keyword selection and analysis of their efficiency. Our system uses Google AdWords API, that’s why the possibilities and limits correspond with this API. Google doesn’t return the data for keywords that are relevant to such thematics as weapon, tobacco, drugs, violence and terrorism.

Please note, if you post, for instance, 100 keywords and at least one of them is relevant to the specified thematics, the data won’t be retrieved for any of them more details can be found at Google Advertising Policies Help.

RateExceededError occurs when our service exceeds the Queries Per Second (QPS) limit set by Google API. Any service that works with Google API has this limit. We are working on expanding of the limits. More details about Google API limits can be found here: developers.google.com - docs/rate-limits. We recommend to process these errors (just like any other errors) and set the next task in 30 seconds if such error occurs.

The time to retrieve the result is from 10 to 60 seconds.

Search Volume for Keyword

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

<?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/login
    $client = new RestClient('https://api.dataforseo.com/', null, 'login', 'password');

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


    $sv_post_result = $client->post('v2/kwrd_sv', array('data' => $post_array));
    print_r($sv_post_result);

    //do something with results

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

$client = null;
?>
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task kwrd_sv()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var postArray = new object[]
            {
                new { language = "en", loc_name_canonical = "United States", key = "average page rpm adsense" },
                new { language = "en", loc_id = 2840, key = "adsense blank ads how long" },
                new { language = "en", loc_name_canonical = "United States", key = "leads and prospects" }
            };
            var response = await httpClient.PostAsync("v2/kwrd_sv", new StringContent(JsonConvert.SerializeObject(new { data = postArray })));
            var obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
            {
                foreach (var result in obj.results)
                    Console.WriteLine(result);
            }
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")

keywords_list = [
    dict(
        language="en",
        loc_name_canonical="United States",
        key="average page rpm adsense"
    ),
    dict(
        language="en",
        loc_id=2840,
        key="adsense blank ads how long"
    ),
    dict(
        language="en",
        loc_name_canonical="United States",
        key="leads and prospects"
    )
]

response = client.post("/v2/kwrd_sv", dict(data=keywords_list))
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "task_id": 423292503,
    "results_time": "2.1886 sec.",
    "results_count": 3,
    "results": [
        {
            "language": "en",
            "loc_id": 2840,
            "key": "leads and prospects",
            "cmp": 0.47619047619048,
            "cpc": 0,
            "sv": 10,
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 10
                }
            ]
        },
        {
            "language": "en",
            "loc_id": 2840,
            "key": "adsense blank ads how long",
            "cmp": 0,
            "cpc": 0,
            "sv": 10,
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 0
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 0
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 0
                }
            ]
        },
        {
            "language": "en",
            "loc_id": 2840,
            "key": "average page rpm adsense",
            "cmp": null,
            "cpc": null,
            "sv": null,
            "ms": null
        }
    ]
}

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

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

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

Name of a field Type Description
loc_id integer search engine location id
optional field
you can specify one of the fields loc_id or loc_name_canonical
list of available locations for search engines loc_id you can receive by separate request List of Locations
please notice that we use Google Geographical Targeting, that’s why you are able to point in the field loc_id appropriate Criteria ID
loc_name_canonical string full name of a location for search engine
optional field
you can specify one of the fields loc_id or loc_name_canonical
list of the available locations for search engines with specifying of their loc_name_canonical you can receive by separate request List of Locations
please notice that we use Google Geographical Targeting, that’s why you are able to point in the field loc_name_canonical appropriate Canonical Name
for instance: “London,England,United Kingdom”
language string language
optional field
can have the following values: “ar”, “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”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API - Languages available for targeting
key string keyword
required field
all %## are decoded (plus symbol ‘+’ is decoded to a space character)
for instance: “rank tracker api”

As a response of API server you will receive JSON array in the field results of which there will be keywords data.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you will be able to see more detailed information about array error error
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
task_id integer unique task identifier in our system
results_time string execution time
results_count string number of elements in the array of results results
results array array of results
            language string language
            loc_id integer search engine location id
            key string keyword
keyword is returned decoded %## (plus symbol ‘+’ is decoded as a space character)
            cmp float competition
represents the relative amount of competition associated with the given keyword idea, relative to other keywords. This value will be between 0 and 1 (inclusive).
If there is no data then the value is null
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
If there is no data then the value is null
            sv integer search volume for the last month
represents either the (approximate) number of searches for the given keyword idea on google.com or google.com and partners, depending on the user’s targeting.
If there is no data then the value is null
            ms array monthly searches
represents the (approximated) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographies.
If there is no data then the value is null

Possible errors codes:

Error Code Meaning
404 “not found or not enough data: location” - you have specified nonexistent loc_id, or the location for the search engine wasn’t found according to your loc_name_canonical

Bulk Keyword Search Volume

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

<?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/login
    $client = new RestClient('https://api.dataforseo.com/', null, 'login', 'password');

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


    $sv_post_result = $client->post('v2/kwrd_sv_batch', array('data' => $post_array));
    print_r($sv_post_result);

    //do something with results

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

$client = null;
?>
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task kwrd_sv()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var postArray = new object[]
            {
                new {
                    language = "en",
                    loc_name_canonical = "United States",
                    keys = new[]
                    {
                        "average page rpm adsense",
                        "adsense blank ads how long",
                        "leads and prospects"
                    }
                }
            };
            var response = await httpClient.PostAsync("v2/kwrd_sv", new StringContent(JsonConvert.SerializeObject(new { data = postArray })));
            var obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
            {
                foreach (var result in obj.results)
                    Console.WriteLine(result);
            }
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")

keyword_list = [
    dict(
        language="en",
        loc_name_canonical="United States",
        keys=[
            "average page rpm adsense",
            "adsense blank ads how long",
            "leads and prospects"
        ]
    )
]


response = client.post("/v2/kwrd_sv", dict(data=keyword_list))
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "task_id": 423292503,
    "results_time": "2.1886 sec.",
    "results_count": 3,
    "results": [
        {
            "language": "en",
            "loc_id": 2840,
            "key": "leads and prospects",
            "cmp": 0.47619047619048,
            "cpc": 0,
            "sv": 10,
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 10
                }
            ]
        },
        {
            "language": "en",
            "loc_id": 2840,
            "key": "adsense blank ads how long",
            "cmp": 0,
            "cpc": 0,
            "sv": 10,
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 0
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 0
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 0
                }
            ]
        },
        {
            "language": "en",
            "loc_id": 2840,
            "key": "average page rpm adsense",
            "cmp": null,
            "cpc": null,
            "sv": null,
            "ms": null
        }
    ]
}

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

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

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

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

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

Name of a field Type Description
loc_id integer search engine location id
optional field
you can specify one of the fields loc_id or loc_name_canonical
list of available locations for search engines loc_id you can receive by separate request List of Locations
please notice that we use Google Geographical Targeting, that’s why you are able to point in the field loc_id appropriate Criteria ID
loc_name_canonical string full name of a location for search engine
optional field
you can specify one of the fields loc_id or loc_name_canonical
list of the available locations for search engines with specifying of their loc_name_canonical you can receive by separate request List of Locations
please notice that we use Google Geographical Targeting, that’s why you are able to point in the field loc_name_canonical appropriate Canonical Name
for instance: “London,England,United Kingdom”
language string language
optional field
can have the following values: “ar”, “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”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API - Languages available for targeting
keys array array of keywords
required field
all %## are decoded (plus symbol ‘+’ is decoded to a space character)

As a response of API server you will receive JSON array in the field results of which there will be keywords data.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you will be able to see more detailed information about array error error
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
task_id integer unique task identifier in our system
results_time string execution time
results_count string number of elements in the array of results results
results array array of results
            language string language
            loc_id integer search engine location id
            key string keyword
keyword is returned decoded %## (plus symbol ‘+’ is decoded as a space character)
            cmp float competition
represents the relative amount of competition associated with the given keyword idea, relative to other keywords. This value will be between 0 and 1 (inclusive).
If there is no data then the value is null
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
If there is no data then the value is null
            sv integer search volume for the last month
represents either the (approximate) number of searches for the given keyword idea on google.com or google.com and partners, depending on the user’s targeting.
If there is no data then the value is null
            ms array monthly searches
represents the (approximated) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographies.
If there is no data then the value is null

Possible errors codes:

Error Code Meaning
404 “not found or not enough data: location” - you have specified nonexistent loc_id, or the location for the search engine wasn’t found according to your loc_name_canonical

Keywords for Domain

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

<?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/login
    $client = new RestClient('https://api.dataforseo.com/', null, 'login', 'password');

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

    //do something with results

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

$client = null;
?>
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task kwrd_for_domain()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var domain = "ranksonic.com";
            var country = "us";
            var language = "en";
            var response = await httpClient.GetAsync($"v2/kwrd_for_domain/{domain}/{country}/{language}");
            var obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
            {
                foreach (var result in obj.results)
                    Console.WriteLine(result);
            }
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")
domain = "ranksonic.com"
country_code = "us"
language = "en"
response = client.get("/v2/kwrd_for_domain/%s/%s/%s" % (domain, country_code, language))
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

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


        {
            "key": "check serp ranking for keyword",
            "cmp": 0.097560975609756,
            "cpc": 0,
            "sv": 10,
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 40
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 50
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 20
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 20
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 10
                }
            ]
        }
    ]
}

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

The receiving of keywords is made by GET method with such parameters:

Name of a field Type Description
domain string domain
required field
you can also specify URL in single quotes, like
GET https://api.dataforseo.com/v2/kwrd_for_domain/'https://seo.com/page/'/us/en
country_code string ISO country code for this search engine
language string language
can have the following values: “ar”, “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”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API - Languages available for targeting
sort_by string column to sort the results
can have the following values: “sv”, “relevance”
default value: “sv”

As a response of API server you will receive JSON array in the field results of which there will be data for the selected keywords. Maximum amount of the selected keywords is 700. Array of results is returned according to the sorted field sv.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you will be able to see more detailed information about array error error
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
task_id integer unique task identifier in our system
results_time string execution time, seconds
results_count string number of elements in the array of results results
results array array of results
            key string keyword
            cmp float competition
represents the relative amount of competition associated with the given keyword idea, relative to other keywords. This value will be between 0 and 1 (inclusive).
If there is no data then the value is null
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
If there is no data then the value is null
            sv integer search volume for the last month
represents either the (approximate) number of searches for the given keyword idea on google.com or google.com and partners, depending on the user’s targeting.
If there is no data then the value is null
            ms array monthly searches
represents the (approximated) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographies.
If there is no data then the value is null

Keywords for Keywords

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

<?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/login
    $client = new RestClient('https://api.dataforseo.com/', null, 'login', 'password');

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

    $kw_post_result = $client->post('v2/kwrd_for_keywords', array('data' => $post_array));
    print_r($kw_post_result);

    //do something with results

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

$client = null;
?>
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task kwrd_for_domain()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };

            var postArray = new object[]
            {
                new { language = "en", loc_name_canonical = "United States", keys = new {"seo", "seo agency", "seo marketing"} }
            };
            var response = await httpClient.PostAsync("v2/kwrd_for_keywords", new StringContent(JsonConvert.SerializeObject(new { data = postArray })));
            var obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
            {
                foreach (var result in obj.results)
                    Console.WriteLine(result);
            }
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")

keywords_list = [
    dict(
        language="en",
        loc_name_canonical="United States",
        keys=["seo", "seo agency", "seo marketing"]
    )
]
response = client.post("/v2/kwrd_for_keywords", dict(data=keywords_list))
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

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


        {
            "key": "check serp ranking for keyword",
            "cmp": 0.097560975609756,
            "cpc": 0,
            "sv": 10,
            "ms": [
                {
                    "year": 2016,
                    "month": 10,
                    "count": 40
                },
                {
                    "year": 2016,
                    "month": 9,
                    "count": 50
                },
                {
                    "year": 2016,
                    "month": 8,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 7,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 6,
                    "count": 0
                },
                {
                    "year": 2016,
                    "month": 5,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 4,
                    "count": 20
                },
                {
                    "year": 2016,
                    "month": 3,
                    "count": 20
                },
                {
                    "year": 2016,
                    "month": 2,
                    "count": 10
                },
                {
                    "year": 2016,
                    "month": 1,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 12,
                    "count": 10
                },
                {
                    "year": 2015,
                    "month": 11,
                    "count": 10
                }
            ]
        }
    ]
}

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

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

Name of a field Type Description
loc_id integer search engine location id
optional field
you can specify one of the fields loc_id or loc_name_canonical
list of available locations for search engines loc_id you can receive by separate request List of Locations
please notice that we use Google Geographical Targeting, that’s why you are able to point in the field loc_id appropriate Criteria ID
loc_name_canonical string full name of a location for search engine
optional field
you can specify one of the fields loc_id or loc_name_canonical
list of the available locations for search engines with specifying of their loc_name_canonical you can receive by separate request List of Locations
please notice that we use Google Geographical Targeting, that’s why you are able to point in the field loc_name_canonical appropriate Canonical Name
for instance: “London,England,United Kingdom”
language string language
optional field
can have the following values: “ar”, “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”, “th”, “tr”, “uk”, “ur”, “vi”
Source Google AdWords API - Languages available for targeting
sort_by string column to sort the results
can have the following values: “sv”, “relevance”
default value: “sv”
keys array array of keywords
required field
all %## are decoded (plus symbol ‘+’ is decoded to a space character)
keys_negative array array of negative keywords
optional field
maximum 200 elements can be specified
all %## are decoded (plus symbol ‘+’ is decoded to a space character)

As a response of API server you will receive JSON array in the field results of which there will be data for the selected keywords. Maximum amount of the selected keywords is 700. Array of results is returned according to the sorted field sv.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you will be able to see more detailed information about array error error
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
task_id integer unique task identifier in our system
results_time string execution time, seconds
results_count string number of elements in the array of results results
results array array of results
            key string keyword
            cmp float competition
represents the relative amount of competition associated with the given keyword idea, relative to other keywords. This value will be between 0 and 1 (inclusive).
If there is no data then the value is null
            cpc float cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
If there is no data then the value is null
            sv integer search volume for the last month
represents either the (approximate) number of searches for the given keyword idea on google.com or google.com and partners, depending on the user’s targeting.
If there is no data then the value is null
            ms array monthly searches
represents the (approximated) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographies.
If there is no data then the value is null

Competitor Data API

Competitor API will provide you with information about your competitors.

The time to retrieve the result is up to 5 seconds.

Competitor Info

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

<?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/login
    $client = new RestClient('https://api.dataforseo.com/', null, 'login', 'password');

    $cmp_get_result = $client->get('v2/cmp_get/asana.com');
    print_r($cmp_get_result);

    //do something with results

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

$client = null;
?>
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task cmp_get()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var domain = "asana.com";
            var response = await httpClient.GetAsync($"v2/cmp_get/{domain}");
            var obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
            {
                foreach (var result in obj.results)
                    Console.WriteLine(result);
            }
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")
domain = "asana.com"
response = client.get("/v2/cmp_get/%s" % (domain))
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.6756 sec.",
    "results_count": 1,
    "results": [
        {
            "date": "2017-01-01",
            "site_url": "asana.com",
            "site_title": "Use Asana to track your team’s work & manage projects · Asana",
            "site_description": "It’s free to use, simple to get started, and powerful enough to run your entire business. Sign up for free today.",
            "audience": {
                "visits": 19952871,
                "time_on_site_avg": "00:09:25",
                "page_views_avg": 6.9773123942789,
                "bounce_rate": 35.85
            },
            "traffic": {
                "value": 19952871,
                "percent": 100,
                "countries": [
                    {
                        "country": "United States",
                        "value": 6864349,
                        "percent": 34.4
                    },
                    {
                        "country": "United Kingdom",
                        "value": 1133338,
                        "percent": 5.68
                    },
                    {
                        "country": "Brazil",
                        "value": 705693,
                        "percent": 3.54
                    },
                    {
                        "country": "Canada",
                        "value": 703566,
                        "percent": 3.53
                    },
                    {
                        "country": "Poland",
                        "value": 700182,
                        "percent": 3.51
                    },
                    {
                        "country": "Other",
                        "value": 984474655,
                        "percent": 49.34
                    }
                ],
                "sources": {
                    "direct": {
                        "value": 11200942,
                        "percent": 56.14
                    },
                    "search_organic": {
                        "value": 1516235,
                        "percent": 7.6,
                        "top_keywords": [
                            {
                                "keyword": "asana",
                                "value": 1137732,
                                "percent": 75.04
                            },
                            {
                                "keyword": "asana app",
                                "value": 13908,
                                "percent": 0.92
                            },
                            {
                                "keyword": "independent director positions",
                                "value": 8174,
                                "percent": 0.54
                            },
                            {
                                "keyword": "poczta kwiatkowskiego 2b rzeszow",
                                "value": 7422,
                                "percent": 0.49
                            },
                            {
                                "keyword": "setting yourself up for acquisition",
                                "value": 6074,
                                "percent": 0.4
                            }
                        ]
                    },
                    "search_ad": {
                        "value": 101983,
                        "percent": 0.51,
                        "top_keywords": [
                            {
                                "keyword": "asana",
                                "value": 67707,
                                "percent": 66.39
                            },
                            {
                                "keyword": "timeline",
                                "value": 1288,
                                "percent": 1.26
                            },
                            {
                                "keyword": "to do list",
                                "value": 1181,
                                "percent": 1.16
                            },
                            {
                                "keyword": "task manager",
                                "value": 793,
                                "percent": 0.78
                            },
                            {
                                "keyword": "assana",
                                "value": 779,
                                "percent": 0.76
                            }
                        ]
                    },
                    "referral": {
                        "value": 4479578,
                        "percent": 22.45,
                        "top_referrals": [
                            {
                                "site": "blog.capterra.com",
                                "value": 204328,
                                "percent": 4.56
                            },
                            {
                                "site": "instagantt.com",
                                "value": 189092,
                                "percent": 4.22
                            },
                            {
                                "site": "news.ycombinator.com",
                                "value": 177579,
                                "percent": 3.96
                            },
                            {
                                "site": "github.com",
                                "value": 116090,
                                "percent": 2.59
                            },
                            {
                                "site": "symbaloo.com",
                                "value": 115508,
                                "percent": 2.58
                            }
                        ]
                    },
                    "referral_ad": {
                        "value": 8640,
                        "percent": 0.04,
                        "top_referrals": [
                            {
                                "site": "nytimes.com",
                                "value": 3173,
                                "percent": 36.73
                            },
                            {
                                "site": "recode.net",
                                "value": 1586,
                                "percent": 18.37
                            },
                            {
                                "site": "thenextweb.com",
                                "value": 1057,
                                "percent": 12.24
                            },
                            {
                                "site": "youtube.com",
                                "value": 881,
                                "percent": 10.2
                            },
                            {
                                "site": "inbox.google.com",
                                "value": 352,
                                "percent": 4.08
                            }
                        ]
                    },
                    "social": {
                        "value": 672103,
                        "percent": 3.37,
                        "top_socials": [
                            {
                                "site": "Facebook",
                                "value": 356595,
                                "percent": 53.06
                            },
                            {
                                "site": "Youtube",
                                "value": 135141,
                                "percent": 20.11
                            },
                            {
                                "site": "WhatsApp Webapp",
                                "value": 50327,
                                "percent": 7.49
                            },
                            {
                                "site": "Twitter",
                                "value": 34339,
                                "percent": 5.11
                            },
                            {
                                "site": "Linkedin",
                                "value": 24925,
                                "percent": 3.71
                            }
                        ]
                    },
                    "appstore": {
                        "value": 0,
                        "percent": 0,
                        "top_apps": [
                            {
                                "app_id": "com.asana.app",
                                "app_title": "Asana: Team Tasks & Projects",
                                "app_author": "Asana, Inc.",
                                "app_category": "Business",
                                "app_price": "Free",
                                "app_rating": 4.1412091255188,
                                "app_rating_count": 15948
                            },
                            {
                                "app_id": "489969512",
                                "app_title": "Asana: Team Tasks & Conversations",
                                "app_author": "Asana, Inc.",
                                "app_category": "Business",
                                "app_price": "0.0 EGP",
                                "app_rating": 4,
                                "app_rating_count": 2666
                            },
                            {
                                "app_id": "1175204125",
                                "app_title": "Answers For Lego Heroes Trivia Photo Games Pro",
                                "app_author": "Sukanda Tualek",
                                "app_category": "Games",
                                "app_price": "1.99 USD",
                                "app_rating": 0,
                                "app_rating_count": 0
                            }
                        ]
                    },
                    "mail": {
                        "value": 1973386,
                        "percent": 9.89
                    }
                },
                "estimated": {
                    "2016-08-01": 21392337,
                    "2016-09-01": 20358683,
                    "2016-10-01": 20588723,
                    "2016-11-01": 19146635,
                    "2016-12-01": 17345915,
                    "2017-01-01": 19952871
                }
            }
        }
    ]
}

This feature will provide you with information about traffic and its sources, as well as visits analysis of your competitors websites.

The receiving of information is made by GET method with such parameters:

Name of a field Type Description
domain string domain
required field

As a response of API server you will receive JSON array in the field results of which there will be data for the competitor domain.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you will be able to see more detailed information about array error error
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the array of results
results array array of results
      date string month when the information was received
in the format “year-month-date”
all information provided for this month
      site_url string domain URL
      site_title string main page ‘Title’ metatag
      site_description string main page ‘Description’ metatag
      audience array audience information
         visits integer total visits
         time_on_site_avg string average visit duration
         page_views_avg string average page views by visit
         bounce_rate string bounce rate
      traffic array traffic information
         value integer total traffic value
         percent float total traffic percentage
         countries array traffic by countries
            country string country
            value integer traffic value
            percent float traffic percentage
         sources array traffic sources
            direct array direct source
               value integer traffic value
               percent float traffic percentage
            search_organic array organic search
               value integer traffic value
               percent float traffic percentage
               top_keywords array top 5 organic search keywords
                  keyword string search keyword
                  value integer organic search value
                  percent float organic search percentage
            search_ad array paid search
               value integer traffic value
               percent float traffic percentage
               top_keywords array top 5 keywords
                  keyword string keyword
                  value integer paid search value
                  percent float paid search percentage
            referral array top referring sites
               value integer traffic value
               percent float traffic percentage
               top_referrals array top 5 referring sites
                  site string site
                  value integer referral traffic value
                  percent float referral traffic percentage
            referral_ad array advertising publishers
               value integer traffic value
               percent float traffic percentage
               top_referrals array top 5 publishers
                  site string site
                  value integer advertising referral traffic value
                  percent float advertising referral traffic percentage
            social array traffic from social media
               value integer traffic value
               percent float traffic percentage
               top_socials array top socials
                  site string social
                  value integer social traffic value
                  percent float social traffic percentage
            appstore array related apps
               value integer traffic value
               percent float traffic percentage
               top_apps array top applications
                  app_id string application ID
                  app_title string application title
                  app_author string application author
                  app_category string application category
                  app_price string application price
                  app_rating string application rating
                  app_rating_count string application rating count
            mail array source
               value integer traffic value
               percent float traffic percentage
         estimated array estimated traffic by months
            $month integer this month estimated traffic value

OnPage API

The OnPage API is designed to improve your website’s performance and get better rankings in SERP. Crawl diagnostics is one of the most powerful tools for the internal site optimization.

OnPage API checks your website for 60+ parameters, defines and displays all found flaws, so you can easily fix them. It checks meta tags, content, images tags, response codes and parameters of every page. The full list of parameters that your website is checked for you can find in the page result fields section.

Setting Tasks

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

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

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

$post_array = array();
$my_unq_id = mt_rand(0,30000000); //your unique ID (like you DB "id" field. type 'string'). will be returned with all results
$post_array[$my_unq_id] = array(
    "site" => "ranksonic.com",
    "crawl_max_pages" => 10
);

try {
    // POST /v2/op_tasks_post/$data
    // $tasks_data must by array with key 'data'
    $task_post_result = $client->post("v2/op_tasks_post", array('data' => $post_array));
    print_r($task_post_result);

    //do something with post results

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

$client = null;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task srp_tasks_post()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var rnd = new Random(); //you can set as "index of post_data" your ID, string, etc. we will return it with all results.
            var postObject = new Dictionary<int, object>
            {
                [rnd.Next(1, 30000000)] = new
                {
                    site = "ranksonic.com",
                    crawl_max_pages = 10
                }
            };
            var taskPostResponse = await httpClient.PostAsync("v2/op_tasks_post", new StringContent(JsonConvert.SerializeObject(new {data = postObject})));
            var obj = JsonConvert.DeserializeObject<dynamic>(await taskPostResponse.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
            {
                foreach (var result in obj.results)
                {
                    var taskState = ((IEnumerable<dynamic>) result).First();
                    if (taskState.status == "error")
                        Console.WriteLine($"Error in task with post_id {taskState.post_id}. Code: {taskState.error.code} Message: {taskState.error.message}");
                    Console.WriteLine(taskState);
                }
            }
        }
    }
}
from random import Random
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")
rnd = Random() #you can set as "index of post_data" your ID, string, etc. we will return it with all results.
post_data = dict()
post_data[rnd.randint(1, 30000000)] = dict(
    site="ranksonic.com",
    crawl_max_pages=10
)

response = client.post("/v2/op_tasks_post", dict(data=post_data))
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1029 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": 104574,
            "post_site": "ranksonic.com",            
            "task_id": 130491671,
            "status": "ok"
        }
    ]
}

Using this function, you can set tasks for scanning of a website. After a task has been set, there will be three stages of its completion. Each of them will be shown in the status of the task (the status field). Firstly, the task is queued to the completion status="in_queue". Secondly, the website is crawled status="crawling". On the final stage, when the scanning process is finished, the task gets status="crawled". After the task is completed (status="crawled"), you will be able to use functions to analyze the received results. The current status of a task can be found in the results of the Get Tasks Status function. The results of the completed task will be available within 30 days of its completion.

Task completion time depends on many factors. They are a number of scanned pages (the field crawl_max_pages that you must specify when setting a task), a response time of the server where a website is located, the volume of the pages that are being analyzed, etc.

If number of pages crawled is fewer than the specified parameter crawl_max_pages, remaining credits will be refunded

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

Name of a field Type Description
site string site
required field
crawl_max_pages integer maximum number of test pages
required field
credits will be withdrawn on the basis of this parameter
if number of pages crawled is fewer than this parameter, remaining credits will be refunded.
crawl_max_depth integer crawl depth
optional field
crawl depth of the website. for example: homepage is level 0, links from the homepage is level 1, etc. unique links are taken into account (for example, links from level 1 will be reflected as level 0).
default value: 0.
crawl_delay integer delay between queries
optional field
this parameter enables adjusting the frequency of queries to the server in order to reduce the burden and avoid DDOS.
default value: 0.
cookies_use integer usage of cookies when a website is being scanned
optional field
сan take the values: 0 - no, 1 - yes.
default value: 1.
robots string user robots.txt
optional field
You can set up your robots.txt for this crawling task.
robots_mode string merger mode with robots.txt of the website
optional field
can take values: ‘merge’, ‘override’.
default value: ‘merge’.
string_search_containment string presence of the text on the page
optional field
the result of the search will be shown in the string_containment_check field.
default value: ‘null’.
pingback_url string notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use string ‘$task_id’ as $task_id variable and ‘$post_id’ as $post_id variable. we will set necessary values before sending a request. for example:
  http://your-server.com/pingscript?taskId=$task_id
  http://your-server.com/pingscript?taskId=$task_id&postId=$post_id

As a response of API server you will receive JSON array in the field results where you wil find an information appropriate to the tasks set.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information in the error array
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of the error
results_time string execution time, seconds
results_count string number of elements in the results array
results array results array of tasks setting
      post_id string index in the array received in a POST request
      post_site string site received in a POST request
      task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time.
      status string results of this task setting
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information in the error array
      error array informational array of error
only if status=“error”
the list of possible errors can be found below.
            code integer error code
            message string text description of an error

Possible errors 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: crawl_max_pages” - you didn’t specify a crawl_max_pages field in the task
501 “invalid ‘data’ field” - probably you haven’t passed data for the tasks in the field data. POST data should be represented as an array and added to the field data: array(‘data’ => $post_array_for_tasks)
501 “invalid data” - Data in the field data isn’t an array with the required structure.
500 “internal error” - some internal error. We did our best to avoid this type of error.

Get Tasks Status

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

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

try {
    $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";
}

//get ALL results status
try {
    //GET /v2/op_tasks_get
    $task_get_result = $client->get("v2/op_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";
}

$client = null;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task rnk_tasks_get()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),
                DefaultRequestHeaders = {Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}
            };

            var response = await httpClient.GetAsync("v2/op_tasks_get");
            var obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else if (obj.results_count != 0)
            {
                foreach (var result in obj.results)
                {
                    var resultItem = ((IEnumerable<dynamic>) result).First();
                    Console.WriteLine(resultItem);
                }
            }
            else
                Console.WriteLine("no results");

        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

client = RestClient("login", "password")
response = client.get("/v2/op_tasks_get")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0043 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "104574",
            "post_site": "ranksonic.com",
            "task_id": 130434581,
            "string_search_containment": "the implementation",
            "crawl_max_pages": 100,
            "crawl_start": "2017-09-07 18:09:02.609802+03",
            "crawl_end": "2017-09-09 12:56:49.164561+03",
            "status": "crawled"
        }
    ]
}

Using this function, you can get the current status of a task completion. If a task has status="crawled" you can use functions to analyze the received results.

You can receive results status in two different ways:

  1. GET https://api.dataforseo.com/v2/op_tasks_get
    you will receive all results status.
  2. When setting a task (Setting OnPage Tasks) you’ve specified pingback_url. As soon as the task is completed we will send GET request to the URL you’ve specified as pingback_url.

You will receive array from the API server in the results field where you will find results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information in the error array
error array informational array of error
only if status=“error”
      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 results array
      post_id string index in the array received in a POST array
      post_site string site received in a POST array
      task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time
      string_search_containment string string_search_containment received in a POST request
default value: ‘null’.
      crawl_max_pages integer maximum number of test pages
      crawl_start string date and time of the start of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-14 11:50:01 +02:00’
      crawl_end string date and time of the end of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-13 15:30:34 +02:00’
      status string current status of the task
possible values: “in_queue”, “crawling”, “crawled”, “crawl_paused”
if the task status is “crawled” you can get the results for this task

Get Task Result Summary

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

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

try {
    $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";
}

try {

    // GET /api/v2/op_tasks_get/$task_id
    $task_get_result = $client->get("v2/op_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;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task rnk_tasks_get()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),
                DefaultRequestHeaders = {Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}
            };

            var taskid = 123456789;
            response = await httpClient.GetAsync($"v2/op_tasks_get/{taskid}");
            obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else if (obj.results_count != 0)
            {
                foreach (var result in obj.results)
                {
                    var resultItem = ((IEnumerable<dynamic>)result).First();
                    Console.WriteLine(resultItem);
                }
            }
            else
                Console.WriteLine("no results");
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

client = RestClient("login", "password")
response = client.get("/v2/op_tasks_get/123456789")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0395 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "1214",
            "post_site": "webbysite.co.uk",
            "task_id": 123456789,
            "string_search_containment": "the implementation",
            "crawl_max_pages": 4,
            "crawl_start": "2017-10-12 11:14:23.624803+03",
            "crawl_end": "2017-10-12 11:15:08.908063+03",
            "status": "crawled",
            "summary": [
                {
                    "absent_doctype": 0,
                    "absent_encoding_meta_tag": 0,
                    "absent_h1_tags": 0,
                    "canonical_another": 0,
                    "canonical_recursive": 0,
                    "cms": "wordpress 4.8.2",
                    "compression_disabled": 0,
                    "content_invalid_rate": 4,
                    "content_invalid_size": 0,
                    "content_readability_bad": 0,
                    "crawl_end": "2017-10-12T08:14:56.766+00:00",
                    "crawl_start": "2017-10-12T08:14:24.762+00:00",
                    "deprecated_html_tags": 0,
                    "domain": "webbysite.co.uk",
                    "duplicate_meta_tags": 0,
                    "duplicate_titles": 0,
                    "favicon_invalid": 0,
                    "have_robots": true,
                    "have_sitemap": true,
                    "images_invalid_alt": 0,
                    "images_invalid_title": 4,
                    "ip": "37.61.232.138",
                    "links_broken": 0,
                    "links_external": 8,
                    "links_internal": 54,
                    "meta_description_empty": 3,
                    "meta_description_inappropriate": 0,
                    "meta_keywords_empty": 4,
                    "meta_keywords_inappropriate": 0,
                    "pages_broken": 0,
                    "pages_http": 4,
                    "pages_https": 0,
                    "pages_invalid_size": 0,
                    "pages_non_www": 4,
                    "pages_total": 4,
                    "pages_with_flash": 0,
                    "pages_with_frame": 0,
                    "pages_with_lorem_ipsum": 0,
                    "pages_www": 0,
                    "response_code_1xx": 0,
                    "response_code_2xx": 4,
                    "response_code_3xx": 0,
                    "response_code_4xx": 0,
                    "response_code_5xx": 0,
                    "response_code_other": 0,
                    "seo_friendly_url": 4,
                    "seo_non_friendly_url": 0,
                    "server": "Apache",
                    "ssl": false,
                    "ssl_certificate_expiration": "0001-01-01T00:00:00+00:00",
                    "ssl_certificate_hash_algorithm": null,
                    "ssl_certificate_issuer": null,
                    "ssl_certificate_subject": null,
                    "ssl_certificate_valid": false,
                    "ssl_certificate_x509_version": 0,
                    "string_containment_check": 1,
                    "test_canonicalization": 200,
                    "test_directory_browsing": true,
                    "test_server_signature": false,
                    "test_trash_page": 404,
                    "time_load_high": 0,
                    "time_waiting_high": 0,
                    "title_duplicate_tag": 0,
                    "title_empty": 0,
                    "title_inappropriate": 0,
                    "title_long": 0,
                    "title_short": 2,
                    "www": false
                }
            ]
        }
    ]
}

Using this function, you can get the overall information of a website. This information allows you to detect exact on-page issues of a website that has been scanned. As a result, you will know what functions to use for receiving of detailed data for each of the found problems.

You will receive array from the API server in the results field where you will find results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information in the error array
error array informational array of error
only if status=“error”
      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 results array
      post_id string index in the array received in a POST array
      post_site string site received in a POST array
      task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time
      string_search_containment string string_search_containment received in a POST request
default value: ‘null’.
      crawl_max_pages integer maximum number of test pages
      crawl_start string date and time of the start of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-14 11:50:01 +02:00’
      crawl_end string date and time of the end of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-13 15:30:34 +02:00’
      status string current status of the task
possible values: “in_queue”, “crawling”, “crawled”, “crawl_paused”
if the task status “crawled” you will get the composite result in the summary array
      summary array composite result
            absent_doctype integer number of pages without <!DOCTYPE html>
            absent_encoding_meta_tag integer number of pages without <meta charset=...>, but only if the encoding is not explicit in the header Content-Type (for example Content-Type: "text/html; charset=utf8")
            absent_h1_tags integer number of pages without H1
only for canonical pages
            canonical_another integer number of pages with the canonical to another page
only for pages with 200 response code
            canonical_recursive integer number of pages with recursive canonicals
            cms string content of generator meta tag
the data is taken from the first random page with 200 response code
            compression_disabled integer *number of pages without enabled gzip or deflate compression
only for pages with 200 response code
            content_bad_readability integer pages that scored less than 15 points on Flesch–Kincaid readability tests
only for canonical pages
            content_invalid_rate integer number of pages, which have value (plaintext size/page size) less than 0.1 or more than 0.9
the data is available only for canonical pages
            content_invalid_size integer number of pages, which have plain text size less than 1024 bytes or more than 256 kbytes
the data is available only for canonical pages
            crawl_end string date and time of the end of crawling
in the format year-month-day:minutes:GMT_difference_hours:GMT_difference_minutes
for example: ‘2017-12-13 15:30:34 +00:00’
            crawl_start string date and time of the start of crawling
in the format year-month-day:minutes:GMT_difference_hours:GMT_difference_minutes
for example: ‘2017-12-14 11:50:01 +00:00’
            deprecated_html_tags integer number of pages with deprecated html tags
the data is available only for canonical pages
more info: list of deprecated tags
            domain string root domain without subdomains
for example: if ‘blog.example.com’ is checked, it’s value would be ‘example.com’
            duplicate_meta_tags integer number of pages with 2 or more meta tags of the same type
only for canonical pages
            duplicate_pages integer number of pages with duplicate content
only for canonical pages
            duplicate_titles integer number of pages with duplicated tag <title>
only for canonical pages
            favicon_invalid integer number of pages that don’t contain link rel="icon"
the data is available only for canonical pages
            have_robots boolean presenсe of robots.txt
            have_sitemap boolean presenсe of sitemap.xml
            images_invalid_alt integer number of pages that have at least one image with empty or absent alt attribute of <img> tag
the data is available only for canonical pages
            images_invalid_title integer number of pages that have at least one image with empty or absent title attribute of <img> tag
the data is available only for canonical pages
            ip string IP address of the website
            links_broken integer number of pages that have at least one reference to the page with a broken link
the link is considered as a broken one if it leads to the page which response code is >=400 and <500
the data is available for all pages
            links_external integer total number of external links
the data is available for all pages
            links_internal integer total number of internal links
the data is available for all pages
            meta_description_empty integer number of pages with empty or absent meta tag description
the data is available only for canonical pages
            meta_description_inappropriate integer number of pages with content of description tag that is irrelevant to the content of a page (only for canonical pages)
the relevance threshold is 0.2
the data is not available for the pages that don’t have description tag
            meta_keywords_empty integer number of pages with empty keywords in meta tags
the data is available only for canonical pages
            meta_keywords_inappropriate integer number of pages with content of keywords tag that is irrelevant to the content of a page (only for canonical pages)
the relevance threshold is 0.6
the data is not available for the pages that don’t have keywords tag
            pages_broken integer number of pages which response code is >=400 or <200
the data is available for all pages
            pages_http integer number of pages with HTTP protocol
the data is available for all pages
            pages_https integer number of pages with HTTPS protocol
the data is available for all pages
            pages_invalid_size integer number of pages with the page size less than 1024 bytes or more than 256 kbytes
the data is available only for canonical pages
            pages_non_www integer number of pages without subdomain www
the data is available for all pages
            pages_total integer total number of scanned HTML pages
            pages_with_flash integer number of pages with flash elements
the data is available for all pages
            pages_with_frame integer number of pages that contain frame, iframe, frameset tags
the data is available for all pages
            pages_with_lorem_ipsum integer number of pages that probably contain ‘lorem ipsum’
the data is available for all pages
            pages_www integer number of pages with subdomain www
the data is available for all pages
            response_code_1xx integer number of pages which response code is >=100 and <200
the data is available for all pages
            response_code_2xx integer number of pages which response code is >=200 and <300
the data is available for all pages
            response_code_3xx integer number of pages which response code is >=300 and <400
the data is available for all pages
            response_code_4xx integer number of pages which response code is >=400 and <500
the data is available for all pages
            response_code_5xx integer number of pages which response code is >=500 and <600
the data is available for all pages
            response_code_other integer number of pages which response code is >=600 and <100
also, the number includes those pages which response code was not retrieved
the data is available for all pages
            seo_friendly_url integer number of pages with an ‘SEO-friendly URL’
the ‘SEO-friendliness’ of a page URL is checked by four parameters:
- length of relative path is less than 120 symbols
- no special characters
- no dynamic parameters
- relevance of URL to the page
if at least one of them is failed then such URL is considered as not ‘SEO-friendly’
the data is available only for canonical pages
            seo_non_friendly_url integer number of pages that don’t have an ‘SEO-friendly URL’
the ‘SEO-friendliness’ of a page URL is checked by four parameters:
- length of relative path is less than 120 symbols
- no special characters
- no dynamic parameters
- relevance of URL to the page
if at least one of them is failed then such URL is considered as not ‘SEO-friendly’
the data is available only for canonical pages
            server string content of header server
the information is taken from the first page which response code is 200
            ssl boolean usage of the secure SSL protocol
true - if there is at least one HTTPS page
relevant fields will contain data if ssl = true
the information about sertificate is taken from the first page that has https
            ssl_certificate_expiration string expiration date and time of the SSL certificate
in the format year-month-day:minutes:GMT_difference_hours:GMT_difference_minutes
for example: ‘2017-12-25 05:10:34 +00:00’
            ssl_certificate_hash_algorithm string encryption algorithm of the SSL certificate
if website does not support SSL (field ssl=false), there is always an empty value
            ssl_certificate_issuer string issuer of the SSL certificate
if website does not support SSL (field ssl=false), there is always an empty value
            ssl_certificate_subject string issuer of the SSL certificate
if website does not support SSL (field ssl=false), there is always an empty value
            ssl_certificate_valid boolean validation of the SSL certificate
if website does not support SSL (field ssl=false), there is always ‘false’
            ssl_certificate_x509_version integer version of the SSL certificate
if website does not support SSL (field ssl=false), there is always an empty value
            string_containment_check integer the number of pages that contain text specified in the string_search_containment field
            test_canonicalization integer the checkup of server behavior when our crawler tries to access the website via IP
the field is a status code of server response
normally, a server returns 301 response code
            test_directory_browsing boolean the checkup of the possibility to access a content directory of a website
some webservers may return the data that the server directory has
the checkup will be conducted if a website has at least one page which response code is 200
            test_server_signature boolean *the checkup of header server
if the version is specified along with the server, the test will be considered as a failed one
knowing the version of the server, the attacker can exploit the vulnerabilities specific to this version to attack the site
the test is conducted after the information about header server is received
            test_trash_page integer the checkup of website behavior when the crawler requests a non-existent page
the field is a status code of server response
normally, a server returns 404 response code
            time_load_high integer number of pages with the loading time of more than 3 seconds
the data is available for all pages
            time_waiting_high integer number of pages with waiting time
(time spent waiting for the initial response, also known as the Time To First Byte) of more than 1.5 sec

the data is available for all pages
            title_duplicate_tag integer number of pages with more than one tag <title> on a page
the data is available only for canonical pages
            title_empty integer number of pages with empty or absent tag <title>
the data is available only for canonical pages
            title_inappropriate integer *number of pages with content of <title> tag that is irrelevant to the content of a page (only for canonical pages)
the relevance threshold is 0.3
the data is not available for the pages that don’t have <title> tag
            title_long integer * number of pages with too long tag <title>*
the data is available only for canonical pages
            title_short integer number of pages with too short tag <title>
the data is available only for canonical pages
            www boolean usage of subdomain www
true - if there is at least one page on the subdomain ‘www’ which response code is 200
‘www’ is the only subdomain that is parsed by our crawler within the specified domain

Get Pages

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

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

try {
    $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";
}

try {

    // GET /api/v2/op_tasks_get/$task_id
    $task_get_result = $client->get("v2/op_tasks_get_pages/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;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task rnk_tasks_get()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),
                DefaultRequestHeaders = {Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}
            };

            var taskid = 123456789;
            response = await httpClient.GetAsync($"v2/op_tasks_get_pages/{taskid}");
            obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else if (obj.results_count != 0)
            {
                foreach (var result in obj.results)
                {
                    var resultItem = ((IEnumerable<dynamic>)result).First();
                    Console.WriteLine(resultItem);
                }
            }
            else
                Console.WriteLine("no results");
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

client = RestClient("login", "password")
response = client.get("/v2/op_tasks_get_pages/123456789")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0675 sec.",
    "results_count": 10,
    "results": [
        {
            "post_id": "10##4",
            "post_site": "ranksonic.com",
            "task_id": 130492587,
            "string_search_containment": "the implementation",
            "crawl_max_pages": 4,
            "crawl_start": "2017-10-12 11:14:23.624803+03",
            "crawl_end": "2017-10-12 11:15:08.908063+03",
            "status": "crawled",
            "pages": [
                {
                    "address_full": "https:\/\/ranksonic.com\/features-common.html",
                    "address_relative": "\/features-common.html",
                    "canonical_another": false,
                    "canonical_page": "\/features-common.html",
                    "canonical_page_recursive": "",
                    "content_charset": 65001,
                    "content_count_words": 156,
                    "content_encoding": "gzip",
                    "content_readability_ari": 9.018014,
                    "content_readability_coleman_liau": 10.5429783,
                    "content_readability_dale_chall": 7.216251,
                    "content_readability_flesh_kincaid": 55.32,
                    "content_readability_smog": 17.56878,
                    "crawl_depth": 1,
                    "crawl_end": "2017-10-12T08:15:00+00:00",
                    "crawled": true,
                    "deprecated_tags": [],
                    "duplicate_meta_tags": [],
                    "favicon": "\/themes\/default\/images\/favicon\/favicon_152x152.png",
                    "follow": true,
                    "frame_test": false,
                    "h1_count": 0,
                    "h2_count": 0,
                    "h3_count": 0,
                    "have_deprecated_tags": false,
                    "have_description_duplicates": false,
                    "have_doctype": true,
                    "have_duplicates": false,
                    "have_enc_meta_tag": true,
                    "have_flash": false,
                    "have_lorem_ipsum": false,
                    "have_recursive_canonical": false,
                    "have_title_duplicates": false,
                    "images_count": 17,
                    "images_invalid_alt": 12,
                    "images_invalid_title": 17,
                    "links_broken": 0,
                    "links_count": 12,
                    "links_external": 10,
                    "links_internal": 21,
                    "meta_description": "Improve your SEO, get better results and save time with day-to-day marketing tasks.",
                    "meta_description_consistency": 1,
                    "meta_description_length": 83,
                    "meta_keywords": "ranksonic, seo, features",
                    "meta_keywords_consistency": 0.6666667,
                    "plain_text_rate": 0.175029352,
                    "plain_text_size": 3429,
                    "redirect": null,
                    "response_code": 200,
                    "seo_friendly_url": true,
                    "seo_friendly_characters_check": true,
                    "seo_friendly_dynamic_check": true,
                    "seo_friendly_keywords_check": true,
                    "seo_friendly_rel_path_length_check": true,
                    "size": 19591,
                    "ssl": true,
                    "ssl_handshake_time": 1,
                    "string_containment_check": true,
                    "time_connection": 3,
                    "time_download": 0,
                    "time_total_load": 43,
                    "time_sending_request": 0,
                    "time_waiting": 39,
                    "title": "RankSonic SEO platform common features",
                    "title_consistency": 0.4,
                    "title_length": 38,
                    "www": false
                },



            ]
        }
    ]
}

Using this function, you can retrieve structured data for each page of a website that has been scanned. To get the list of pages based on the set parameters, use the extended version of the Get Filtered Pages function.

You will receive array from the API server in the results field where you will find results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information in the error array
error array informational array of error
only if status=“error”
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the results array
results array results array
      post_id string index in the array received in a POST array
      post_site string site received in a POST array
      task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time
      string_search_containment string string_search_containment received in a POST request
default value: ‘null’.
      crawl_max_pages integer maximum number of test pages
      crawl_start string date and time of the start of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-14 11:50:01 +02:00’
      crawl_end string date and time of the end of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-13 15:30:34 +02:00’
      status string current status of the task
possible values: “in_queue”, “crawling”, “crawled”, “crawl_paused”
      pages array array of scanned pages
            address_full string full page address
            address_relative string relative page address
more info about relative
            canonical_another boolean presence of another canonical page
‘true’ - if page is non-canonical
            canonical_page string canonical link
            canonical_page_recursive string canonical link if its recursive
            content_charset integer content character encoding
list of charset
            content_count_words integer number of words in the content of the page
exceptions are the a tags, etc. the text that is present in the body tag is being parsed. the text that is in script, style, a, noscript, select, button, embed, framest tags as well as comments is ignored
            content_encoding string compression algorithm of the content of the page
more information
            content_readability_ari float ratio of readability by the algotithm Automated Readability Index (ARI)
            content_readability_coleman_liau float ratio of readability by the algotithm Coleman–Liau Index
            content_readability_dale_chall float ratio of readability by the algotithm Dale–Chall Readability
            content_readability_flesh_kincaid float ratio of readability by the algotithm Flesch–Kincaid readability tests
            content_readability_smog float ratio of readability by the algotithm SMOG
            crawl_depth integer level of the page in the website hierarchy
            crawl_end string date and time of the end of crawling
in the format year-month-day:minutes:GMT_difference_hours:GMT_difference_minutes
for example: ‘2017-12-13 15:30:34 +00:00’
            crawled boolean status of the page
            deprecated_html_tags array array of deprecated html tags of the page
            duplicate_meta_tags array array of meta tags that are duplicated
            favicon string favicon of the page
            h1_count integer count of H1 tags
            h2_count integer count of H2 tags
            h3_count integer count of H3 tags
            have_deprecated_tags boolean presence of deprecated tags on the page
            have_doctype boolean presence of <!DOCTYPE html> on the page
            have_page_duplicates boolean presence of duplicate pages of the page
to get these pages you can call op_tasks_get_duplicates with parameter ‘page’
            have_enc_meta_tag boolean presence of tag <charset> on the page
            have_flash boolean presence of flash elements on the page
            have_frame boolean presence of frames on the page
            have_lorem_ipsum boolean presence of ‘lorem ipsum’ text on the page
            have_meta_description_duplicates boolean there are pages with duplicate content of meta tag description on the page
to get these pages you can call op_tasks_get_duplicates with parameter ‘description’
            have_recursive_canonical boolean presence of recursive canonical
            have_title_duplicates boolean there are pages with duplicate content of tag <title>
to get these pages you can call op_tasks_get_duplicates with parameter ‘title’
            images_count integer number of images on the page
            images_invalid_alt integer number of images with empty or missing tag alt
            images_invalid_title integer number of images with empty or missing tag title
            links_broken integer number of broken links from the page
pages with 4xx response code will have 0 value in this field
            links_external integer number of external links on the page
            links_referring integer number of referring links to the page
            links_internal integer number of internal links on the page
            meta_description string content of meta tag description
            meta_description_consistency float consistency of meta tag description with page content
from 0 to 1
            meta_description_length integer length of meta tag description content
            meta_keywords string content of meta tag keywords
            meta_keywords_consistency float consistency of meta tag keywords with page content
from 0 to 1
            page_allowed boolean page access is not disallowed by meta tag robots or X-Robots-Tag HTTP header
            page_redirect string url of page where the specified page is redirected to
the field is not empty only if a status code is 3xx
            page_size integer page size in bytes
            plain_text_rate float plaintext rate value (plain_text_size / page_size)
            plain_text_size integer page size in symbols
            response_code integer HTTP response code
            seo_friendly_url boolean page has an ‘SEO-friendly URL’
true if seo_friendly_url_characters_check=true and seo_friendly_url_dynamic_check=true and seo_friendly_url_keywords_check=true and seo_friendly_url_relative_length_check=true
            seo_friendly_url_characters_check boolean checking for symbols in accordance with Google recommendations
only uppercase and lowercase Latin characters, digits and dashes are allowed
‘true’ - if the test is passed.
            seo_friendly_url_dynamic_check boolean presence of dynamic parameters for a resource
like ‘https://example.com/some_url.php ?adsasd=5
if there are dynamic symbols in the URL then the status will be ‘false’
            seo_friendly_url_keywords_check boolean consistency of page url with meta tag keywords
if the keywords tag is empty or absent then the URL is being compared with the content of <title> tag. if the title tag absent then this test is considered as not passed
            seo_friendly_url_relative_length_check boolean checking the length of the relative way
url should not be longer than 120 characters
            ssl boolean usage of the secure SSL protocol
            ssl_handshake_time integer time (in milliseconds) spent on the ‘SSL handshake’
            string_containment_check boolean shows the presence or absence of the specified text in the on string_search_containment the page
if there is no text specified in the string_search_containment field, then the string_containment_check field will have ‘false’ value
            time_connection integer time (in milliseconds) spent on establishing the connection
            time_download integer time (in milliseconds) spent on the loading of resources
            time_total_load integer total time
time_connection + time_sending_request + time_waiting + time_download + ssl_handshake_time
            time_sending_request integer time (in milliseconds) spent on sending a request to a server
            time_waiting integer time spent waiting for the initial response, also known as the Time To First Byte
            title string content of tag <title>
            title_consistency integer consistency of tag <title> with page content
from 0 to 1
            title_length integer length of tag <title> content
            www boolean usage of the subdomain www

Get Filtered Pages

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

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

try {
    $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";
}

try {

    $post_array = array();
    $post_array[] = array(
        "task_id" => 151668277,
        "limit" => 1000,
        "offset" => 0,
        "filters" => array(
            array("h1_count", "=", 0),
            array("content_count_words", ">", 200)
        )
    );

    // POST /api/v2/op_tasks_get_pages_filter/$data
    $pages_post_result = $client->post("/v2/op_tasks_get_pages_filter", array('data' => $post_array));
    print_r($pages_post_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;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task srp_tasks_post()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };

            var postObject = new[]
            {
                new
                {
                    task_id = 151668277,
                    limit = 1000,
                    offset = 0,
                    filters = new[]
                    {
                        new object[] { "h1_count", "=", 0 },
                        new object[] { "content_count_words", ">", 200 }
                    }
                }
            };
            var pagePostResponse = await httpClient.PostAsync("v2/op_tasks_get_pages_filter", new StringContent(JsonConvert.SerializeObject(new {data = postObject})));
            var obj = JsonConvert.DeserializeObject<dynamic>(await pagePostResponse.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
            {
                foreach (var result in obj.results)
                {
                    var taskState = ((IEnumerable<dynamic>) result).First();
                    if (taskState.status == "error")
                        Console.WriteLine($"Error in task with post_id {taskState.post_id}. Code: {taskState.error.code} Message: {taskState.error.message}");
                    Console.WriteLine(taskState);
                }
            }
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

client = RestClient("login", "password")
post_data = dict()
post_data = [
    dict(
        task_id=151668277,
        limit=1000,
        offset=0,
        filters=[
            ["h1_count", "=", 0],
            ["content_count_words", ">", 200]
        ]
    )
]
response = client.post("/v2/op_tasks_get_pages_filter", dict(data=post_data))
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0402 sec.",
    "results_count": 5,
    "results": [
        {
            "post_id": "9#999#555",
            "post_site": "ranksonic.com",
            "task_id": 151668277,
            "string_search_containment": "the implementation",
            "crawl_max_pages": 10,
            "crawl_start": "2017-10-12 11:14:23.624803+03",
            "crawl_end": "2017-10-12 11:15:08.908063+03",
            "status": "crawled",
            "pages": [
                {
                    "address_full": "https:\/\/ranksonic.com\/compare.html",
                    "address_relative": "\/compare.html",
                    "canonical_another": false,
                    "canonical_page": "\/compare.html",
                    "canonical_page_recursive": "",
                    "content_charset": 65001,
                    "content_count_words": 203,
                    "content_encoding": "gzip",
                    "content_readability_ari": 8.418127,
                    "content_readability_coleman_liau": 11.8246012,
                    "content_readability_dale_chall": 8.241003,
                    "content_readability_flesh_kincaid": 44.30253,
                    "content_readability_smog": 16.4731522,
                    "crawl_depth": 1,
                    "crawl_end": "2017-10-12T08:15:00+00:00",
                    "crawled": true,
                    "deprecated_html_tags": [],
                    "duplicate_meta_tags": [],
                    "favicon": "\/themes\/default\/images\/favicon\/favicon_152x152.png",
                    "h1_count": 0,
                    "h2_count": 0,
                    "h3_count": 0,
                    "have_deprecated_tags": false,
                    "have_doctype": true,
                    "have_enc_meta_tag": true,
                    "have_flash": false,
                    "have_frame": false,
                    "have_lorem_ipsum": false,
                    "have_meta_description_duplicates": false,
                    "have_page_duplicates": false,
                    "have_recursive_canonical": false,
                    "have_title_duplicates": false,
                    "images_count": 5,
                    "images_invalid_alt": 0,
                    "images_invalid_title": 5,
                    "links_broken": 0,
                    "links_external": 10,
                    "links_internal": 16,
                    "links_referring": 20,
                    "meta_description": "SEO software comparison. Compare SEO Platforms. RankSonic SEO Platform.",
                    "meta_description_consistency": 0.428571433,
                    "meta_description_length": 71,
                    "meta_keywords": "ranksonic, seo, seo comparison",
                    "meta_keywords_consistency": 0.6666667,
                    "page_allowed": true,
                    "page_redirect": null,
                    "page_size": 107829,
                    "plain_text_rate": 0.224707633,
                    "plain_text_size": 24230,
                    "response_code": 200,
                    "seo_friendly_url": false,
                    "seo_friendly_url_characters_check": true,
                    "seo_friendly_url_dynamic_check": true,
                    "seo_friendly_url_keywords_check": false,
                    "seo_friendly_url_relative_length_check": true,
                    "ssl": true,
                    "ssl_handshake_time": 1,
                    "string_containment_check": true,
                    "time_connection": 3,
                    "time_download": 0,
                    "time_total_load": 48,
                    "time_sending_request": 0,
                    "time_waiting": 44,
                    "title": "SEO software comparison. Compare SEO Platforms. RankSonic SEO Platform.",
                    "title_consistency": 0.428571433,
                    "title_length": 71,
                    "www": false
                },


            ]
        }
    ]
}

Using this function, you can get a list of pages based on the parameters you specify. It is the primary function which you can use to get pages with on-page errors. For instance, you can set the parameters to receive the list of pages with not SEO-friendly URL, get the list of pages with too high loading time, get the list of pages with low readability score, etc.

All POST data should be sent in the JSON format (UTF-8 encoding). The pages filtering request is done using POST method when array of filtering request is sent to the data field. Each of the array elements has the following structure:

Name of a field Type Description
task_id integer unique identifier returned to you in the response from our service when you set a task
required field
limit integer maximum number of returned pages
offset integer offset in results array of returned pages
filter array array with filters
required field
      $field string the name of filtered field
required field
list of all available fields you can see in the results of Get Pages
      $operator string comparison operator
required field
available operators: >, =, !=, <>, <, <=, >=, contains, notcontains, startswith, endswith
      $value string comparison value
required field

You will receive array from the API server in the results field where you will find results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information in the error array
error array informational array of error
only if status=“error”
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the results array
results array results array
      post_id string index in the array received in a POST array
      post_site string site received in a POST array
      task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time
      string_search_containment string string_search_containment received in a POST request
default value: ‘null’.
      crawl_max_pages integer maximum number of test pages
      crawl_start string date and time of the start of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-14 11:50:01 +02:00’
      crawl_end string date and time of the end of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-13 15:30:34 +02:00’
      status string current status of the task
possible values: “in_queue”, “crawling”, “crawled”, “crawl_paused”
      pages array array of pages
            address_full string full page address
            address_relative string relative page address
more info about relative
            absent_h1_tags integer number of pages without H1 tags
            canonical_another boolean presence of another canonical page
‘true’ - if page is non-canonical
            canonical_page string canonical page
            canonical_page_recursive string recursive canonical page
            content_charset integer content character encoding
list of charset
            content_count_words integer number of words in the content of the page
exceptions are the a tags, etc. the text that is present in the body tag is being parsed. the text that is in script, style, a, noscript, select, button, embed, framest tags as well as comments is ignored
            content_encoding string compression algorithm of the content of the page
more information
            content_readability_ari float ratio of readability by the algotithm Automated Readability Index (ARI)
            content_readability_coleman_liau float ratio of readability by the algotithm Coleman–Liau Index
            content_readability_dale_chall float ratio of readability by the algotithm Dale–Chall Readability
            content_readability_flesh_kincaid float ratio of readability by the algotithm Flesch–Kincaid readability tests
            content_readability_smog float ratio of readability by the algotithm SMOG
            crawl_depth integer level of the page in the website hierarchy
            crawl_end string date and time of the end of crawling
in the format year-month-day:minutes:GMT_difference_hours:GMT_difference_minutes
for example: ‘2017-12-13 15:30:34 +00:00’
            crawled boolean status of the page
            deprecated_html_tags array array of deprecated html tags of the page
            duplicate_meta_tags array array of meta tags that are duplicated
            favicon string favicon of the page
            h1_count integer count of H1 tags
            h2_count integer count of H2 tags
            h3_count integer count of H3 tags
            have_deprecated_tags boolean presence of deprecated tags on the page
            have_doctype boolean presence of <!DOCTYPE html> on the page
            have_page_duplicates boolean presence of duplicate pages of the page
to get these pages you can call op_tasks_get_duplicates with parameter ‘page’
            have_enc_meta_tag boolean presence of tag <charset> on the page
            have_flash boolean presence of flash elements on the page
            have_frame boolean presence of frames on the page
            have_lorem_ipsum boolean presence of ‘lorem ipsum’ text on the page
            have_meta_description_duplicates boolean there are pages with duplicate content of meta tag description on the page
to get these pages you can call op_tasks_get_duplicates with parameter ‘description’
            have_recursive_canonical boolean presence of recursive canonical
            have_title_duplicates boolean there are pages with duplicate content of tag <title>
to get these pages you can call op_tasks_get_duplicates with parameter ‘title’
            images_count integer number of images on the page
            images_invalid_alt integer number of images with empty or missing tag alt
            images_invalid_title integer number of images with empty or missing tag title
            links_broken integer number of broken links from the page
pages with 4xx response code will have 0 value in this field
            links_external integer number of external links on the page
            links_referring integer number of referring links to the page
            links_internal integer number of internal links on the page
            meta_description string content of meta tag description
            meta_description_consistency float consistency of meta tag description with page content
from 0 to 1
            meta_description_length integer length of meta tag description content
            meta_keywords string content of meta tag keywords
            meta_keywords_consistency float consistency of meta tag keywords with page content
from 0 to 1
            page_allowed boolean page access is not disallowed by meta tag robots or X-Robots-Tag HTTP header
            page_redirect string url of page where the specified page is redirected to
the field is not empty only if a status code is 3xx
            page_size integer page size in bytes
            plain_text_rate float plaintext rate value (plain_text_size / page_size)
            plain_text_size integer page size in symbols
            response_code integer HTTP response code
            seo_friendly_url boolean page has an ‘SEO-friendly URL’
true if seo_friendly_url_characters_check=true and seo_friendly_url_dynamic_check=true and seo_friendly_url_keywords_check=true and seo_friendly_url_relative_length_check=true
            seo_friendly_url_characters_check boolean checking for symbols in accordance with Google recommendations
only uppercase and lowercase Latin characters, digits and dashes are allowed
‘true’ - if the test is passed.
            seo_friendly_url_dynamic_check boolean presence of dynamic parameters for a resource
like ‘https://example.com/some_url.php ?adsasd=5
if there are dynamic symbols in the URL then the status will be ‘false’
            seo_friendly_url_keywords_check boolean consistency of page url with meta tag keywords
if the keywords tag is empty or absent then the URL is being compared with the content of <title> tag. if the title tag absent then this test is considered as not passed
            seo_friendly_url_relative_length_check boolean checking the length of the relative way
url should not be longer than 120 characters
            ssl boolean usage of the secure SSL protocol
            ssl_handshake_time integer time (in milliseconds) spent on the ‘SSL handshake’
            string_containment_check boolean shows the presence or absence of the specified text in the on string_search_containment the page
if there is no text specified in the string_search_containment field, then the string_containment_check field will have ‘false’ value
            time_connection integer time (in milliseconds) spent on establishing the connection
            time_download integer time (in milliseconds) spent on the loading of resources
            time_total_load integer total time
time_connection + time_sending_request + time_waiting + time_download + ssl_handshake_time
            time_sending_request integer time (in milliseconds) spent on sending a request to a server
            time_waiting integer time spent waiting for the initial response, also known as the Time To First Byte
            title string content of tag <title>
            title_consistency integer consistency of tag <title> with page content
from 0 to 1
            title_length integer length of tag <title> content
            www boolean usage of the subdomain www

Get Broken Pages

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

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

try {
    $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";
}

try {

    // GET /api/v2/op_tasks_get_broken_pages/$task_id
    $task_get_result = $client->get("v2/op_tasks_get_broken_pages/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;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task rnk_tasks_get()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),
                DefaultRequestHeaders = {Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}
            };

            var taskid = 123456789;
            response = await httpClient.GetAsync($"v2/op_tasks_get_broken_pages/{taskid}");
            obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else if (obj.results_count != 0)
            {
                foreach (var result in obj.results)
                {
                    var resultItem = ((IEnumerable<dynamic>)result).First();
                    Console.WriteLine(resultItem);
                }
            }
            else
                Console.WriteLine("no results");
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

client = RestClient("login", "password")
response = client.get("/v2/op_tasks_get_broken_pages/123456789")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0675 sec.",
    "results_count": 1,
    "results": [
        {
            "post_id": "10##4",
            "post_site": "ranksonic.com",
            "task_id": 130491671,
            "string_search_containment": "the implementation",
            "crawl_max_pages": 10,
            "crawl_start": "2017-10-12 11:14:23.624803+03",
            "crawl_end": "2017-10-12 11:15:08.908063+03",
            "status": "crawled",
            "broken_pages": [
                {
                    "address_full": "https:\/\/ranksonic.com\/features-common.html",
                    "address_relative": "\/features-common.html",
                    "canonical_another": false,
                    "canonical_page": null,
                    "canonical_page_recursive": "",
                    "content_charset": 0,
                    "content_count_words": 0,
                    "content_encoding": "none",
                    "content_readability_ari": 0,
                    "content_readability_coleman_liau": 0,
                    "content_readability_dale_chall": 0,
                    "content_readability_flesh_kincaid": 0,
                    "content_readability_smog": 0,
                    "crawl_depth": 2,
                    "crawl_end": "2017-10-12T08:15:00+00:00",
                    "crawled": true,
                    "deprecated_html_tags": [],
                    "duplicate_meta_tags": [],
                    "favicon": "",
                    "h1_count": 0,
                    "h2_count": 0,
                    "h3_count": 0,
                    "have_deprecated_tags": false,
                    "have_doctype": false,
                    "have_enc_meta_tag": false,
                    "have_flash": false,
                    "have_frame": false,
                    "have_lorem_ipsum": false,
                    "have_meta_description_duplicates": false,
                    "have_page_duplicates": false,
                    "have_recursive_canonical": false,
                    "have_title_duplicates": false,
                    "images_count": 0,
                    "images_invalid_alt": 0,
                    "images_invalid_title": 0,
                    "links_broken": 0,
                    "links_external": 0,
                    "links_internal": 0,
                    "links_referring": 14,
                    "meta_description": null,
                    "meta_description_consistency": 0,
                    "meta_description_length": 0,
                    "meta_keywords": "",
                    "meta_keywords_consistency": 0,
                    "page_allowed": true,
                    "page_redirect": null,
                    "page_size": 0,
                    "plain_text_rate": 0,
                    "plain_text_size": 0,
                    "response_code": 404,
                    "seo_friendly_url": false,
                    "seo_friendly_url_characters_check": false,
                    "seo_friendly_url_dynamic_check": false,
                    "seo_friendly_url_keywords_check": false,
                    "seo_friendly_url_relative_length_check": false,
                    "ssl": false,
                    "ssl_handshake_time": 0,
                    "string_containment_check": true,
                    "time_connection": 35,
                    "time_download": 0,
                    "time_total_load": 461,
                    "time_sending_request": 0,
                    "time_waiting": 426,
                    "title": null,
                    "title_consistency": 0,
                    "title_length": 0,
                    "www": false
                }
            ]
        }
    ]
}

Using this function, you can get a list of broken pages (4xx response code). There may be referring links from other pages of a website to the broken pages that don’t exist.

You will receive array from the API server in the results field where you will find results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information in the error array
error array informational array of error
only if status=“error”
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the results array
results array results array
      post_id string index in the array received in a POST array
      post_site string site received in a POST array
      task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time
      string_search_containment string string_search_containment received in a POST request
default value: ‘null’.
      crawl_max_pages integer maximum number of test pages
      crawl_start string date and time of the start of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-14 11:50:01 +02:00’
      crawl_end string date and time of the end of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-13 15:30:34 +02:00’
      status string current status of the task
possible values: “in_queue”, “crawling”, “crawled”, “crawl_paused”
      broken_pages array array of broken pages
            address_full string full page address
            address_relative string relative page address
more info about relative
            absent_h1_tags integer number of pages without H1 tags
            canonical_another boolean presence of another canonical page
‘true’ - if page is non-canonical
            canonical_page string canonical page
            canonical_page_recursive string recursive canonical page
            content_charset integer content character encoding
list of charset
            content_count_words integer number of words in the content of the page
exceptions are the a tags, etc. the text that is present in the body tag is being parsed. the text that is in script, style, a, noscript, select, button, embed, framest tags as well as comments is ignored
            content_encoding string compression algorithm of the content of the page
more information
            content_readability_ari float ratio of readability by the algotithm Automated Readability Index (ARI)
            content_readability_coleman_liau float ratio of readability by the algotithm Coleman–Liau Index
            content_readability_dale_chall float ratio of readability by the algotithm Dale–Chall Readability
            content_readability_flesh_kincaid float ratio of readability by the algotithm Flesch–Kincaid readability tests
            content_readability_smog float ratio of readability by the algotithm SMOG
            crawl_depth integer level of the page in the website hierarchy
            crawl_end string date and time of the end of crawling
in the format year-month-day:minutes:GMT_difference_hours:GMT_difference_minutes
for example: ‘2017-12-13 15:30:34 +00:00’
            crawled boolean status of the page
            deprecated_html_tags array array of deprecated html tags of the page
            duplicate_meta_tags array array of meta tags that are duplicated
            favicon string favicon of the page
            h1_count integer count of H1 tags
            h2_count integer count of H2 tags
            h3_count integer count of H3 tags
            have_deprecated_tags boolean presence of deprecated tags on the page
            have_doctype boolean presence of <!DOCTYPE html> on the page
            have_page_duplicates boolean presence of duplicate pages of the page
to get these pages you can call op_tasks_get_duplicates with parameter ‘page’
            have_enc_meta_tag boolean presence of tag <charset> on the page
            have_flash boolean presence of flash elements on the page
            have_frame boolean presence of frames on the page
            have_lorem_ipsum boolean presence of ‘lorem ipsum’ text on the page
            have_meta_description_duplicates boolean there are pages with duplicate content of meta tag description on the page
to get these pages you can call op_tasks_get_duplicates with parameter ‘description’
            have_recursive_canonical boolean presence of recursive canonical
            have_title_duplicates boolean there are pages with duplicate content of tag <title>
to get these pages you can call op_tasks_get_duplicates with parameter ‘title’
            images_count integer number of images on the page
            images_invalid_alt integer number of images with empty or missing tag alt
            images_invalid_title integer number of images with empty or missing tag title
            links_broken integer number of broken links from the page
pages with 4xx response code will have 0 value in this field
            links_external integer number of external links on the page
            links_referring integer number of referring links to the page
            links_internal integer number of internal links on the page
            meta_description string content of meta tag description
            meta_description_consistency float consistency of meta tag description with page content
from 0 to 1
            meta_description_length integer length of meta tag description content
            meta_keywords string content of meta tag keywords
            meta_keywords_consistency float consistency of meta tag keywords with page content
from 0 to 1
            page_allowed boolean page access is not disallowed by meta tag robots or X-Robots-Tag HTTP header
            page_redirect string url of page where the specified page is redirected to
the field is not empty only if a status code is 3xx
            page_size integer page size in bytes
            plain_text_rate float plaintext rate value (plain_text_size / page_size)
            plain_text_size integer page size in symbols
            response_code integer HTTP response code
            seo_friendly_url boolean page has an ‘SEO-friendly URL’
true if seo_friendly_url_characters_check=true and seo_friendly_url_dynamic_check=true and seo_friendly_url_keywords_check=true and seo_friendly_url_relative_length_check=true
            seo_friendly_url_characters_check boolean checking for symbols in accordance with Google recommendations
only uppercase and lowercase Latin characters, digits and dashes are allowed
‘true’ - if the test is passed
            seo_friendly_url_dynamic_check boolean presence of dynamic parameters for a resource
like ‘https://example.com/some_url.php ?adsasd=5
if there are dynamic symbols in the URL then the status will be ‘false’
            seo_friendly_url_keywords_check boolean consistency of page url with meta tag keywords
if the keywords tag is empty or absent then the URL is being compared with the content of <title> tag. if the title tag absent then this test is considered as not passed
            seo_friendly_url_relative_length_check boolean checking the length of the relative way
url should not be longer than 120 characters
            ssl boolean usage of the secure SSL protocol
            ssl_handshake_time integer time (in milliseconds) spent on the ‘SSL handshake’
            string_containment_check boolean shows the presence or absence of the specified text in the on string_search_containment the page
if there is no text specified in the string_search_containment field, then the string_containment_check field will have ‘false’ value
            time_connection integer time (in milliseconds) spent on establishing the connection
            time_download integer time (in milliseconds) spent on the loading of resources
            time_total_load integer total time
time_connection + time_sending_request + time_waiting + time_download + ssl_handshake_time
            time_sending_request integer time (in milliseconds) spent on sending a request to a server
            time_waiting integer time spent waiting for the initial response, also known as the Time To First Byte
            title string content of tag <title>
            title_consistency integer consistency of tag <title> with page content
from 0 to 1
            title_length integer length of tag <title> content
            www boolean usage of the subdomain www

Get Duplicate Pages

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

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

try {
    $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";
}

try {

    // GET /api/v2/op_tasks_get_duplicates/$task_id
    $task_get_result = $client->get("v2/op_tasks_get_duplicates/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;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task rnk_tasks_get()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),
                DefaultRequestHeaders = {Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}
            };

            var taskid = 123456789;
            response = await httpClient.GetAsync($"v2/op_tasks_get_duplicates/{taskid}");
            obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else if (obj.results_count != 0)
            {
                foreach (var result in obj.results)
                {
                    var resultItem = ((IEnumerable<dynamic>)result).First();
                    Console.WriteLine(resultItem);
                }
            }
            else
                Console.WriteLine("no results");
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

client = RestClient("login", "password")
response = client.get("/v2/op_tasks_get_duplicates/123456789")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1450 sec.",
    "results_count": 21,
    "results": [
        {
            "post_id": "9999555",
            "post_site": "alpinen-gold.com",            
            "task_id": 136371534,
            "string_search_containment": null,
            "crawl_max_pages": 100,
            "crawl_start": "2017-10-12 11:14:23.624803+03",
            "crawl_end": "2017-10-12 11:15:08.908063+03",
            "status": "crawled",
            "duplicates": [
                {
                    "accumulator": "ALPINEN GOLD - Letter D (котята мейн кун и щенки сенбернара)",
                    "pages": [
                        {
                            "accumulator": "ALPINEN GOLD - Letter D (котята мейн кун и щенки сенбернара)",
                            "address_full": "http:\/\/alpinen-gold.com\/kotyata\/letter-d\/",
                            "address_relative": "\/kotyata\/letter-d\/",
                            "canonical_another": false,
                            "canonical_page": "\/kotyata\/letter-d\/",
                            "canonical_page_recursive": "",
                            "content_charset": 65001,
                            "content_count_words": 68,
                            "content_encoding": "gzip",
                            "content_readability_ari": 6.24265766,
                            "content_readability_coleman_liau": 2.14972973,
                            "content_readability_dale_chall": 4.42414236,
                            "content_readability_flesh_kincaid": 66.9806747,
                            "content_readability_smog": 15.9031887,
                            "crawl_depth": 2,
                            "crawl_end": "2017-10-12T08:15:00+00:00",
                            "crawled": true,
                            "deprecated_html_tags": [],
                            "duplicate_meta_tags": [],
                            "favicon": "\/wp-content\/themes\/theme1760\/favicon.ico",
                            "h1_count": 1,
                            "h2_count": 1,
                            "h3_count": 2,
                            "have_deprecated_tags": false,
                            "have_doctype": true,
                            "have_enc_meta_tag": true,
                            "have_flash": false,
                            "have_frame": false,
                            "have_lorem_ipsum": false,
                            "have_meta_description_duplicates": false,
                            "have_page_duplicates": false,
                            "have_recursive_canonical": false,
                            "have_title_duplicates": false,
                            "images_count": 2,
                            "images_invalid_alt": 0,
                            "images_invalid_title": 0,
                            "links_broken": 0,
                            "links_external": 3,
                            "links_internal": 35,
                            "links_referring": 0,
                            "meta_description": "» Letter D | Питомник ALPINEN GOLD",
                            "meta_description_consistency": 0,
                            "meta_description_length": 34,
                            "meta_keywords": "",
                            "meta_keywords_consistency": 0,
                            "page_allowed": true,
                            "page_redirect": null,
                            "page_size": 25476,
                            "plain_text_rate": 0.07878837,
                            "plain_text_size": 1956,
                            "response_code": 200,
                            "seo_friendly_url": false,
                            "seo_friendly_url_characters_check": false,
                            "seo_friendly_url_dynamic_check": false,
                            "seo_friendly_url_keywords_check": false,
                            "seo_friendly_url_relative_length_check": false,
                            "ssl": false,
                            "ssl_handshake_time": 0,
                            "string_containment_check": false,
                            "time_connection": 35,
                            "time_download": 1,
                            "time_total_load": 1069,
                            "time_sending_request": 0,
                            "time_waiting": 1033,
                            "title": "ALPINEN GOLD - Letter D (котята мейн кун и щенки сенбернара)",
                            "title_consistency": 0,
                            "title_length": 60,
                            "www": false
                        },


                    ]
                },

            ]
        }
    ]
}

Using this function, you can get a list of duplicate pages. Duplicates can be received based on some accumulator, for instance, title, description or content of a page.

$duplicate_type - can have the following string values: ‘title’, ‘description’, ‘page’. Default value is ‘title’.

You will receive array from the API server in the results field where you will find results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information in the error array
error array informational array of error
only if status=“error”
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the results array
results array results array
      post_id string index in the array received in a POST array
      post_site string site received in a POST array
      task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time
      string_search_containment string string_search_containment received in a POST request
default value: ‘null’.
      crawl_max_pages integer maximum number of test pages
      crawl_start string date and time of the start of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-14 11:50:01 +02:00’
      crawl_end string date and time of the end of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-13 15:30:34 +02:00’
      status string current status of the task
possible values: “in_queue”, “crawling”, “crawled”, “crawl_paused”
      duplicates array array of duplicate pages
            accumulator string the sign on which the pages were grouped
            pages array array of duplicate pages with the accumulator
                  address_full string full page address
                  address_relative string relative page address
                  absent_h1_tags integer number of pages without H1 tags
                  canonical_another boolean presence of another canonical page
‘true’ - if page is non-canonical
                  canonical_page string canonical page
                  canonical_page_recursive string recursive canonical page
                  content_charset integer content character encoding
list of charset
                  content_count_words integer number of words in the content of the page
exceptions are the a tags, etc. the text that is present in the body tag is being parsed. the text that is in script, style, a, noscript, select, button, embed, framest tags as well as comments is ignored
                  content_encoding string compression algorithm of the content of the page
more information
                  content_readability_ari float ratio of readability by the algotithm Automated Readability Index (ARI)
                  content_readability_coleman_liau float ratio of readability by the algotithm Coleman–Liau Index
                  content_readability_dale_chall float ratio of readability by the algotithm Dale–Chall Readability
                  content_readability_flesh_kincaid float ratio of readability by the algotithm Flesch–Kincaid readability tests
                  content_readability_smog float ratio of readability by the algotithm SMOG
                  crawl_depth integer level of the page in the website hierarchy
                  crawl_end string date and time of the end of crawling
in the format year-month-day:minutes:GMT_difference_hours:GMT_difference_minutes
for example: ‘2017-12-13 15:30:34 +00:00’
                  crawled boolean status of the page
                  deprecated_html_tags array array of deprecated html tags of the page
                  duplicate_meta_tags array array of meta tags that are duplicated
                  favicon string favicon of the page
                  h1_count integer count of H1 tags
                  h2_count integer count of H2 tags
                  h3_count integer count of H3 tags
                  have_deprecated_tags boolean presence of deprecated tags on the page
                  have_doctype boolean presence of <!DOCTYPE html> on the page
                  have_page_duplicates boolean presence of duplicate pages of the page
to get these pages you can call op_tasks_get_duplicates with parameter ‘page’
                  have_enc_meta_tag boolean presence of tag <charset> on the page
                  have_flash boolean presence of flash elements on the page
                  have_frame boolean presence of frames on the page
                  have_lorem_ipsum boolean presence of ‘lorem ipsum’ text on the page
                  have_meta_description_duplicates boolean there are pages with duplicate content of meta tag description on the page
to get these pages you can call op_tasks_get_duplicates with parameter ‘description’
                  have_recursive_canonical boolean presence of recursive canonical
                  have_title_duplicates boolean there are pages with duplicate content of tag <title>
to get these pages you can call op_tasks_get_duplicates with parameter ‘title’
                  images_count integer number of images on the page
                  images_invalid_alt integer number of images with empty or missing tag alt
                  images_invalid_title integer number of images with empty or missing tag title
                  links_broken integer number of broken links from the page
pages with 4xx response code will have 0 value in this field
                  links_external integer number of external links on the page
                  links_referring integer number of referring links to the page
                  links_internal integer number of internal links on the page
                  meta_description string content of meta tag description
                  meta_description_consistency float consistency of meta tag description with page content
from 0 to 1
                  meta_description_length integer length of meta tag description content
                  meta_keywords string content of meta tag keywords
                  meta_keywords_consistency float consistency of meta tag keywords with page content
from 0 to 1
                  page_allowed boolean page access is not disallowed by meta tag robots or X-Robots-Tag HTTP header
                  page_redirect string url of page where the specified page is redirected to
the field is not empty only if a status code is 3xx
                  page_size integer page size in bytes
                  plain_text_rate float plaintext rate value (plain_text_size / page_size)
                  plain_text_size integer page size in symbols
                  response_code integer HTTP response code
                  seo_friendly_url boolean page has an ‘SEO-friendly URL’
true if seo_friendly_url_characters_check=true and seo_friendly_url_dynamic_check=true and seo_friendly_url_keywords_check=true and seo_friendly_url_relative_length_check=true
                  seo_friendly_url_characters_check boolean checking for symbols in accordance with Google recommendations
only uppercase and lowercase Latin characters, digits and dashes are allowed
‘true’ - if the test is passed.
                  seo_friendly_url_dynamic_check boolean presence of dynamic parameters for a resource
like ‘https://example.com/some_url.php ?adsasd=5
if there are dynamic symbols in the URL then the status will be ‘false’
                  seo_friendly_url_keywords_check boolean consistency of page url with meta tag keywords
if the keywords tag is empty or absent then the URL is being compared with the content of <title> tag. if the title tag absent then this test is considered as not passed
                  seo_friendly_url_relative_length_check boolean checking the length of the relative way
url should not be longer than 120 characters
                  ssl boolean usage of the secure SSL protocol
                  ssl_handshake_time integer time (in milliseconds) spent on the ‘SSL handshake’
                  string_containment_check boolean shows the presence or absence of the specified text in the on string_search_containment the page
if there is no text specified in the string_search_containment field, then the string_containment_check field will have ‘false’ value
                  time_connection integer time (in milliseconds) spent on establishing the connection
                  time_download integer time (in milliseconds) spent on the loading of resources
                  time_sending_request integer time (in milliseconds) spent on sending a request to a server
                  time_total_load integer total time
time_connection + time_sending_request + time_waiting + time_download + ssl_handshake_time
                  time_waiting integer time spent waiting for the initial response, also known as the Time To First Byte
                  title string content of tag <title>
                  title_consistency integer consistency of tag <title> with page content
from 0 to 1
                  title_length integer length of tag <title> content
                  www boolean usage of the subdomain www

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

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

try {
    $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";
}

try {

    // GET /api/v2/op_tasks_get_links_to/$task_id/$page
    $task_get_result = $client->get("v2/op_tasks_get_links_to/123456789/'/relative/page/on/site.html'");
    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;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task rnk_tasks_get()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),
                DefaultRequestHeaders = {Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}
            };

            var taskid = 123456789;
            var pageonsite = "'/relative/page/on/site.html'";
            response = await httpClient.GetAsync($"v2/op_tasks_get_links_to/{taskid}/{pageonsite}");
            obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else if (obj.results_count != 0)
            {
                foreach (var result in obj.results)
                {
                    var resultItem = ((IEnumerable<dynamic>)result).First();
                    Console.WriteLine(resultItem);
                }
            }
            else
                Console.WriteLine("no results");
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

client = RestClient("login", "password")
response = client.get("/v2/op_tasks_get_links_to/123456789/'/relative/page/on/site.html'")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0741 sec.",
    "results_count": 14,
    "results": [
        {
            "post_id": "9999555",
            "post_site": "alpinen-gold.com",
            "task_id": 136371534,
            "string_search_containment": null,
            "crawl_max_pages": 100,
            "crawl_start": "2017-10-12 11:14:23.624803+03",
            "crawl_end": "2017-10-12 11:15:08.908063+03",
            "status": "crawled",
            "links_to": [
                {
                    "alt": "DAIQUIRI - DSC_0081",
                    "anchor": "",
                    "link_from": "http:\/\/alpinen-gold.com\/2017\/10\/",
                    "link_to": "http:\/\/alpinen-gold.com\/kotyata\/letter-d\/",
                    "nofollow": false,
                    "page_from": "\/2017\/10\/",
                    "page_to": "\/kotyata\/letter-d\/",
                    "relative": true,
                    "ssl_from_use": false,
                    "ssl_to_use": false,
                    "state": "alive",
                    "text_post": "",
                    "text_pre": "",
                    "type": "image",
                    "www_from_use": false,
                    "www_to_use": false
                },
                {
                    "alt": null,
                    "anchor": "...",
                    "link_from": "http:\/\/alpinen-gold.com\/2017\/10\/",
                    "link_to": "http:\/\/alpinen-gold.com\/kotyata\/letter-d\/",
                    "nofollow": false,
                    "page_from": "\/2017\/10\/",
                    "page_to": "\/kotyata\/letter-d\/",
                    "relative": true,
                    "ssl_from_use": false,
                    "ssl_to_use": false,
                    "state": "alive",
                    "text_post": "",
                    "text_pre": ".",
                    "type": "href",
                    "www_from_use": false,
                    "www_to_use": false
                },

                {
                    "alt": null,
                    "anchor": null,
                    "link_from": "http:\/\/alpinen-gold.com\/kotyata\/letter-d\/",
                    "link_to": "http:\/\/alpinen-gold.com\/kotyata\/letter-d\/",
                    "nofollow": false,
                    "page_from": "\/kotyata\/letter-d\/",
                    "page_to": "\/kotyata\/letter-d\/",
                    "relative": true,
                    "ssl_from_use": false,
                    "ssl_to_use": false,
                    "state": "alive",
                    "text_post": null,
                    "text_pre": null,
                    "type": "canonical",
                    "www_from_use": false,
                    "www_to_use": false
                }
            ]
        }
    ]
}

Using this function, you can get a list of all referring links to a certain page.

$page - is a relative page address on a site. The page value must be enclosed in single quotes, like this
https://api.dataforseo.com/v2/op_tasks_get_links_to/12345/'/page/on/site.html'

You will receive array from the API server in the results field where you will find results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information in the error array
error array informational array of error
only if status=“error”
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the results array
results array results array
      post_id string index in the array received in a POST array
      post_site string site received in a POST array
      task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time
      string_search_containment string string_search_containment received in a POST request
default value: ‘null’.
      crawl_max_pages integer maximum number of test pages
      crawl_start string date and time of the start of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-14 11:50:01 +02:00’
      crawl_end string date and time of the end of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-13 15:30:34 +02:00’
      status string current status of the task
possible values: “in_queue”, “crawling”, “crawled”, “crawl_paused”
      links_to array array of referring links
            alt string alt attribute of an element
            anchor string an anchor of a link
            link_from string full page address of referring page
            link_to string full page address of requested page
            nofollow boolean presence of nofollow attribute on the referring page
information about “nofollow”: “nofollow” provides a way for webmasters to tell search engines “don’t follow links on this page” or “don’t follow this specific link.”
            page_from string relative page address of referring page
            page_to string relative page address of requested page
            relative boolean relevance of the referring page
            ssl_from_use boolean ssl used on the referring page
            ssl_to_use boolean ssl used on the requested page
            state string current link state
possible values: ‘dead’ or ‘alive’
            text_post string text after anchor
            text_pre string text before anchor
            type string type of link
possible values: ‘href’, ‘image’
            www_from_use boolean www. subdomain used on the referring page
            www_to_use string www. subdomain used on the requested page

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

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

try {
    $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";
}

try {

    // GET /api/v2/op_tasks_get_links_from/$task_id/$page
    $task_get_result = $client->get("v2/op_tasks_get_links_from/123456789/'/relative/page/on/site.html'");
    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;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task rnk_tasks_get()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),
                DefaultRequestHeaders = {Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}
            };

            var taskid = 123456789;
            var pageonsite = "'/relative/page/on/site.html'";
            response = await httpClient.GetAsync($"v2/op_tasks_get_links_from/{taskid}/{pageonsite}");
            obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else if (obj.results_count != 0)
            {
                foreach (var result in obj.results)
                {
                    var resultItem = ((IEnumerable<dynamic>)result).First();
                    Console.WriteLine(resultItem);
                }
            }
            else
                Console.WriteLine("no results");
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

client = RestClient("login", "password")
response = client.get("/v2/op_tasks_get_links_from/123456789/'/relative/page/on/site.html'")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0668 sec.",
    "results_count": 38,
    "results": [
        {
            "post_id": "9999555",
            "post_site": "alpinen-gold.com",
            "task_id": 136371534,
            "string_search_containment": null,
            "crawl_max_pages": 100,
            "crawl_start": "2017-10-12 11:14:23.624803+03",
            "crawl_end": "2017-10-12 11:15:08.908063+03",
            "status": "crawled",
            "links_from": [
                {
                    "alt": null,
                    "anchor": "Facebook",
                    "link_from": "http:\/\/alpinen-gold.com\/kotyata\/letter-d\/",
                    "link_to": "https:\/\/facebook.com\/nina.babaeva.14",
                    "nofollow": false,
                    "page_from": "\/kotyata\/letter-d\/",
                    "page_to": "facebook.com\/nina.babaeva.14",
                    "relative": false,
                    "ssl_from_use": false,
                    "ssl_to_use": true,
                    "state": "alive",
                    "text_post": "",
                    "text_pre": "",
                    "type": "href",
                    "www_from_use": false,
                    "www_to_use": true
                },
                {
                    "alt": null,
                    "anchor": "gavr1l0",
                    "link_from": "http:\/\/alpinen-gold.com\/kotyata\/letter-d\/",
                    "link_to": "http:\/\/gavr1l0.pro\/",
                    "nofollow": false,
                    "page_from": "\/kotyata\/letter-d\/",
                    "page_to": "gavr1l0.pro\/",
                    "relative": false,
                    "ssl_from_use": false,
                    "ssl_to_use": false,
                    "state": "alive",
                    "text_post": "",
                    "text_pre": "bsp;       разработка сайта:",
                    "type": "href",
                    "www_from_use": false,
                    "www_to_use": false
                },
                {
                    "alt": null,
                    "anchor": "Одноклассники",
                    "link_from": "http:\/\/alpinen-gold.com\/kotyata\/letter-d\/",
                    "link_to": "http:\/\/odnoklassniki.ru\/pitomnik.alpinengold",
                    "nofollow": false,
                    "page_from": "\/kotyata\/letter-d\/",
                    "page_to": "odnoklassniki.ru\/pitomnik.alpinengold",
                    "relative": false,
                    "ssl_from_use": false,
                    "ssl_to_use": false,
                    "state": "alive",
                    "text_post": "",
                    "text_pre": "",
                    "type": "href",
                    "www_from_use": false,
                    "www_to_use": true
                },
                {
                    "alt": null,
                    "anchor": "ALPINEN GOLD",
                    "link_from": "http:\/\/alpinen-gold.com\/kotyata\/letter-d\/",
                    "link_to": "http:\/\/alpinen-gold.com\/",
                    "nofollow": false,
                    "page_from": "\/kotyata\/letter-d\/",
                    "page_to": "\/",
                    "relative": true,
                    "ssl_from_use": false,
                    "ssl_to_use": false,
                    "state": "alive",
                    "text_post": "",
                    "text_pre": "",
                    "type": "href",
                    "www_from_use": false,
                    "www_to_use": false
                },
                {
                    "alt": null,
                    "anchor": "Главная",
                    "link_from": "http:\/\/alpinen-gold.com\/kotyata\/letter-d\/",
                    "link_to": "http:\/\/alpinen-gold.com\/",
                    "nofollow": false,
                    "page_from": "\/kotyata\/letter-d\/",
                    "page_to": "\/",
                    "relative": true,
                    "ssl_from_use": false,
                    "ssl_to_use": false,
                    "state": "alive",
                    "text_post": "",
                    "text_pre": "",
                    "type": "href",
                    "www_from_use": false,
                    "www_to_use": false
                },


            ]
        }
    ]
}

Using this function, you can get a list of external and internal links from a certain page.

$page - is a relative page address on a site. The page value must be enclosed in single quotes, like this
https://api.dataforseo.com/v2/op_tasks_get_links_from/12345/'/page/on/site.html'

You will receive array from the API server in the results field where you will find results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information in the error array
error array informational array of error
only if status=“error”
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the results array
results array results array
      post_id string index in the array received in a POST array
      post_site string site received in a POST array
      task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time
      string_search_containment string string_search_containment received in a POST request
default value: ‘null’.
      crawl_max_pages integer maximum number of test pages
      crawl_start string date and time of the start of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-14 11:50:01 +02:00’
      crawl_end string date and time of the end of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-13 15:30:34 +02:00’
      status string current status of the task
possible values: “in_queue”, “crawling”, “crawled”, “crawl_paused”
      links_from array array of links
            alt string alt attribute of an element
            anchor string an anchor of a link
            link_from string full page address of the requested page
            link_to string full page address of a link from the page
            nofollow boolean presence of nofollow attribute on the requested page
information about “nofollow”: “nofollow” provides a way for webmasters to tell search engines “don’t follow links on this page” or “don’t follow this specific link.”
            page_from string relative page address of the requested page
            page_to string relative page address of a link from the page
            relative boolean relevance of a link from the page
            ssl_from_use boolean ssl used on the requested page
            ssl_to_use boolean ssl used on the result page
            state string current link state
possible values: ‘dead’ or ‘alive’
            text_post string text after anchor
            text_pre string text before anchor
            type string type of link
possible values: ‘href’, ‘image’
            www_from_use boolean www. subdomain used on the requested page
            www_to_use string www. subdomain used on the result page

Get H Tags On Page

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

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

try {
    $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";
}

try {

    // GET /api/v2/op_tasks_htags_on_page/$task_id/$page
    $task_get_result = $client->get("v2/op_tasks_htags_on_page/123456789/'/relative/page/on/site.html'");
    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;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task rnk_tasks_get()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),
                DefaultRequestHeaders = {Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}
            };

            var taskid = 123456789;
            var pageonsite = "'/relative/page/on/site.html'";
            response = await httpClient.GetAsync($"v2/op_tasks_htags_on_page/{taskid}/{pageonsite}");
            obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else if (obj.results_count != 0)
            {
                foreach (var result in obj.results)
                {
                    var resultItem = ((IEnumerable<dynamic>)result).First();
                    Console.WriteLine(resultItem);
                }
            }
            else
                Console.WriteLine("no results");
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

client = RestClient("login", "password")
response = client.get("/v2/op_tasks_htags_on_page/123456789/'/relative/page/on/site.html'")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1295 sec.",
    "results_count": 4,
    "results": [
        {
            "post_id": "9999555",
            "post_site": "alpinen-gold.com",
            "task_id": 136371534,
            "string_search_containment": null,
            "crawl_max_pages": 4,
            "crawl_start": "2017-10-12 11:14:23.624803+03",
            "crawl_end": "2017-10-12 11:15:08.908063+03",
            "status": "crawled",
            "htags_on_page": [
                {
                    "h1": [
                        "Letter D"
                    ],
                    "h2": [
                        "ALPINEN GOLD"
                    ],
                    "h3": [
                        "Календарь",
                        "Категории"
                    ]
                }
            ]
        }
    ]
}

Using this function, you can get a list of H1 tags on a page.

$page - is a relative page address on a site. The page value must be enclosed in single quotes, like this
https://api.dataforseo.com/v2/op_tasks_htags_on_page/12345/'/page/on/site.html'

You will receive array from the API server in the results field where you will find results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information in the error array
error array informational array of error
only if status=“error”
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the results array
results array results array
      post_id string index in the array received in a POST array
      post_site string site received in a POST array
      task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time
      string_search_containment string string_search_containment received in a POST request
default value: ‘null’.
      crawl_max_pages integer maximum number of test pages
      crawl_start string date and time of the start of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-14 11:50:01 +02:00’
      crawl_end string date and time of the end of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-13 15:30:34 +02:00’
      status string current status of the task
possible values: “in_queue”, “crawling”, “crawled”, “crawl_paused”
      htags_on_page array array of H tags
            h1 array array of H1 tags
            h2 array array of H2 tags
            h3 array array of H3 tags

Get Images On Page

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

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

try {
    $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";
}

try {

    // GET /api/v2/op_tasks_images_on_page/$task_id/$page
    $task_get_result = $client->get("v2/op_tasks_images_on_page/123456789/'/relative/page/on/site.html'");
    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;
?>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task rnk_tasks_get()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),
                DefaultRequestHeaders = {Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password")))}
            };

            var taskid = 123456789;
            var pageonsite = "'/relative/page/on/site.html'";
            response = await httpClient.GetAsync($"v2/op_tasks_images_on_page/{taskid}/{pageonsite}");
            obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else if (obj.results_count != 0)
            {
                foreach (var result in obj.results)
                {
                    var resultItem = ((IEnumerable<dynamic>)result).First();
                    Console.WriteLine(resultItem);
                }
            }
            else
                Console.WriteLine("no results");
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

client = RestClient("login", "password")
response = client.get("/v2/op_tasks_images_on_page/123456789/'/relative/page/on/site.html'")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.1068 sec.",
    "results_count": 12,
    "results": [
        {
            "post_id": "9#999#555",
            "post_site": "ranksonic.com",
            "task_id": 151668277,
            "string_search_containment": null,
            "crawl_max_pages": 12,
            "crawl_start": "2017-10-12 11:14:23.624803+03",
            "crawl_end": "2017-10-12 11:15:08.908063+03",
            "status": "crawled",
            "images_on_page": [
                {
                    "alt": "RankS",
                    "src": "\/assets\/images\/logo_ranks.png",
                    "title": ""
                },
                {
                    "alt": "O",
                    "src": "\/assets\/images\/logo_o.png",
                    "title": ""
                },
                {
                    "alt": "nic",
                    "src": "\/assets\/images\/logo_nic.png",
                    "title": ""
                },
                {
                    "alt": "menu",
                    "src": "\/assets\/images\/icon-menu.png",
                    "title": ""
                },
                {
                    "alt": "Generate keywords",
                    "src": "\/assets\/images\/gk-img.png",
                    "title": ""
                },
                {
                    "alt": "700 keywords",
                    "src": "\/assets\/images\/gk-find.png",
                    "title": ""
                },
                {
                    "alt": "According to the region",
                    "src": "\/assets\/images\/gk-location.png",
                    "title": ""
                },
                {
                    "alt": "Export results",
                    "src": "\/assets\/images\/gk-export.png",
                    "title": ""
                },
                {
                    "alt": "menu",
                    "src": "\/assets\/images\/close-icon.png",
                    "title": ""
                },
                {
                    "alt": "close",
                    "src": "\/themes\/default\/images\/icons\/close-ticket.png",
                    "title": ""
                },
                {
                    "alt": "close",
                    "src": "\/themes\/default\/images\/icons\/close-ticket.png",
                    "title": ""
                },
                {
                    "alt": "close",
                    "src": "\/themes\/default\/images\/icons\/close-ticket.png",
                    "title": ""
                }
            ]
        }
    ]
}

Using this function, you can get a list of images on a page.

$page - is a relative page address on a site. The page value must be enclosed in single quotes, like this
https://api.dataforseo.com/v2/op_tasks_images_on_page/12345/'/page/on/site.html'

You will receive array from the API server in the results field where you will find results.

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information in the error array
error array informational array of error
only if status=“error”
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of elements in the results array
results array results array
      post_id string index in the array received in a POST array
      post_site string site received in a POST array
      task_id integer unique task identifier in our system
in the future you will be able to use it within 30 days to request results of this task any time
      string_search_containment string string_search_containment received in a POST request
default value: ‘null’.
      crawl_max_pages integer maximum number of test pages
      crawl_start string date and time of the start of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-14 11:50:01 +02:00’
      crawl_end string date and time of the end of crawling
in the format year-month-day:GMT_hours:GMT_minutes:time_zone
for example: ‘2017-12-13 15:30:34 +02:00’
      status string current status of the task
possible values: “in_queue”, “crawling”, “crawled”, “crawl_paused”
      images_on_page array array of images
            alt string alt attribute
            src string src attribute
            title string title attribute

Common API

In this section we’ve collected the features that will be useful for using different API.

List of Search Engines

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

<?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/login
    $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;
?>
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task cmn_se()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var response = await httpClient.GetAsync("v2/cmn_se");
            var obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
            {
                foreach (var result in obj.results)
                    Console.WriteLine(result);
            }
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/php/_php_RestClient.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")
response = client.get("/v2/cmn_se")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

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"
        }
    ]
}

You will receive the list of available search engines that you are able to use at Rank Tracker API and SERP API.

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

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you will be able to see more detailed information about array error error
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 an error
results_time string execution time, seconds
results_count string number of elements in the array of results results
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 search engine interface)

List of Locations

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

<?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/login
    $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;
?>
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task cmn_locations()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var response = await httpClient.GetAsync("v2/cmn_locations");
            var obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
            {
                foreach (var result in obj.results)
                    Console.WriteLine(result);
            }
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")
response = client.get("/v2/cmn_locations")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"])

The above command returns JSON structured like this:

{
    "status": "ok",
    "results_time": "0.0392 sec.",
    "results_count": 36938,
    "results": [
        {
            "loc_id": 2004,
            "loc_id_parent": null,
            "loc_name": "Afghanistan",
            "loc_name_canonical": "Afghanistan",
            "loc_type": "Country",
            "loc_country_iso_code": "AF"
        },

        {
            "loc_id": 9067849,
            "loc_id_parent": 21199,
            "loc_name": "La Trinidad",
            "loc_name_canonical": "La Trinidad,Miranda,Venezuela",
            "loc_type": "City",
            "loc_country_iso_code": "VE"
        },
        {
            "loc_id": 9067850,
            "loc_id_parent": 2850,
            "loc_name": "Christiansted",
            "loc_name_canonical": "Christiansted,U.S. Virgin Islands",
            "loc_type": "City",
            "loc_country_iso_code": "VI"
        }
    ]
}

You will receive the list of available search engines that you are able to use at Rank Tracker API and SERP API.

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 ‘Country’, ‘State’, ‘Region’, ‘Municipality’, ‘City’.

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

Name of a field Type Des
status string general result
“ok” - successful
“error” - error
if status=“error”, then you will be able to see more detailed information about array error error
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 an error
results_time string execution time, seconds
results_count string number of elements in the array of results results
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 a location
            loc_type string location type
            loc_country_iso_code string ISO country code of location

Get Keyword ID

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

<?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/login
    $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;
?>
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task cmn_key_id()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var keyword = "online rank checker";
            var response = await httpClient.GetAsync("v2/cmn_key_id/" + keyword);
            var obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
                Console.WriteLine(obj.results[0].key_id);
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")
keyword = "online rank checker"
response = client.get("/v2/cmn_key_id/%s" % keyword)
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"][0]["key_id"])

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 key_id from our database (if there is no such keyword, it will be added and key_id created and returned), which you are able to use in Rank Tracker API and SERP API. Keyword key_id is unique and can’t be changed.

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

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you will be able to see more detailed information about array error error
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of the elements in the array of results results
results array
            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/login
    $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 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;
?>
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task cmn_user()
        {
            var httpClient = new HttpClient {
                BaseAddress = new Uri("https://api.dataforseo.com/"),

                //Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var response = await httpClient.GetAsync("v2/cmn_user");
            var obj = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
            if (obj.status == "error")
                Console.WriteLine($"error. Code: {obj.error.code} Message: {obj.error.message}");
            else
                Console.WriteLine(obj.results[0]);
        }
    }
}
from client import RestClient
#You can download this file from here https://api.dataforseo.com/_examples/python/_python_Client.zip

#Instead of 'login' and 'password' use your credentials from https://my.dataforseo.com/login
client = RestClient("login", "password")
response = client.get("/v2/cmn_user")
if response["status"] == "error":
    print("error. Code: %d Message: %s" % (response["error"]["code"], response["error"]["message"]))
else:
    print(response["results"][0])

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,
            "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
                        }
                    }
                }
            }
        }
    ]
}

Information about current user

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

Name of a field Type Description
status string general result
“ok” - successful
“error” - error
if status=“error”, then you can see more detailed information about array error error
error array informational array of error
only if status=“error”
the list of possible errors can be found below.
      code integer error code
      message string text description of an error
results_time string execution time, seconds
results_count string number of the elements in the array of results results
results array
      login string your login
      timezone string your time zone
can be set at the settings of your profile
      rate_limit_per_minute integer limit of any requests per a minute
this limit is used for load balancing on our servers
      rate integer current number of requests per a minute
      credit integer total amount of credits passed to your account
      balance integer current balance of your account
credit-count_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 values:
per_result - charge for every row in result array
per_request - charge for GET or POST request
                  price string the cost in credits