Reference example

# Fixed reference example. Playground inputs do not update this sample.
curl --request POST \
  --url https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "target": "dataforseo.com",
    "language_name": "English",
    "location_name": "United States",
    "load_rank_absolute": true,
    "limit": 3
  }
]'

curl --request POST \
  --url https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "language_name": "English",
    "limit": 3,
    "load_rank_absolute": true,
    "location_name": "United States",
    "target": "dataforseo.com"
  }
]
'

import requests

url = "https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live"

payload = [
    {
        "language_name": "English",
        "limit": 3,
        "load_rank_absolute": True,
        "location_name": "United States",
        "target": "dataforseo.com"
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      language_name: 'English',
      limit: 3,
      load_rank_absolute: true,
      location_name: 'United States',
      target: 'dataforseo.com'
    }
  ])
};

fetch('https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'language_name' => 'English',
        'limit' => 3,
        'load_rank_absolute' => true,
        'location_name' => 'United States',
        'target' => 'dataforseo.com'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live"

	payload := strings.NewReader("[\n  {\n    \"language_name\": \"English\",\n    \"limit\": 3,\n    \"load_rank_absolute\": true,\n    \"location_name\": \"United States\",\n    \"target\": \"dataforseo.com\"\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"language_name\": \"English\",\n    \"limit\": 3,\n    \"load_rank_absolute\": true,\n    \"location_name\": \"United States\",\n    \"target\": \"dataforseo.com\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"language_name\": \"English\",\n    \"limit\": 3,\n    \"load_rank_absolute\": true,\n    \"location_name\": \"United States\",\n    \"target\": \"dataforseo.com\"\n  }\n]"

response = http.request(request)
puts response.read_body

{
  "cost": 123,
  "status_code": 123,
  "status_message": "<string>",
  "tasks_count": 123,
  "tasks_error": 123,
  "time": "<string>",
  "version": "<string>",
  "tasks": [
    {
      "cost": 123,
      "data": {},
      "id": "<string>",
      "path": [
        "<string>"
      ],
      "result_count": 123,
      "status_code": 123,
      "status_message": "<string>",
      "time": "<string>",
      "result": [
        {
          "items": [
            {
              "keyword_data": {
                "avg_backlinks_info": {
                  "backlinks": 123,
                  "dofollow": 123,
                  "last_updated_time": "<string>",
                  "main_domain_rank": 123,
                  "rank": 123,
                  "referring_domains": 123,
                  "referring_main_domains": 123,
                  "referring_pages": 123,
                  "se_type": "<string>"
                },
                "clickstream_keyword_info": {
                  "age_distribution": {},
                  "gender_distribution": {},
                  "last_updated_time": "<string>",
                  "monthly_searches": [
                    {
                      "month": 123,
                      "search_volume": 123,
                      "year": 123
                    }
                  ],
                  "search_volume": 123
                },
                "keyword": "<string>",
                "keyword_info": {
                  "categories": [
                    123
                  ],
                  "competition": 123,
                  "competition_level": "<string>",
                  "cpc": 123,
                  "high_top_of_page_bid": 123,
                  "last_updated_time": "<string>",
                  "low_top_of_page_bid": 123,
                  "monthly_searches": [
                    {
                      "month": 123,
                      "search_volume": 123,
                      "year": 123
                    }
                  ],
                  "se_type": "<string>",
                  "search_volume": 123,
                  "search_volume_trend": {
                    "monthly": 123,
                    "quarterly": 123,
                    "yearly": 123
                  }
                },
                "keyword_info_normalized_with_bing": {
                  "is_normalized": true,
                  "last_updated_time": "<string>",
                  "monthly_searches": [
                    {
                      "month": 123,
                      "search_volume": 123,
                      "year": 123
                    }
                  ],
                  "search_volume": 123
                },
                "keyword_info_normalized_with_clickstream": {
                  "is_normalized": true,
                  "last_updated_time": "<string>",
                  "monthly_searches": [
                    {
                      "month": 123,
                      "search_volume": 123,
                      "year": 123
                    }
                  ],
                  "search_volume": 123
                },
                "keyword_properties": {
                  "core_keyword": "<string>",
                  "detected_language": "<string>",
                  "is_another_language": true,
                  "keyword_difficulty": 123,
                  "se_type": "<string>",
                  "synonym_clustering_algorithm": "<string>",
                  "words_count": 123
                },
                "language_code": "<string>",
                "location_code": 123,
                "se_type": "<string>",
                "search_intent_info": {
                  "foreign_intent": [
                    "<string>"
                  ],
                  "last_updated_time": "<string>",
                  "main_intent": "<string>",
                  "se_type": "<string>"
                },
                "serp_info": {
                  "check_url": "<string>",
                  "last_updated_time": "<string>",
                  "previous_updated_time": "<string>",
                  "se_results_count": 123,
                  "se_type": "<string>",
                  "serp_item_types": [
                    "<string>"
                  ]
                }
              },
              "ranked_serp_element": {
                "check_url": "<string>",
                "is_lost": true,
                "keyword_difficulty": 123,
                "last_updated_time": "<string>",
                "previous_updated_time": "<string>",
                "se_results_count": 123,
                "se_type": "<string>",
                "serp_item": {
                  "links": [
                    {
                      "description": "<string>",
                      "domain": "<string>",
                      "snippet": "<string>",
                      "title": "<string>",
                      "type": "<string>",
                      "url": "<string>",
                      "xpath": "<string>"
                    }
                  ],
                  "text": [
                    "<string>"
                  ],
                  "position": "<string>",
                  "rank_absolute": 123,
                  "rank_group": 123,
                  "se_type": "<string>",
                  "type": "<string>",
                  "xpath": "<string>"
                },
                "serp_item_types": [
                  "<string>"
                ]
              },
              "se_type": "<string>"
            }
          ],
          "items_count": 123,
          "language_code": "<string>",
          "location_code": 123,
          "metrics": {},
          "metrics_absolute": {},
          "se_type": "<string>",
          "target": "<string>",
          "total_count": 123
        }
      ]
    }
  ]
}

DataForSEO

Ranked Keywords

‌ This endpoint will provide you with the list of keywords that any domain, subdomain, or webpage is ranking for. You will also get SERP elements related to the keyword position, as well as monthly searches and other data relevant to the returned keywords.  Usage-based billing; Default request estimate: $0.132 USD (not a fixed price). Account-specific pricing and final settlement may differ.

POST

https://api.aisa.one

apis

dataforseo

dataforseo_labs

google

ranked_keywords

live

Reference example

# Fixed reference example. Playground inputs do not update this sample.
curl --request POST \
  --url https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "target": "dataforseo.com",
    "language_name": "English",
    "location_name": "United States",
    "load_rank_absolute": true,
    "limit": 3
  }
]'

curl --request POST \
  --url https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "language_name": "English",
    "limit": 3,
    "load_rank_absolute": true,
    "location_name": "United States",
    "target": "dataforseo.com"
  }
]
'

import requests

url = "https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live"

payload = [
    {
        "language_name": "English",
        "limit": 3,
        "load_rank_absolute": True,
        "location_name": "United States",
        "target": "dataforseo.com"
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      language_name: 'English',
      limit: 3,
      load_rank_absolute: true,
      location_name: 'United States',
      target: 'dataforseo.com'
    }
  ])
};

fetch('https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'language_name' => 'English',
        'limit' => 3,
        'load_rank_absolute' => true,
        'location_name' => 'United States',
        'target' => 'dataforseo.com'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live"

	payload := strings.NewReader("[\n  {\n    \"language_name\": \"English\",\n    \"limit\": 3,\n    \"load_rank_absolute\": true,\n    \"location_name\": \"United States\",\n    \"target\": \"dataforseo.com\"\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"language_name\": \"English\",\n    \"limit\": 3,\n    \"load_rank_absolute\": true,\n    \"location_name\": \"United States\",\n    \"target\": \"dataforseo.com\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"language_name\": \"English\",\n    \"limit\": 3,\n    \"load_rank_absolute\": true,\n    \"location_name\": \"United States\",\n    \"target\": \"dataforseo.com\"\n  }\n]"

response = http.request(request)
puts response.read_body

{
  "cost": 123,
  "status_code": 123,
  "status_message": "<string>",
  "tasks_count": 123,
  "tasks_error": 123,
  "time": "<string>",
  "version": "<string>",
  "tasks": [
    {
      "cost": 123,
      "data": {},
      "id": "<string>",
      "path": [
        "<string>"
      ],
      "result_count": 123,
      "status_code": 123,
      "status_message": "<string>",
      "time": "<string>",
      "result": [
        {
          "items": [
            {
              "keyword_data": {
                "avg_backlinks_info": {
                  "backlinks": 123,
                  "dofollow": 123,
                  "last_updated_time": "<string>",
                  "main_domain_rank": 123,
                  "rank": 123,
                  "referring_domains": 123,
                  "referring_main_domains": 123,
                  "referring_pages": 123,
                  "se_type": "<string>"
                },
                "clickstream_keyword_info": {
                  "age_distribution": {},
                  "gender_distribution": {},
                  "last_updated_time": "<string>",
                  "monthly_searches": [
                    {
                      "month": 123,
                      "search_volume": 123,
                      "year": 123
                    }
                  ],
                  "search_volume": 123
                },
                "keyword": "<string>",
                "keyword_info": {
                  "categories": [
                    123
                  ],
                  "competition": 123,
                  "competition_level": "<string>",
                  "cpc": 123,
                  "high_top_of_page_bid": 123,
                  "last_updated_time": "<string>",
                  "low_top_of_page_bid": 123,
                  "monthly_searches": [
                    {
                      "month": 123,
                      "search_volume": 123,
                      "year": 123
                    }
                  ],
                  "se_type": "<string>",
                  "search_volume": 123,
                  "search_volume_trend": {
                    "monthly": 123,
                    "quarterly": 123,
                    "yearly": 123
                  }
                },
                "keyword_info_normalized_with_bing": {
                  "is_normalized": true,
                  "last_updated_time": "<string>",
                  "monthly_searches": [
                    {
                      "month": 123,
                      "search_volume": 123,
                      "year": 123
                    }
                  ],
                  "search_volume": 123
                },
                "keyword_info_normalized_with_clickstream": {
                  "is_normalized": true,
                  "last_updated_time": "<string>",
                  "monthly_searches": [
                    {
                      "month": 123,
                      "search_volume": 123,
                      "year": 123
                    }
                  ],
                  "search_volume": 123
                },
                "keyword_properties": {
                  "core_keyword": "<string>",
                  "detected_language": "<string>",
                  "is_another_language": true,
                  "keyword_difficulty": 123,
                  "se_type": "<string>",
                  "synonym_clustering_algorithm": "<string>",
                  "words_count": 123
                },
                "language_code": "<string>",
                "location_code": 123,
                "se_type": "<string>",
                "search_intent_info": {
                  "foreign_intent": [
                    "<string>"
                  ],
                  "last_updated_time": "<string>",
                  "main_intent": "<string>",
                  "se_type": "<string>"
                },
                "serp_info": {
                  "check_url": "<string>",
                  "last_updated_time": "<string>",
                  "previous_updated_time": "<string>",
                  "se_results_count": 123,
                  "se_type": "<string>",
                  "serp_item_types": [
                    "<string>"
                  ]
                }
              },
              "ranked_serp_element": {
                "check_url": "<string>",
                "is_lost": true,
                "keyword_difficulty": 123,
                "last_updated_time": "<string>",
                "previous_updated_time": "<string>",
                "se_results_count": 123,
                "se_type": "<string>",
                "serp_item": {
                  "links": [
                    {
                      "description": "<string>",
                      "domain": "<string>",
                      "snippet": "<string>",
                      "title": "<string>",
                      "type": "<string>",
                      "url": "<string>",
                      "xpath": "<string>"
                    }
                  ],
                  "text": [
                    "<string>"
                  ],
                  "position": "<string>",
                  "rank_absolute": 123,
                  "rank_group": 123,
                  "se_type": "<string>",
                  "type": "<string>",
                  "xpath": "<string>"
                },
                "serp_item_types": [
                  "<string>"
                ]
              },
              "se_type": "<string>"
            }
          ],
          "items_count": 123,
          "language_code": "<string>",
          "location_code": 123,
          "metrics": {},
          "metrics_absolute": {},
          "se_type": "<string>",
          "target": "<string>",
          "total_count": 123
        }
      ]
    }
  ]
}

Request contract

Method and path: POST /apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live
Availability: enabled
Request URL template: https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live
Runtime facts: 6ab8fec17df1d5dcdff2e036dd1eb40587752b774ec040ab4eb0cc6946c3dd3c

Complete OpenAPI definition Effective request and pricing declaration (including authentication and referenced schemas):

{
  "operationId": "any_dataforseo_apis_v1_dataforseo_dataforseo_labs_23787a",
  "method": "POST",
  "path": "/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live",
  "servers": [
    {
      "url": "https://api.aisa.one"
    }
  ],
  "parameters": [],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "example": [
            {
              "language_name": "English",
              "limit": 3,
              "load_rank_absolute": true,
              "location_name": "United States",
              "target": "dataforseo.com"
            }
          ],
          "items": {
            "oneOf": [
              {
                "example": [
                  {
                    "language_name": "English",
                    "limit": 3,
                    "load_rank_absolute": true,
                    "location_name": "United States",
                    "target": "dataforseo.com"
                  }
                ],
                "properties": {
                  "filters": {
                    "description": "<em>array of results filtering parameters</em><br>optional field<br><strong>you can add several filters at once (8 filters maximum)</strong><br>you should set a logical operator <code>and</code>, <code>or</code> between the conditions<br>the following operators are supported:<br><code>regex</code>, <code>not_regex</code>, <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, <code>&gt;=</code>, <code>=</code>, <code>&lt;&gt;</code>, <code>in</code>, <code>not_in</code>, <code>match</code>, <code>not_match</code>, <code>ilike</code>, <code>not_ilike</code>, <code>like</code>, <code>not_like</code><br>you can use the <code>%</code> operator with <code>like</code> and <code>not_like</code>, as well as <code>ilike</code> and <code>not_ilike</code> to match any string of zero or more characters<br>example:<br><code>[\"ranked_serp_element.serp_item.rank_group\",\"&lt;=\",10]</code><p><code>[[\"ranked_serp_element.serp_item.rank_group\",\"&lt;=\",10],<br>\"and\",<br>[\"ranked_serp_element.serp_item.type\",\"&lt;&gt;\",\"paid\"]]</code><p><code>[[\"keyword_data.keyword_info.search_volume\",\"&lt;&gt;\",0],<br>\"and\",<br>[[\"ranked_serp_element.serp_item.type\",\"&lt;&gt;\",\"paid\"],\"or\",[\"ranked_serp_element.serp_item.is_malicious\",\"=\",false]]]</code><p>if you want to get the keywords a particular webpage ranks for, you can use a <code><a href=\"/v3/dataforseo_labs/google/ranked_keywords/live/#target\">target</a></code> field or filter by the <code>ranked_serp_element.serp_item.relative_url</code> parameter<br>example:<br><code>[\"ranked_serp_element.serp_item.relative_url\", \"=\", \"/apis/rank-tracker-api\"]</code><br>for more information about filters, please refer to <a href=\"/v3/dataforseo_labs/filters\" target=\"_blank\" rel=\"noopener noreferrer\">Dataforseo Labs - Filters</a> or this <a href=\"https://dataforseo.com/help-center/how-to-use-filters-in-dataforseo-labs-api\" rel=\"noopener noreferrer\" target=\"_blank\">help center guide</a>",
                    "items": {
                      "type": [
                        "object",
                        "null"
                      ]
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  },
                  "historical_serp_mode": {
                    "description": "<em>data collection mode</em><br>optional field<br>you can use this field to filter the results;<br>possible types of filtering:<br><code>live</code> — return keywords for which the specified <code>target</code> currently has ranking results in SERP;<br><code>lost</code> — return keywords for which the specified <code>target</code> had previously had ranking results in SERP, but didn't have them during the last check;<br><code>all</code> — return both types of keywords.<br>default value: <code>live</code>",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "ignore_synonyms": {
                    "description": "<em>ignore highly similar keywords</em><br>optional field<br>if set to <code class=\"prettyprint\">true</code> only core keywords will be returned, all highly similar keywords will be excluded;  <br>default value: <code>false</code>",
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "include_clickstream_data": {
                    "description": "<em>include or exclude data from clickstream-based metrics in the result</em><br>optional field<br>if the parameter is set to <code>true</code>, you will receive <code>clickstream_keyword_info</code>, <code>clickstream_etv</code>, <code>clickstream_gender_distribution</code>, <code>clickstream_age_distribution</code>, <code>keyword_info_normalized_with_clickstream</code>, and <code>keyword_info_normalized_with_bing</code> fields in the response<br>default value: <code>false</code><br>with this parameter enabled, you will be charged double the price for the request<p>learn more about how clickstream-based metrics are calculated in this <a href=\"https://dataforseo.com/help-center/what-are-clickstream-based-metrics-and-how-do-we-calculate-them\" rel=\"noopener noreferrer\" target=\"_blank\">help center article</a>",
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "item_types": {
                    "description": "<em>display results by item type</em><br>optional field<br>indicates the type of search results included in the response<p><strong>Note:</strong> if the <code>item_types</code> array contains item types that are different from <code>organic</code>, the results will be ordered by the first item type in the array; you will not be able to sort and filter results by the types of search results not included in the response;<p>possible values: <br><code>[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\", \"ai_overview_reference\"]</code><br>default value: <br><code>[\"organic\", \"paid\"]</code>",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  },
                  "language_code": {
                    "description": "<em>language code</em><br>optional field<br>if you use this field, you don't need to specify <code>language_name</code><br>you can receive the list of available languages with their <code>language_code</code> by making a separate request to the <br><code>https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages</code><br>ignore this field to get the results for all available languages<br>example:<br><code class=\"long-string\">en</code>",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "language_name": {
                    "description": "<em>full name of the language</em><br>optional field<br>if you use this field, you don't need to specify <code>language_code</code><br>you can receive the list of available languages with their <code>language_name</code> by making a separate request to the <br><code>https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages</code><br>ignore this field to get the results for all available languages<br>example:<br><code class=\"long-string\">English</code>",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "description": "<em>the maximum number of returned keywords</em><br>optional field<br>default value: <code>100</code><br>maximum value: <code>1000</code>",
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "load_rank_absolute": {
                    "description": "<em>return rankings distribution by <code>rank_absolute</code></code></em><br>optional field<br>default value: <code>false</code><br>if set to <code>true</code>, we will return the field <code>metrics_absolute</code> containing rankings distribution by the <code>rank_absolute</code> parameter that indicates the result’s position among all SERP elements",
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "location_code": {
                    "description": "<em>location code</em><br>optional field<br>if you use this field, you don't need to specify <code>location_name</code><br>you can receive the list of available locations with their <code>location_code</code> by making a separate request to the <br><code>https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages</code><br>ignore this field to get the results for all available locations<br>example:<br><code class=\"long-string\">2840</code>",
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "location_name": {
                    "description": "<em>full name of the location</em><br>optional field<br>if you use this field, you don't need to specify <code>location_code</code><br>you can receive the list of available locations with their <code>location_name</code> by making a separate request to the <br><code>https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages</code><br>ignore this field to get the results for all available locations<br>example:<br><code class=\"long-string\">United Kingdom</code>",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "offset": {
                    "description": "<em>offset in the results array of returned keywords</em><br>optional field<br>default value: <code>0</code><br>if you specify the <code>10</code> value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords",
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "order_by": {
                    "description": "<em>results sorting rules</em><br>optional field<br>you can use the same values as in the <code>filters</code> array to sort the results<br>possible sorting types:<br><code>asc</code> - results will be sorted in the ascending order<br><code>desc</code> - results will be sorted in the descending order<br>you should use a comma to set up a sorting type<br>example:<br><code>[\"keyword_data.keyword_info.competition,desc\"]</code><br>default rule:<br><code>[\"ranked_serp_element.serp_item.rank_group,asc\"]</code><br><strong>note that you can set no more than three sorting rules in a single request</strong><br>you should use a comma to separate several sorting rules<br>example:<br><code>[\"keyword_data.keyword_info.search_volume,desc\",\"keyword_data.keyword_info.cpc,desc\"]</code>",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  },
                  "tag": {
                    "description": "<em>user-defined task identifier</em><br>optional field<br><em>the character limit is 255</em><br>you can use this parameter to identify the task and match it with the result<br>you will find the specified <code>tag</code> value in the <code>data</code> object of the response",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "target": {
                    "description": "<em>domain name or page url</em><br><strong>required field</strong><br>the domain name of the target website, subdomain or URL of the target webpage;<br>the <strong>domain name</strong> must be specified <strong>without</strong> <code>https://</code> or <code>www.</code>;<br>the <strong>subdomain</strong> must be specified <strong>without</strong> <code>https://</code>;<br>the <strong>webpage URL</strong> must be specified <strong>with</strong> <code>https://</code> or <code>www.</code><br><strong>Note:</strong> if you specify the <strong>webpage URL</strong> without <code>https://</code> or <code>www.</code>, the result will be returned for the <strong>entire domain</strong> rather than the specific page",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            ],
            "type": [
              "object",
              "null"
            ]
          },
          "type": "array"
        }
      }
    }
  },
  "x-aisa-status": "enabled",
  "x-aisa-pricing": {
    "cost_contract": "response_usd",
    "customer_multiplier": 1.0,
    "customer_pricing": "provider_cost_multiplier",
    "default_request_estimate_usd": 0.132,
    "estimate_source": "profile_seed",
    "evidence_source": "response_body"
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  }
}

Cost and request rules

Usage-based billing; Default request estimate: $0.132 USD (not a fixed price). Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.

Default request reference estimate (USD): 0.132
Cost contract: response_usd
Published reference multiplier: 1.0
Settlement evidence source: response_body

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

filters

(object | null)[] | null

array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:
regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like
you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters
example:
["ranked_serp_element.serp_item.rank_group","<=",10]

[["ranked_serp_element.serp_item.rank_group","<=",10],"and",["ranked_serp_element.serp_item.type","<>","paid"]]

[["keyword_data.keyword_info.search_volume","<>",0],"and",[["ranked_serp_element.serp_item.type","<>","paid"],"or",["ranked_serp_element.serp_item.is_malicious","=",false]]]

if you want to get the keywords a particular webpage ranks for, you can use a target field or filter by the ranked_serp_element.serp_item.relative_url parameter
example:
["ranked_serp_element.serp_item.relative_url", "=", "/apis/rank-tracker-api"]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide

historical_serp_mode

string | null

data collection mode
optional field
you can use this field to filter the results;
possible types of filtering:
live — return keywords for which the specified target currently has ranking results in SERP;
lost — return keywords for which the specified target had previously had ranking results in SERP, but didn't have them during the last check;
all — return both types of keywords.
default value: live

ignore_synonyms

boolean | null

ignore highly similar keywords
optional field
if set to true only core keywords will be returned, all highly similar keywords will be excluded;
default value: false

include_clickstream_data

boolean | null

include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_keyword_info, clickstream_etv, clickstream_gender_distribution, clickstream_age_distribution, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response
default value: false
with this parameter enabled, you will be charged double the price for the request

learn more about how clickstream-based metrics are calculated in this help center article

item_types

string[] | null

display results by item type
optional field
indicates the type of search results included in the response

Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array; you will not be able to sort and filter results by the types of search results not included in the response;

possible values:
["organic", "paid", "featured_snippet", "local_pack", "ai_overview_reference"]
default value:
["organic", "paid"]

language_code

string | null

language code
optional field
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:
en

language_name

string | null

full name of the language
optional field
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:
English

limit

integer | null

the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000

load_rank_absolute

boolean | null

return rankings distribution by rank_absolute
optional field
default value: false
if set to true, we will return the field metrics_absolute containing rankings distribution by the rank_absolute parameter that indicates the result’s position among all SERP elements

location_code

integer | null

location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations with their location_code by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:
2840

location_name

string | null

full name of the location
optional field
if you use this field, you don't need to specify location_code
you can receive the list of available locations with their location_name by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:
United Kingdom

offset

integer | null

offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords

order_by

string[] | null

results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:
asc - results will be sorted in the ascending order
desc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:
["keyword_data.keyword_info.competition,desc"]
default rule:
["ranked_serp_element.serp_item.rank_group,asc"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:
["keyword_data.keyword_info.search_volume,desc","keyword_data.keyword_info.cpc,desc"]

tag

string | null

user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response

target

string

domain name or page url
required field
the domain name of the target website, subdomain or URL of the target webpage;
the domain name must be specified without https:// or www.;
the subdomain must be specified without https://;
the webpage URL must be specified with https:// or www.
Note: if you specify the webpage URL without https:// or www., the result will be returned for the entire domain rather than the specific page

Example:

[
  {
    "language_name": "English",
    "limit": 3,
    "load_rank_absolute": true,
    "location_name": "United States",
    "target": "dataforseo.com"
  }
]

Response

object | null

Successful operation

cost

number<double> | null

total tasks cost, USD

status_code

integer | null

general status code you can find the full list of the response codes here

status_message

string | null

general informational message you can find the full list of general informational messages here

tasks_count

integer<int64> | null

the number of tasks in the tasks array

tasks_error

integer<int64> | null

the number of tasks in the tasks array returned with an error

time

string | null

total execution time, seconds

version

string | null

the current version of the API

tasks

(object | null)[] | null

array of tasks

Show child attributes

Overview

Models

Search & Research

Finance & Crypto

Social & Media

SEO & Web Intel

Sales & Email

Travel & Other

Ranked Keywords

Request contract

Cost and request rules

Authorizations

Body

Response

​Request contract

​Cost and request rules

Authorizations

Body

Response

Request contract

Cost and request rules