{"listing":null,"template":{"owner":"0b653b0ed0235b537c0c8c2e114261ad","name":"dataforseo","digest":"sha256:da9aa932341d4624d1d1619be06eb86b97fa4d68712b8503b13462f679071dd8","manifest":{"abi_version":7,"name":"crab-dataforseo","version":"0.1.2","lang":"0.1.2","imports":["berm.args.len","berm.args.read","berm.done","berm.fail","berm.http.fetch","berm.result.read","berm.trace"],"description":"DataForSEO keyword metrics, backlinks, rankings and web data tools","homepage":"","repository":"https://github.com/crabtalk/crab","readme":"# DataForSEO\n\nGet keyword metrics, backlinks, rankings and search results, inspect sites and business data, or submit and retrieve supported DataForSEO tasks.\n\n## Call\n\nWith Crab signed in to Cloud, replace `owner/dataforseo` with the address of a running deployment you can access. If this page only offers a template, deploy a copy first.\n\n```sh\ncrab call owner/dataforseo keyword_volume '{\"input\":{\"body\":[{\"keywords\":[\"rust hosting\",\"wasm hosting\"],\"location_code\":2840,\"language_code\":\"en\"}]}}'\n```\n\nReturns the upstream task envelope, including results, task IDs and costs. Live tools return their immediate results; task-submission tools return IDs for explicit retrieval.\n\nOn a callable deployment, you can also open a tool on this page to call it, or connect your agent through [CrabTalk MCP](https://crab.talk/docs/guides/mcp). Calls use this deployment’s provider credentials.\n\n## Deploy your own\n\nIf this page offers **Deploy your own**, use it to create a private copy with your own credentials and state. The CLI equivalent is:\n\n```sh\ncrab deploy --from owner/dataforseo\n```\n\nSet `DATAFORSEO_AUTH_TOKEN` through credential setup to the Base64 encoding of `API_LOGIN:API_PASSWORD`, without the `Basic ` prefix. Use the API credentials from your DataForSEO account, not the account password. Requests spend the connected DataForSEO balance.\n\nTemplate deployment needs a published image. To build a modified version or deploy when no template is published, use the [source instructions](https://github.com/crabtalk/crab/blob/dev/services/README.md#building-from-source).\n\n## Usage notes\n\nPOST tools take an array of task objects under `input.body`; GET path parameters go under `input.path`. Live endpoints accept one task per call; Standard task submission limits depend on the tool.\n\nEnvelope and task failures return errors containing the original response, including successful tasks in a mixed result. Created tasks and explicitly partial results remain responses.\n\nCalls do not poll, paginate or retry automatically. Google Events Live Advanced and Pinterest Live are not included.\n\n[Source and Rust API](https://github.com/crabtalk/crab/tree/dev/services/dataforseo) · [Provider documentation](https://docs.dataforseo.com/v3/)\n","logo":"https://crab.talk/logos/templates/dataforseo-v1.png","tools":[{"name":"account_usage","description":"You will receive detailed information about your API usage, prices, spending and other account details by calling this API.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Account usage"},{"name":"ai_ai_keyword_data_keywords_search_volume_live","description":"‌\nThis endpoint provides search volume data for your target keywords, reflecting their estimated usage in AI tools.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["iphone","seo"],"language_name":"English","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keywords":["iphone","seo"],"language_name":"English","location_code":2840}]],"properties":{"keywords":{"description":"keywords
required field
UTF-8 encoding
The maximum number of keywords you can specify: 1000;
The maximum number of characters in a single keyword: 250;
The keywords will be converted to lowercase format;

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"language code
required field if you don't specify language_name
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/ai_optimization/ai_keyword_data/locations_and_languages
example:
en","type":"string"},"language_name":{"description":"full name of the language
required field if you don't specify language_code
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/ai_optimization/ai_keyword_data/locations_and_languages
example:
English","type":"string"},"location_code":{"description":"unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the
https://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or 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/ai_optimization/ai_keyword_data/locations_and_languages
example:
United Kingdom","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization ai keyword data keywords search volume live"},{"name":"ai_chat_gpt_llm_responses_live","description":"‌‌\nLive ChatGPT LLM Responses endpoint allows you to retrieve structured responses from a specific ChatGPT AI model, based on the input parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"max_output_tokens":200,"message_chain":[{"message":"Hello, what’s up?","role":"user"},{"message":"Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?","role":"ai"}],"model_name":"gpt-4.1-mini","system_message":"communicate as if we are in a business meeting","temperature":0.3,"top_p":0.5,"user_prompt":"provide information on how relevant the amusement park business is in France now","web_search":true,"web_search_city":"Paris","web_search_country_iso_code":"FR"}]],"items":{"oneOf":[{"examples":[[{"max_output_tokens":200,"message_chain":[{"message":"Hello, what’s up?","role":"user"},{"message":"Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?","role":"ai"}],"model_name":"gpt-4.1-mini","system_message":"communicate as if we are in a business meeting","temperature":0.3,"top_p":0.5,"user_prompt":"provide information on how relevant the amusement park business is in France now","web_search":true,"web_search_city":"Paris","web_search_country_iso_code":"FR"}]],"properties":{"force_web_search":{"description":"force AI agent to use web search
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response
Note #2: not supported in reasoning models","type":["boolean","null"]},"max_output_tokens":{"description":"maximum number of tokens in the AI response
optional field
minimum value for reasoning models (e.g., reasoning is true in the Models endpoint): 1024;
minimum value for non-reasoning models: 16;
maximum value: 4096;
default value: 2048
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit","type":["integer","null"]},"message_chain":{"description":"conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]","items":{"oneOf":[{"properties":{"message":{"description":"message text","type":["string","null"]},"role":{"description":"role of the user from whom the message originates","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"model_name":{"description":"name of the AI model
required field
model_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if gpt-4.1 is specified, the gpt-4.1-2025-04-14 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_responses/models","type":"string"},"system_message":{"description":"instructions for the AI behaviour
optional field
defines the AI's role, tone, or specific behavior
you can specify up to 500 characters in the system_message field","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"temperature":{"description":"randomness of the AI response
optional field
higher values make output more diverse;
lower values make output more focused;
minimum value: 0
maximum value: 2
default value: 0.94
Note: not supported in reasoning models","type":["number","null"]},"top_p":{"description":"diversity of the AI response
optional field
controls diversity of the response by limiting token selection;
minimum value: 0
maximum value: 1
default value: 0.92

Note: top_p cannot be used together with temperature in the same request","type":["number","null"]},"user_prompt":{"description":"prompt for the AI model
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field","type":"string"},"web_search":{"description":"enable web search
optional field
when enabled, the AI model can access and cite current web information;
default value: false;
Note: refer to the Models endpoint for a list of models that support web_search;","type":["boolean","null"]},"web_search_city":{"description":"city name of the location
optional field
Note: not supported in o3-mini, o1-pro, o1 models","type":["string","null"]},"web_search_country_iso_code":{"description":"ISO country code of the location
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model will search the web from the country you specify;
Note: not supported in o3-mini, o1-pro, o1 models","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization chat gpt llm responses live"},{"name":"ai_chat_gpt_llm_scraper_live_advanced","description":"‌‌\nLive ChatGPT LLM Scraper endpoint provides results from ChatGPT searches. The results are specific to the selected location (see the List of Locations) and language (see the List of Languages) parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"properties":{"force_web_search":{"description":"force AI agent to use web search
optional field
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response","type":["boolean","null"]},"keyword":{"description":"keyword
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name;
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages
example:
en","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code;
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locations
example:
2840","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locations
example:
United States","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization chat gpt llm scraper live advanced"},{"name":"ai_chat_gpt_llm_scraper_locations_country","description":"You will receive the list of locations by this API call. You can filter the list of locations by country when setting a task.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization chat gpt llm scraper locations country"},{"name":"ai_claude_llm_responses_live","description":"‌‌\nLive Claude LLM Responses endpoint allows you to retrieve structured responses from a specific Claude model, based on the input parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"max_output_tokens":200,"message_chain":[{"message":"Hello, what’s up?","role":"user"},{"message":"Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?","role":"ai"}],"model_name":"claude-opus-5","system_message":"communicate as if we are in a business meeting","temperature":0.3,"user_prompt":"provide information on how relevant the amusement park business is in France now","web_search":true,"web_search_country_iso_code":"FR"}]],"items":{"oneOf":[{"examples":[[{"max_output_tokens":200,"message_chain":[{"message":"Hello, what’s up?","role":"user"},{"message":"Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?","role":"ai"}],"model_name":"claude-opus-5","system_message":"communicate as if we are in a business meeting","temperature":0.3,"user_prompt":"provide information on how relevant the amusement park business is in France now","web_search":true,"web_search_country_iso_code":"FR"}]],"properties":{"force_web_search":{"description":"force AI agent to use web search
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response","type":["boolean","null"]},"max_output_tokens":{"description":"maximum number of tokens in the AI response
optional field
minimum value: 1;
maximum value: 4096;
default value: 2048;
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit
Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1025","type":["integer","null"]},"message_chain":{"description":"conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]","items":{"oneOf":[{"properties":{"message":{"description":"message text","type":["string","null"]},"role":{"description":"role of the user from whom the message originates","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"model_name":{"description":"name of the AI model
required field
model_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if claude-opus-4-0 is specified, the claude-opus-4-20250514 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/claude/llm_responses/models","type":"string"},"system_message":{"description":"instructions for the AI behaviour
optional field
defines the AI's role, tone, or specific behavior;
you can specify up to 500 characters in the system_message field","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"temperature":{"description":"randomness of the AI response
optional field
higher values make output more diverse;
lower values make output more focused;
minimum value: 0
maximum value: 1
default value: 0.7

Note: temperature cannot be used together with top_p in the same request","type":["number","null"]},"top_p":{"description":"diversity of the AI response
optional field
controls diversity of the response by limiting token selection;
minimum value: 0
maximum value: 1
default value: null

Note: top_p cannot be used together with temperature in the same request","type":["number","null"]},"use_reasoning":{"description":"enable reasoning for the AI model
optional field
when enabled, the model will perform reasoning before generating a response
refer to the Models endpoint for a list of models that support reasoning
default value: false
Note: if set to true, the minimum value for max_output_tokens is 1025
Note #2: if set to true, force_web_search must be set to false
Note #3: if set to true, the temperature and top_p cannot be used","type":["boolean","null"]},"user_prompt":{"description":"prompt for the AI model
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field","type":"string"},"web_search":{"description":"enable web search for current information
optional field
when enabled, the AI model can access and cite current web information;
Note: refer to the Models endpoint for a list of models that support web_search;
default value: false;
The cost of the parameter can be calculated on the Pricing page","type":["boolean","null"]},"web_search_city":{"description":"city name of the location used for searching the web
optional field
","type":["string","null"]},"web_search_country_iso_code":{"description":"ISO country code of the location used for searching the web
optional field
possible values: 'AR','AT','AU','BE','BR','CA','CH','CL','CN','DE','DK','ES','FI','FR','GB','HK','ID','IN','IT','JP','KR','MX','MY','NL','NO','NZ','PH','PL','PT','RU','SA','SE','TR','TW','US','ZA'","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization claude llm responses live"},{"name":"ai_gemini_llm_responses_live","description":"‌‌\nLive Gemini LLM Responses endpoint allows you to retrieve structured responses from a specific Gemini AI model, based on the input parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"max_output_tokens":200,"message_chain":[{"message":"Hello, what’s up?","role":"user"},{"message":"Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?","role":"ai"}],"model_name":"gemini-2.5-flash","system_message":"communicate as if we are in a business meeting","temperature":0.3,"top_p":0.5,"user_prompt":"provide information on how relevant the amusement park business is in France now","web_search":true}]],"items":{"oneOf":[{"examples":[[{"max_output_tokens":200,"message_chain":[{"message":"Hello, what’s up?","role":"user"},{"message":"Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?","role":"ai"}],"model_name":"gemini-2.5-flash","system_message":"communicate as if we are in a business meeting","temperature":0.3,"top_p":0.5,"user_prompt":"provide information on how relevant the amusement park business is in France now","web_search":true}]],"properties":{"max_output_tokens":{"description":"maximum number of tokens in the AI response
optional field
minimum value: 1
maximum value: 4096;
default value: 2048;
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit
Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1024","type":["integer","null"]},"message_chain":{"description":"conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]","items":{"oneOf":[{"properties":{"message":{"description":"message text","type":["string","null"]},"role":{"description":"role of the user from whom the message originates","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"model_name":{"description":"name of the AI model
required field
model_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if gemini-1.5-pro is specified, the gemini-1.5-pro-002 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_responses/models","type":"string"},"system_message":{"description":"instructions for the AI behavior
optional field
defines the AI's role, tone, or specific behavior
you can specify up to 500 characters in the system_message field","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"temperature":{"description":"randomness of the AI response
optional field
higher values make output more diverse
lower values make output more focused
minimum value: 0
maximum value: 2
default value: 1.3","type":["number","null"]},"top_p":{"description":"diversity of the AI response
optional field
controls diversity of the response by limiting token selection
minimum value: 0
maximum value: 1
default value: 0.9","type":["number","null"]},"use_reasoning":{"description":"enable reasoning for the AI model
optional field
when enabled, the model will perform reasoning before generating a response
refer to the Models endpoint for a list of models that support reasoning
default value: false
Note: if set to true, the minimum value for max_output_tokens is 1024
Note #2: for Gemini Pro models, the use_reasoning will automatically be set to true","type":["boolean","null"]},"user_prompt":{"description":"prompt for the AI model
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field","type":"string"},"web_search":{"description":"enable web search for current information
optional field
when enabled, the AI model can access and cite current web information;
Note: refer to the Models endpoint for a list of models that support web_search;
default value: false;
The cost of the parameter can be calculated on the Pricing page","type":["boolean","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization gemini llm responses live"},{"name":"ai_gemini_llm_scraper_live_advanced","description":"‌‌\nLive Gemini LLM Scraper endpoint provides structured results from Gemini. The results are specific to the selected location (see the List of Locations), language (see the List of Languages), and keyword.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"properties":{"keyword":{"description":"keyword
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”

GPS coordinates of a location

required field if you don't specify location_name or location_code

if you use this field, you don't need to specify location_name or location_code

location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format

the maximum number of decimal digits for \"latitude\" and \"longitude\": 7

the minimum value for \"radius\": 199 (mm)

the maximum value for \"radius\": 199999 (mm)

example:

53.476225,-2.243572,200

","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:
United States","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization gemini llm scraper live advanced"},{"name":"ai_llm_mentions_historical_live","description":"‌‌\nLive LLM Mentions Historical endpoint provides month-by-month historical metrics for mentions of the keywords or domains specified in the target array of the request. For each month, the response returns the total mentions count and ai_search_volume rate. The results are specific to the selected platform (google for Google’s AI Overview or chat_gpt for ChatGPT), location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"language_code":"es","location_code":2840,"platform":"google","target":[{"domain":"en.wikipedia.org","search_filter":"exclude"},{"keyword":"bmw","search_scope":["answer"]}]}]],"items":{"oneOf":[{"examples":[[{"language_code":"es","location_code":2840,"platform":"google","target":[{"domain":"en.wikipedia.org","search_filter":"exclude"},{"keyword":"bmw","search_scope":["answer"]}]}]],"properties":{"date_from":{"description":"start date of the time range
optional field
minimal value 2025-08-01
date format \"yyyy-mm-dd\"","type":["string","null"]},"date_to":{"description":"end date of the time range
optional field
Note value specified in date_from cannot exceed the value in date_to
date format \"yyyy-mm-dd\"","type":["string","null"]},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions historical live"},{"name":"ai_llm_mentions_multi_target_metrics_live","description":"‌‌\nLive LLM Mentions Multi-Target Metrics endpoint provides aggregated metrics grouped by custom keys for mentions of the keywords or domains specified in the target array of the request. Each item in the results array corresponds to the specified target. The results are specific to the selected platform (google for Google’s AI Overview or chat_gpt for ChatGPT), location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":5,"language_code":"en","location_code":2840,"platform":"google","targets":[{"key":"chat_gpt","target":[{"keyword":"chat gpt"}]},{"key":"claude","target":[{"keyword":"claude"}]},{"key":"gemini","target":[{"keyword":"gemini"}]},{"key":"perplexity","target":[{"keyword":"perplexity","search_filter":"include"}]}]}]],"items":{"oneOf":[{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":5,"language_code":"en","location_code":2840,"platform":"google","targets":[{"key":"chat_gpt","target":[{"keyword":"chat gpt"}]},{"key":"claude","target":[{"keyword":"claude"}]},{"key":"gemini","target":[{"keyword":"gemini"}]},{"key":"perplexity","target":[{"keyword":"perplexity","search_filter":"include"}]}]}]],"properties":{"filters":{"description":"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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"initial_dataset_filters":{"description":"array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
the full list of possible filters is available here.
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
sources_domain
search_results_domain
minimum value: 1
maximum value: 10
default value: 5","type":["integer","null"]},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"limit":{"description":"the maximum number of returned objects
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"offset":{"description":"offset in the results array of the returned mentions data
optional field
default value: 0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000, use the search_after_token if you would like to offset more results","type":["integer","null"]},"order_by":{"description":"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:
[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules","items":{"type":"string"},"type":["array","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"targets":{"items":{"oneOf":[{"properties":{"key":{"description":"key for grouping the results\nrequired field\ngroups results for comparison and serves as a label for the group;\nyou can specify up to 250 characters in the key field","type":["string","null"]},"target":{"items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions multi target metrics live"},{"name":"ai_llm_mentions_search_mentions_live","description":"‌‌\nLive LLM Mentions Search endpoint provides mention data and related metrics from AI searches. The results are specific to the selected platform (google for Google’s AI Overview or chat_gpt for ChatGPT), as well as location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["ai_search_volume",">",1000]],"language_name":"English","limit":3,"location_code":2840,"offset":0,"order_by":["ai_search_volume,desc"],"platform":"google","target":[{"domain":"dataforseo.com","search_filter":"exclude"},{"keyword":"bmw","search_scope":["answer"]}]}]],"items":{"oneOf":[{"examples":[[{"filters":[["ai_search_volume",">",1000]],"language_name":"English","limit":3,"location_code":2840,"offset":0,"order_by":["ai_search_volume,desc"],"platform":"google","target":[{"domain":"dataforseo.com","search_filter":"exclude"},{"keyword":"bmw","search_scope":["answer"]}]}]],"properties":{"filters":{"description":"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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"limit":{"description":"the maximum number of returned objects
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"offset":{"description":"offset in the results array of the returned mentions data
optional field
default value: 0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000, use the search_after_token if you would like to offset more results","type":["integer","null"]},"order_by":{"description":"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:
[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules","items":{"type":"string"},"type":["array","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"search_after_token":{"description":"token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 1000 results in a single request;
by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;
search_after_token values are unique for each subsequent task ;
Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions search mentions live"},{"name":"ai_llm_mentions_target_metrics_lite_live","description":"Live LLM Mentions Target Metrics Lite endpoint is the simplified version of the Target Metrics endpoint and provides a simplified view of aggregated LLM mentions for keywords and domains specified in the target array of the request. The results are specific to the selected platform (google for Google’s AI Overview or chat_gpt for ChatGPT), location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"language_code":"es","limit":6,"location_code":2840,"platform":"google","target":[{"domain":"en.wikipedia.org","search_filter":"exclude"},{"keyword":"bmw","search_scope":["answer"]}]}]],"items":{"oneOf":[{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"language_code":"es","limit":6,"location_code":2840,"platform":"google","target":[{"domain":"en.wikipedia.org","search_filter":"exclude"},{"keyword":"bmw","search_scope":["answer"]}]}]],"properties":{"initial_dataset_filters":{"description":"array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
the full list of possible filters is available here.
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"limit":{"description":"maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100","type":["integer","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"offset":{"description":"offset in the results array of the returned mentions data
optional field
default value: 0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000","type":["integer","null"]},"order_by":{"description":"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:
[\"ai_search_volume,desc\"]
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","items":{"type":"string"},"type":["array","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions target metrics lite live"},{"name":"ai_llm_mentions_target_metrics_live","description":"‌‌\nLive LLM Mentions Target Metrics endpoint provides aggregated metrics for mentions of the keywords or domains specified in the target array of the request. The results are specific to the selected platform (google for Google’s AI Overview or chat_gpt for ChatGPT), location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":10,"language_code":"en","location_code":2840,"platform":"chat_gpt","target":[{"domain":"en.wikipedia.org","search_filter":"exclude"},{"keyword":"bmw","search_scope":["answer"]}]}]],"items":{"oneOf":[{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":10,"language_code":"en","location_code":2840,"platform":"chat_gpt","target":[{"domain":"en.wikipedia.org","search_filter":"exclude"},{"keyword":"bmw","search_scope":["answer"]}]}]],"properties":{"initial_dataset_filters":{"description":"array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
the full list of possible filters is available here.
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
sources_domain
search_results_domain
minimum value: 1
maximum value: 10
default value: 10","type":["integer","null"]},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions target metrics live"},{"name":"ai_llm_mentions_timeseries_delta_live","description":"‌‌\nThe Live LLM Mentions Timeseries Delta endpoint provides the difference in historical mentions and AI search volume data between two specified dates. The results are specific to the specified target (keyword or domain), selected platform (google for Google’s AI Overview or chat_gpt for ChatGPT), as well as location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2025-08-01","date_to":"2025-12-01","group_range":"month","language_name":"English","location_code":2840,"platform":"google","target":[{"domain":"dataforseo.com","search_filter":"exclude"},{"keyword":"bmw","search_scope":["answer"]}]}]],"items":{"oneOf":[{"examples":[[{"date_from":"2025-08-01","date_to":"2025-12-01","group_range":"month","language_name":"English","location_code":2840,"platform":"google","target":[{"domain":"dataforseo.com","search_filter":"exclude"},{"keyword":"bmw","search_scope":["answer"]}]}]],"properties":{"date_from":{"description":"start date of the time range
required field
minimal value: 2025-08-01
date format: \"yyyy-mm-dd\"","type":"string"},"date_to":{"description":"end date of the time range
required field
Note:the value specified in date_from cannot exceed the value in date_to
date format: \"yyyy-mm-dd\"","type":"string"},"group_range":{"description":"timeseries delta range
required field
possible values:
day, week, month, year","type":"string"},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions timeseries delta live"},{"name":"ai_llm_mentions_timeseries_new_lost_live","description":"‌‌\nThis endpoint will provide you with the number of new and lost LLM mentions, as well as ai_search_volume for the domain or keyword specified in the target field.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2025-08-01","date_to":"2025-12-01","group_range":"month","language_name":"English","location_code":2840,"platform":"google","target":[{"domain":"dataforseo.com","search_filter":"exclude"},{"keyword":"serp","search_scope":["answer"]}]}]],"items":{"oneOf":[{"examples":[[{"date_from":"2025-08-01","date_to":"2025-12-01","group_range":"month","language_name":"English","location_code":2840,"platform":"google","target":[{"domain":"dataforseo.com","search_filter":"exclude"},{"keyword":"serp","search_scope":["answer"]}]}]],"properties":{"date_from":{"description":"start date of the time range
required field
minimal value: 2025-08-01
date format: \"yyyy-mm-dd\"","type":"string"},"date_to":{"description":"end date of the time range
required field
Note:the value specified in date_from cannot exceed the value in date_to
date format: \"yyyy-mm-dd\"","type":"string"},"group_range":{"description":"timeseries range
required field
possible values:
day, week, month, year","type":"string"},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions timeseries new lost live"},{"name":"ai_llm_mentions_top_mentioned_brand_categories_lite_live","description":"‌‌\nLive LLM Mentions Top Mentioned Brand Categories Lite endpoint is the simplified version of the Top Mentioned Brand Categories endpoint and provides a simplified view of aggregated LLM mentions metrics grouped by the most frequently mentioned brand categories for the specified target. The results are specific to the selected platform, location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"items":{"oneOf":[{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"properties":{"exclude_brand_categories":{"description":"array of brand categories to exclude from the response
optional field
if specified, the listed brand categories will be omitted from the items array
example:
[\"company\",\"insurance\"]","items":{"type":"string"},"type":["array","null"]},"filters":{"description":"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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_brand_categories":{"description":"array of brand categories to include in the response
optional field
if specified, only the listed brand categories will be returned in the items array
example:
[\"company\",\"insurance\"]","items":{"type":"string"},"type":["array","null"]},"initial_dataset_filters":{"description":"array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
the full list of possible filters is available here.
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5","type":["integer","null"]},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"limit":{"description":"maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100","type":["integer","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"offset":{"description":"offset in the results array of the returned mentions data
optional field
default value: 0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000","type":["integer","null"]},"order_by":{"description":"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:
[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules","items":{"type":"string"},"type":["array","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
default value: google
Note: data specific to brand entities is available for chat_gpt only;
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Top brand categories mentioned by LLMs (Lite)"},{"name":"ai_llm_mentions_top_mentioned_brand_categories_live","description":"‌‌\nLive LLM Mentions Top Mentioned Brand Categories endpoint provides aggregated LLM mentions metrics grouped by the most frequently mentioned brand categories for the specified target. The results are specific to the selected platform, location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"items":{"oneOf":[{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"properties":{"exclude_brand_categories":{"description":"array of brand categories to exclude from the response
optional field
if specified, the listed brand categories will be omitted from the items array
example:
\"exclude_brand_categories\": [\"business\"]","items":{"type":"string"},"type":["array","null"]},"filters":{"description":"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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_brand_categories":{"description":"array of brand_categories to include in the response
optional field
if specified, only the listed brand categories will be returned in the items array
example:
\"include_brand_categories\": [\"business\"]","items":{"type":"string"},"type":["array","null"]},"initial_dataset_filters":{"description":"array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
the full list of possible filters is available here.
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5","type":["integer","null"]},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"limit":{"description":"maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100","type":["integer","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"offset":{"description":"offset in the results array of the returned mentions data
optional field
default value: 0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000","type":["integer","null"]},"order_by":{"description":"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:
[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules","items":{"type":"string"},"type":["array","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
Note: data specific to brand entities is available for chat_gpt only;
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Top brand categories mentioned by LLMs"},{"name":"ai_llm_mentions_top_mentioned_brands_lite_live","description":"‌‌\nLive LLM Mentions Top Mentioned Brands Lite endpoint is the simplified version of the Top Mentioned Brands endpoint and provides a simplified view of aggregated LLM mentions metrics grouped by the most frequently mentioned brands for the specified target. The results are specific to the selected platform, location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"items":{"oneOf":[{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"properties":{"exclude_brands":{"description":"array of brands to exclude from the response
optional field
if specified, the listed brands will be omitted from the items array
example:
[\"BMW\",\"Audi\"]","items":{"type":"string"},"type":["array","null"]},"filters":{"description":"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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\", 1000]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_brands":{"description":"array of brands to include in the response
optional field
if specified, only the listed brands will be returned in the items array
example:
[\"BMW\",\"Audi\"]","items":{"type":"string"},"type":["array","null"]},"initial_dataset_filters":{"description":"array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
the full list of possible filters is available here.
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5","type":["integer","null"]},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"limit":{"description":"maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100","type":["integer","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"offset":{"description":"offset in the results array of the returned mentions data
optional field
default value: 0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000","type":["integer","null"]},"order_by":{"description":"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:
[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules","items":{"type":"string"},"type":["array","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
default value: google
Note: data specific to brand entities is available for chat_gpt only;
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions top mentioned brands lite live"},{"name":"ai_llm_mentions_top_mentioned_brands_live","description":"‌‌\nLive LLM Mentions Top Mentioned Brands endpoint provides aggregated LLM mentions metrics grouped by the most frequently mentioned brands for the specified target. The results are specific to the selected platform, location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"items":{"oneOf":[{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"properties":{"exclude_brands":{"description":"array of brands to exclude from the response
optional field
if specified, the listed brands will be omitted from the items array
example:
\"exclude_brands\": [\"Audi\"]","items":{"type":"string"},"type":["array","null"]},"filters":{"description":"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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_brands":{"description":"array of brands to include in the response
optional field
if specified, only the listed brands will be returned in the items array
example:
\"include_brands\": [\"Audi\"]","items":{"type":"string"},"type":["array","null"]},"initial_dataset_filters":{"description":"array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
the full list of possible filters is available here.
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5","type":["integer","null"]},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"limit":{"description":"maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100","type":["integer","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"offset":{"description":"offset in the results array of the returned mentions data
optional field
default value: 0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000","type":["integer","null"]},"order_by":{"description":"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:
[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules","items":{"type":"string"},"type":["array","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
Note: data specific to brand entities is available for chat_gpt only;
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions top mentioned brands live"},{"name":"ai_llm_mentions_top_mentioned_domains_lite_live","description":"‌‌\nLive LLM Mentions Top Mentioned Domains Lite endpoint is the simplified version of the Top Mentioned Domains endpoint and provides a simplified view of aggregated LLM mentions metrics grouped by the most frequently mentioned domains for the specified target. The results are specific to the selected platform (google for Google’s AI Overview or chat_gpt for ChatGPT), location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"links_scope":"sources","location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"items":{"oneOf":[{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"links_scope":"sources","location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"properties":{"exclude_domains":{"description":"array of domains to exclude from the response
optional field
if specified, the listed domains will be omitted from the items array
example:
[\"google.com\",\"bing.com\"]","items":{"type":"string"},"type":["array","null"]},"filters":{"description":"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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_domains":{"description":"array of domains to include in the response
optional field
if specified, only the listed domains will be returned in the items array
example:
[\"dataforseo.com\",\"seoinsider.com\"]","items":{"type":"string"},"type":["array","null"]},"initial_dataset_filters":{"description":"array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
the full list of possible filters is available here.
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5","type":["integer","null"]},"language_code":{"description":"search 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 of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en onlyn","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"limit":{"description":"maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100","type":["integer","null"]},"links_scope":{"description":"links source scope
optional field
this parameter specifies which links will be used to extract domains and aggregation data
possible values: sources, search_results
default value: sources;
Note: if you specify search_results, the data will be available for chat_gpt only","type":["string","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"offset":{"description":"offset in the results array of the returned mentions data
optional field
default value: 0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000","type":["integer","null"]},"order_by":{"description":"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:
[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules","items":{"type":"string"},"type":["array","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions top mentioned domains lite live"},{"name":"ai_llm_mentions_top_mentioned_domains_live","description":"‌‌\nLive LLM Mentions Top Mentioned Domains endpoint provides aggregated LLM mentions metrics grouped by the most frequently mentioned domains for the specified target. The results are specific to the selected platform (google for Google’s AI Overview or chat_gpt for ChatGPT), location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"links_scope":"sources","location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"items":{"oneOf":[{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"links_scope":"sources","location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"properties":{"exclude_domains":{"description":"array of domains to exclude from the response
optional field
if specified, the listed domains will be omitted from the items array
example:
\"exclude_domains\": [\"en.wikipedia.org\"]","items":{"type":"string"},"type":["array","null"]},"filters":{"description":"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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_domains":{"description":"array of domains to include in the response
optional field
if specified, only the listed domains will be returned in the items array
example:
\"include_domains\": [\"en.wikipedia.org\"]","items":{"type":"string"},"type":["array","null"]},"initial_dataset_filters":{"description":"array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
the full list of possible filters is available here.
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5","type":["integer","null"]},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"limit":{"description":"maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100","type":["integer","null"]},"links_scope":{"description":"links source scope
optional field
this parameter specifies which links will be used to extract domains and aggregation data
possible values: sources, search_results
default value: sources
Note:if you specify search_results, the data will be available for chat_gpt only","type":["string","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"offset":{"description":"offset in the results array of the returned mentions data
optional field
default value: 0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000","type":["integer","null"]},"order_by":{"description":"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:
[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules","items":{"type":"string"},"type":["array","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions top mentioned domains live"},{"name":"ai_llm_mentions_top_mentioned_pages_lite_live","description":"‌‌\nLive LLM Mentions Top Mentioned Pages Lite endpoint is a simplified version of the Top Mentioned Pages that provides a simplified view of aggregated LLM mentions metrics grouped by the most frequently mentioned pages for the specified target. The results are specific to the selected platform (google for Google’s AI Overview or chat_gpt for ChatGPT), location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"links_scope":"sources","location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"items":{"oneOf":[{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"links_scope":"sources","location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"properties":{"exclude_pages":{"description":"array of page URLs to exclude from the response
optional field
if specified, the listed pages will be omitted from the items array
example:
`[\"https://dataforseo.com/apis/ai-optimization-api/llm-mentions-api\", \"https://dataforseo.com/apis/ai-optimization-api\"]`","items":{"type":"string"},"type":["array","null"]},"filters":{"description":"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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_pages":{"description":"array of page URLs to include in the response
optional field
if specified, only the listed pages will be returned in the items array
example:
`[\"https://dataforseo.com/apis/ai-optimization-api/llm-mentions-api\", \"https://dataforseo.com/apis/ai-optimization-api\"]`","items":{"type":"string"},"type":["array","null"]},"initial_dataset_filters":{"description":"array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
the full list of possible filters is available here.
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5","type":["integer","null"]},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"limit":{"description":"maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100","type":["integer","null"]},"links_scope":{"description":"links source scope
optional field
this parameter specifies which links will be used to extract domains and aggregation data
possible values: sources, search_results
default value: sources; ;
Note: if you specify search_results, the data will be available for chat_gpt only","type":["string","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"offset":{"description":"offset in the results array of the returned mentions data
optional field
default value: 0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000","type":["integer","null"]},"order_by":{"description":"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:
[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules","items":{"type":"string"},"type":["array","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions top mentioned pages lite live"},{"name":"ai_llm_mentions_top_mentioned_pages_live","description":"‌‌\nLive LLM Mentions Top Mentioned Pages endpoint provides aggregated LLM mentions metrics grouped by the most frequently mentioned pages for the specified target. The results are specific to the selected platform (google for Google’s AI Overview or chat_gpt for ChatGPT), location and language parameters (see the List of Locations & Languages).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"links_scope":"sources","location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"items":{"oneOf":[{"examples":[[{"initial_dataset_filters":[["ai_search_volume",">",10]],"internal_list_limit":2,"language_code":"en","limit":3,"links_scope":"sources","location_code":2840,"platform":"chat_gpt","target":[{"keyword":"bmw","search_scope":["answer"]},{"keyword":"auto","match_type":"partial_match","search_scope":["question"]}]}]],"properties":{"exclude_pages":{"description":"array of pages to exclude from the response
optional field
if specified, the listed pages will be omitted from the items array
example:
\"exclude_pages\": [\"https://example.page/\"]","items":{"type":"string"},"type":["array","null"]},"filters":{"description":"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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_pages":{"description":"array of pages to include in the response
optional field
if specified, only the listed pages will be returned in the items array
example:
\"include_pages\": [\"https://example.page/\"]","items":{"type":"string"},"type":["array","null"]},"initial_dataset_filters":{"description":"array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"ai_search_volume\",\">\",1000]
the full list of possible filters is available here.
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5","type":["integer","null"]},"language_code":{"description":"search 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 of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only","type":["string","null"]},"language_name":{"description":"full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only","type":["string","null"]},"limit":{"description":"maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100","type":["integer","null"]},"links_scope":{"description":"links source scope
optional field
this parameter specifies which links will be used to extract domains and aggregation data
possible values: sources, search_results
default value: sources;
Note:if you specify search_results, the data will be available for chat_gpt only","type":["string","null"]},"location_code":{"description":"search 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 of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only","type":["integer","null"]},"location_name":{"description":"full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only","type":["string","null"]},"offset":{"description":"offset in the results array of the returned mentions data
optional field
default value: 0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000","type":["integer","null"]},"order_by":{"description":"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:
[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules","items":{"type":"string"},"type":["array","null"]},"platform":{"description":"target platform
optional field
possible values:
chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity","items":{"oneOf":[{"discriminator":{"mapping":{"domain":"#/components/schemas/AiOptimizationLLmMentionsDomainElement","keyword":"#/components/schemas/AiOptimizationLLmMentionsKeywordElement"},"propertyName":"type"},"properties":{"search_filter":{"description":"target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include","type":["string","null"]},"search_scope":{"description":"target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any","items":{"type":["string","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization llm mentions top mentioned pages live"},{"name":"ai_perplexity_llm_responses_live","description":"‌‌\nLive Perplexity LLM Responses endpoint allows you to retrieve structured responses from a specific Perplexity AI model, based on the input parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"max_output_tokens":200,"message_chain":[{"message":"Hello, what’s up?","role":"user"},{"message":"Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?","role":"ai"}],"model_name":"sonar","system_message":"communicate as if we are in a business meeting","temperature":0.3,"top_p":0.5,"user_prompt":"provide information on how relevant the amusement park business is in France now","web_search_country_iso_code":"FR"}]],"items":{"oneOf":[{"examples":[[{"max_output_tokens":200,"message_chain":[{"message":"Hello, what’s up?","role":"user"},{"message":"Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?","role":"ai"}],"model_name":"sonar","system_message":"communicate as if we are in a business meeting","temperature":0.3,"top_p":0.5,"user_prompt":"provide information on how relevant the amusement park business is in France now","web_search_country_iso_code":"FR"}]],"properties":{"max_output_tokens":{"description":"maximum number of tokens in the AI response
optional field
minimum value: 1
maximum value: 4096;
default value: 2048;
Note: if the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit","type":["integer","null"]},"message_chain":{"description":"conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]","items":{"oneOf":[{"properties":{"message":{"description":"message text","type":["string","null"]},"role":{"description":"role of the user from whom the message originates","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"model_name":{"description":"name of the AI model
required field
model_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
you can receive the list of available LLM models by making a separate request to the following endpoint: https://api.dataforseo.com/v3/ai_optimization/perplexity/llm_responses/models","type":"string"},"system_message":{"description":"instructions for the AI behavior
optional field
defines the AI's role, tone, or specific behavior
you can specify up to 500 characters in the system_message field","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"temperature":{"description":"randomness of the AI response
optional field
higher values make output more diverse
lower values make output more focused
minimum value: 0
maximum value: 1.9
default value: 0.77","type":["number","null"]},"top_p":{"description":"diversity of the AI response
optional field
controls diversity of the response by limiting token selection
minimum value: 0
maximum value: 1
default value: 0.9","type":["number","null"]},"user_prompt":{"description":"prompt for the AI model
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field","type":"string"},"web_search_country_iso_code":{"description":"country code for web search localization
optional field
specify the country ISO code to get localized web search results
Note: available only for Perplexity Sonar models
example: US","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ai optimization perplexity llm responses live"},{"name":"anchors","description":"‌‌\nThis endpoint will provide you with a detailed overview of anchors used when linking to the specified website with relevant backlink data for each of them.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":["anchor","like","%news%"],"limit":4,"order_by":["backlinks,desc"],"target":"forbes.com"}]],"items":{"oneOf":[{"examples":[[{"filters":["anchor","like","%news%"],"limit":4,"order_by":["backlinks,desc"],"target":"forbes.com"}]],"properties":{"backlinks_filters":{"description":"filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:
\"backlinks_filters\": [[\"dofollow\", \"=\", true]]","items":{"type":["object","null"]},"type":["array","null"]},"backlinks_status_type":{"description":"set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values:
all - all backlinks will be returned and counted;
live - backlinks found during the last check will be returned and counted;
lost - lost backlinks will be returned and counted;
default value: live","type":["string","null"]},"exclude_internal_backlinks":{"description":"indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be ommited and you won't receive the same domain in the response;
default value: true","type":["boolean","null"]},"filters":{"description":"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, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"referring_links_types.anchors\",\">\",\"1\"]
[[\"broken_pages\",\">\",\"2\"], \"and\", [\"backlinks\",\">\",\"10\"]]
[[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"], \"and\", [[\"anchor\",\"like\",\"%seo%\"],\"or\",[\"referring_domains\",\">\",\"10\"]]]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_indirect_links":{"description":"indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true","type":["boolean","null"]},"include_subdomains":{"description":"indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
referring_links_tld
referring_links_types
referring_links_attributes
referring_links_platform_types
referring_links_semantic_locations
default value: 10
maximum value: 1000","type":["integer","null"]},"limit":{"description":"the maximum number of returned anchors
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned anchors
optional field
default value: 0
if you specify the 10 value, the first ten anchors in the results array will be omitted and the data will be provided for the successive anchors","type":["integer","null"]},"order_by":{"description":"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:
[\"backlinks,desc\"]
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:
[\"backlinks,desc\",\"rank,asc\"]","items":{"type":"string"},"type":["array","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain, subdomain or webpage to get anchors for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Anchors","catalog":"web.anchors.list"},{"name":"app_data_apple_app_info_task_get_advanced_id","description":"This endpoint will provide you with information about the mobile application specified in a POST request. You will receive its ID, icon, description, reviews count, rating, images, and other data. The results are specific to the app_id parameter specified in the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data apple app info task get advanced id"},{"name":"app_data_apple_app_info_task_post","description":"‌‌\nThis endpoint will provide you with information about the App Store application specified in the app_id field of the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_id":"835599320","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_id":"835599320","language_code":"en","location_code":2840}]],"properties":{"app_id":{"description":"id of the app
required field
ID of the mobile application on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL `https://apps.apple.com/us/app/id835599320`
the id is `835599320`","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
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 `https://api.dataforseo.com/v3/app_data/apple/languages`
example:
en","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to `https://api.dataforseo.com/v3/app_data/apple/languages`
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to `https://api.dataforseo.com/v3/app_data/apple/locations`
example:
9061121","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to `https://api.dataforseo.com/v3/app_data/apple/locations`
example:
West Los Angeles,California,United States","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
`http://your-server.com/pingscript?id=$id`
`http://your-server.com/pingscript?id=$id&tag=$tag`
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_data":{"description":"postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:
advanced","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
`http://your-server.com/postbackscript?id=$id`
`http://your-server.com/postbackscript?id=$id&tag=$tag`
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priority You will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data apple app info task post"},{"name":"app_data_apple_app_list_task_get_advanced_id","description":"This endpoint will provide you with a list of applications published in the top app charts on the App Store platform, including app IDs, ratings, prices, titles, and more. The results are specific to the app_collection as well as the location and language parameters specified in the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data apple app list task get advanced id"},{"name":"app_data_apple_app_list_task_post","description":"This endpoint will provide you with a list of mobile applications published in the top app charts on the App Store platform. The returned results are specific to the app collection as well as the language and location parameters.\nfor more info please visit 'https://docs.dataforseo.com/v3/app_data/apple/app_list/task_post/?bash'","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_category":"games","app_collection":"top_free_ios","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_category":"games","app_collection":"top_free_ios","language_code":"en","location_code":2840}]],"properties":{"app_category":{"description":"application category on the App Storeoptional fieldyou can filter the results by app category;example:lifestyle;you can review the full list of available categories here or by making a separate request to https://api.dataforseo.com/v3/app_data/apple/categories","type":["string","null"]},"app_collection":{"description":"app collectionrequired fieldapp collection on App Store from which apps will be collected;you can specify the following values:top_free_ios, top_paid_ios, top_grossing_ios, new_ios, new_free_ios, new_paid_ios","type":"string"},"depth":{"description":"parsing depthoptional fieldnumber of apps to be returned from the App Store SERP;default value: 100maximum value: 100Your account will be billed per each SERP containing up to 100 results; The cost can be calculated on the Pricing page.","type":["integer","null"]},"language_code":{"description":"\"search engine language coderequired field if you don't specify language_nameif you use this field, you don't need to specify language_nameyou can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languagesexample:en","type":["string","null"]},"language_name":{"description":"full name of search engine languagerequired field if you don't specify language_codeif you use this field, you don't need to specify language_codeyou can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languagesexample:English","type":["string","null"]},"location_code":{"description":"search engine location coderequired field if you don't specify location_nameif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locationsexample:9061121","type":["integer","null"]},"location_name":{"description":"full name of search engine locationrequired field if you don't specify location_codeif you use this field, you don't need to specify location_codeyou can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locationsexample:West Los Angeles,California,United States","type":["string","null"]},"pingback_url":{"description":"notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagNote: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center","type":["string","null"]},"postback_data":{"description":"postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:advanced","type":["string","null"]},"postback_url":{"description":"URL for sending task resultsoptional fieldonce the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specifiedyou can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagNote: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priorityoptional fieldcan take the following values:1 – normal execution priority (set by default)2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data apple app list task post"},{"name":"app_data_apple_app_listings_search_live","description":"This endpoint will provide you with a list of apps published on App Store along with additional information: its ID, icon, reviews count, rating, price, and other data. The results are specific to the title, description, and categories parameters specified in the API request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"categories":["Utilities"],"description":"vpn","filters":[["item.rating.value",">",4.5]],"limit":10,"order_by":["item.rating.value,desc"],"title":"vpn"}]],"items":{"oneOf":[{"examples":[[{"categories":["Utilities"],"description":"vpn","filters":[["item.rating.value",">",4.5]],"limit":10,"order_by":["item.rating.value,desc"],"title":"vpn"}]],"properties":{"categories":{"description":"app categories
optional field
the categories you specify are used to search for app listings;
you can get the full list of available app listing categories by this link
you can specify up to 10 categories","items":{"type":"string"},"type":["array","null"]},"description":{"description":"keyword in the app's description
optional field
keywords that occur in the description of the app;
can contain up to 200 characters","type":["string","null"]},"filters":{"description":"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, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"rating.value\",\">\",3]
you can receive the list of available filters_by making a separate request to https://api.dataforseo.com/v3/app_data/apple/app_listings/available_filtersn","items":{"type":["object","null"]},"type":["array","null"]},"limit":{"description":"the maximum number of returned apps
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned apps
optional field
default value: 0
if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead.","type":["integer","null"]},"offset_token":{"description":"token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;
offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center","type":["string","null"]},"order_by":{"description":"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 parameter
example:
[\"item.rating.value,desc\"]
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:
[\"item.rating.value,desc\",\"item.rating.value,desc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"title":{"description":"keyword in the app's title
optional field
keywords that occur in the title of the app;
can contain up to 200 characters","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data apple app listings search live"},{"name":"app_data_apple_app_reviews_task_get_advanced_id","description":"This endpoint will provide you with feedback data on applications listed on the App Store platform, including review ratings, review content, user profile info of each reviewer, review publication dates, and more. The results are specific to the app_id as well as the location and language parameters specified in the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data apple app reviews task get advanced id"},{"name":"app_data_apple_app_reviews_task_post","description":"‌‌\nThis endpoint will provide you with reviews published on the App Store platform for the app specified in the app_id field. The returned results are specific to the indicated language and location parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_id":"835599320","depth":200,"language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_id":"835599320","depth":200,"language_code":"en","location_code":2840}]],"properties":{"app_id":{"description":"id of the app
required field
ID of the mobile application on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL https://apps.apple.com/us/app/id835599320
the id is 835599320","type":"string"},"depth":{"description":"parsing depth
optional field
number of reviews to be returned in the API response;
we strongly recommend setting the parsing depth in the multiples of 25, because our system processes 25 reviews in a row;
default value: 25;
maximum value: 500;
Your account will be billed per each SERP containing up to 25 results;
Setting depth above 25 may result in additional charges if the search engine returns more than 25 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"language_code":{"description":"search engine language code
required field if you don't specify language_name
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 https://api.dataforseo.com/v3/app_data/apple/languages
example:
enn","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations
example:
9061121","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations
example:
West Los Angeles,California,United States","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_data":{"description":"postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:
advanced","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"sort_by":{"description":"results sorting parameters
optional field
you can use this field to sort the results;
possible types of sorting:
most_recent — sort by the most recent reviews;
most_helpful — sort by the most relevant reviews;
default rule: most_helpful","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data apple app reviews task post"},{"name":"app_data_apple_app_searches_task_get_advanced_id","description":"This endpoint will provide you with a list of apps ranking on the App Store for the keyword specified in a POST request. You will also receive additional information about each application: its ID, icon, reviews count, rating, price, and other data. The results are specific to the keyword as well as location and language parameters specified in the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data apple app searches task get advanced id"},{"name":"app_data_apple_app_searches_task_post","description":"‌‌\nThis endpoint will provide you with a list of apps ranking on the App Store for the specified keyword. The returned results are specific to the indicated keyword, as well as the location and language parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"depth":200,"keyword":"vpn","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"depth":200,"keyword":"vpn","language_code":"en","location_code":2840}]],"properties":{"depth":{"description":"parsing depth
optional field
number of results to be returned from the App Store SERP;
we strongly recommend setting the parsing depth in the multiples of 100, because our system processes 100 results in a row;
default value: 100
maximum value: 700
Your account will be billed per each SERP containing up to 100 results;
Setting depth above 100 may result in additional charges if the search engine returns more than 100 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"keyword":{"description":"keyword
required field
you can specify up to 700 characters in the keyword field;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"search engine language code
required field if language_name is not specified
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 https://api.dataforseo.com/v3/app_data/apple/languages
example:
enn","type":"string"},"language_name":{"description":"full name of search engine language
required field if language_code is not specified
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations
example:
9061121","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations
example:
West Los Angeles,California,United States","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_data":{"description":"postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:
advanced","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data apple app searches task post"},{"name":"app_data_google_app_info_task_get_advanced_id","description":"This endpoint will provide you with information about the mobile application specified in a POST request. You will receive its ID, icon, description, reviews count, rating, number of installs, images, and other data. The results are specific to the app_id parameter specified in the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data google app info task get advanced id"},{"name":"app_data_google_app_info_task_post","description":"‌‌\nThis endpoint will provide you with information about the Google Play application specified in the app_id field of the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_id":"org.telegram.messenger","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_id":"org.telegram.messenger","language_code":"en","location_code":2840}]],"properties":{"app_id":{"description":"id of the app
required field
ID of the mobile application on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:
in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger
the id is org.telegram.messenger","type":"string"},"language_code":{"description":"search engine language code
required field if language_name is not specified
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 https://api.dataforseo.com/v3/app_data/google/languages
example:
en","type":"string"},"language_name":{"description":"full name of search engine language
required field if language_code is not specified
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:
9061121","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:
West Los Angeles,California,United States","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23","type":["string","null"]},"postback_data":{"description":"postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:
advanced, html","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data google app info task post"},{"name":"app_data_google_app_list_task_get_advanced_id","description":"This endpoint will provide you with a list of applications published in the top charts on the Google Play platform, including app IDs, ratings, prices, titles, and more. The results are specific to the app_collection as well as the location and language parameters specified in the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data google app list task get advanced id"},{"name":"app_data_google_app_list_task_post","description":"‌‌\nThis endpoint will provide you with a list of mobile applications published in the top charts on the Google Play platform. The returned results are specific to the app collection as well as the the language and location parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_collection":"topselling_free","depth":100,"language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_collection":"topselling_free","depth":100,"language_code":"en","location_code":2840}]],"properties":{"age_rating":{"description":"filter results by age rating
optional field
you can use this field to filter the results by age rating;
possible types of filtering:
ages_up_to_5 — return apps approved for children up to 5 years old;
ages_6_8 — return apps approved for children from 6 to 8 years old;
ages_9_12 — return apps approved for children from 9 to 12 years old;
by default, the API returns apps for all ages;
Note: this filter works only in conjunction with the \"category\": \"family\" parameter","type":["string","null"]},"app_category":{"description":"application category on Google Play
optional field
you can filter the results by app category;
example:
family;
you can receive the full list of available categories by making a separate request to https://api.dataforseo.com/v3/app_data/google/categories
Note: app_category cannot be used if app_collection parameter is set to featured","type":["string","null"]},"app_collection":{"description":"app collection
required field
app collection on Google Play from which apps will be collected;
you can specify the following values:
featured, topselling_paid, topselling_free, topselling_new_free, topselling_new_paid, topgrossing, movers_shakers
Note: if featured is selected, the app_category parameter cannot be used","type":"string"},"depth":{"description":"parsing depth
optional field
number of apps to be returned in the API response;
we strongly recommend setting the parsing depth in the multiples of 100, because our system processes 100 results in a row;
default value: 100;
maximum value: 200;
Your account will be billed per each SERP containing up to 100 results;
Setting depth above 100 may result in additional charges if the search engine returns more than 100 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"language_code":{"description":"search engine language code
required field if language_name is not specified
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 https://api.dataforseo.com/v3/app_data/google/languages
example:
en","type":"string"},"language_name":{"description":"full name of search engine language
required field if language_code is not specified
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:
9061121","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:
West Los Angeles,California,United States","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23","type":["string","null"]},"postback_data":{"description":"postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:
advanced, html","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data google app list task post"},{"name":"app_data_google_app_listings_search_live","description":"This endpoint will provide you with a list of apps published on Google Play along with additional information: its ID, icon, reviews count, rating, price, and other data. The results are specific to the title, description, and categories parameters specified in the API request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"categories":["Tools"],"description":"vpn","filters":[["item.rating.value",">",4.5]],"limit":10,"order_by":["item.installs_count,asc"],"title":"vpn"}]],"items":{"oneOf":[{"examples":[[{"categories":["Tools"],"description":"vpn","filters":[["item.rating.value",">",4.5]],"limit":10,"order_by":["item.installs_count,asc"],"title":"vpn"}]],"properties":{"categories":{"description":"app categories
optional field
the categories you specify are used to search for app listings;
you can get the full list of available app listing categories by this link
you can specify up to 10 categories","items":{"type":"string"},"type":["array","null"]},"description":{"description":"keyword in the app's description
optional field
keywords that occur in the description of the app;
can contain up to 200 characters","type":["string","null"]},"filters":{"description":"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, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"item.rating.value\",\">\",3]
you can receive the list of available filters_by making a separate request to https://api.dataforseo.com/v3/app_data/google/app_listings/available_filters","items":{"type":["object","null"]},"type":["array","null"]},"limit":{"description":"the maximum number of returned apps
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned apps
optional field
default value: 0
if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead.","type":["integer","null"]},"offset_token":{"description":"token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;
offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center","type":["string","null"]},"order_by":{"description":"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 parameter
example:
[\"item.installs_count,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:
[\"item.rating.value,desc\",\"item.installs_count,asc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"title":{"description":"keyword in the app's title
optional field
keywords that occur in the title of the app;
can contain up to 200 characters","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data google app listings search live"},{"name":"app_data_google_app_reviews_task_get_advanced_id","description":"This endpoint will provide you with feedback data on applications listed on the Google Play platform, including review ratings, review content, user profile info of each reviewer, review publication dates, and more. The results are specific to the app_id as well as the location and language parameters specified in the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data google app reviews task get advanced id"},{"name":"app_data_google_app_reviews_task_post","description":"‌‌\nThis endpoint will provide you with reviews published on the Google Play platform for the app specified in the app_id field. The returned results are specific to the indicated language and location parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_id":"org.telegram.messenger","depth":150,"language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_id":"org.telegram.messenger","depth":150,"language_code":"en","location_code":2840}]],"properties":{"app_id":{"description":"id of the app
required field
ID of the mobile application on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:
https://play.google.com/store/apps/details?id=org.telegram.messenger","type":"string"},"depth":{"description":"parsing depth
optional field
number of reviews to be returned in the API response;
we strongly recommend setting the parsing depth in the multiples of 150, because our system processes 150 reviews in a row;
default value: 150;
maximum value: 100000;
Your account will be billed per each SERP containing up to 150 results;
Setting depth above 150 may result in additional charges if the search engine returns more than 150 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"language_code":{"description":"search engine language code
required field if you don't specify language_name
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 https://api.dataforseo.com/v3/app_data/google/languages
example:
en","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:
9061121","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:
West Los Angeles,California,United States","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23","type":["string","null"]},"postback_data":{"description":"postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:
advanced, html","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"rating":{"description":"filter reviews by rating
optional field
you can use this field to filter the results;
possible types of filtering:
5 — return reviews with five-star rating only;
4 — return reviews with four-star rating only;
3 — return reviews with three-star rating only;
2 — return reviews with two-star rating only;
1 — return reviews with one-star rating only;
by default, the API returns all reviews regardless of the number of stars","type":["integer","null"]},"sort_by":{"description":"results sorting parameters
optional field
you can use this field to sort the results;
possible types of sorting:
newest — sort by the most recent reviews;
most_relevant — sort by the most relevant reviews;
default rule: most_relevant","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data google app reviews task post"},{"name":"app_data_google_app_searches_task_get_advanced_id","description":"This endpoint will provide you with a list of apps ranking on Google Play for the keyword specified in a POST request. You will also receive additional information about each application: its ID, icon, reviews count, rating, price, and other data. The results are specific to the keyword as well as location and language parameters specified in the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data google app searches task get advanced id"},{"name":"app_data_google_app_searches_task_post","description":"‌‌\nThis endpoint will provide you with a list of apps ranking on Google Play for the specified keyword. The returned results are specific to the indicated keyword, as well as the language and location parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"depth":30,"keyword":"vpn","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"depth":30,"keyword":"vpn","language_code":"en","location_code":2840}]],"properties":{"depth":{"description":"parsing depth
optional field
number of results to be returned to be returned from the Google Play SERP;
we strongly recommend setting the parsing depth in the multiples of 30, because our system processes 30 results in a row;
default value: 30;
maximum value: 200;
Your account will be billed per each SERP containing up to 30 results;
Setting depth above 30 may result in additional charges if the search engine returns more than 30 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"keyword":{"description":"keyword
required field
you can specify up to 700 characters in the keyword field;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"search engine 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 https://api.dataforseo.com/v3/app_data/google/languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of search engine 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 language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:
English","type":["string","null"]},"location_code":{"description":"search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:
9061121","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:
West Los Angeles,California,United States","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23","type":["string","null"]},"postback_data":{"description":"postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:
advanced, html","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data google app searches task post"},{"name":"app_data_google_locations_country","description":"By calling this endpoint you will receive the list of Google locations supported in App Data API.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code\noptional field\nspecify the ISO code if you want to filter the list of locations by country\nexample:\nus","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"App data google locations country"},{"name":"backlink_competitors","description":"‌‌\nThis endpoint will provide you with a list of competitors that share some part of the backlink profile with a target website, along with a number of backlink intersections and the rank of every competing website.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":["rank",">",100],"limit":5,"order_by":["rank,desc"],"target":"dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"filters":["rank",">",100],"limit":5,"order_by":["rank,desc"],"target":"dataforseo.com"}]],"properties":{"exclude_internal_backlinks":{"description":"indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true","type":["boolean","null"]},"exclude_large_domains":{"description":"indicates whether large domain will appear in results
optional field
if set to true, the results from the large domain (google.com, amazon.com, etc.) will be omitted;
default value: true","type":["boolean","null"]},"filters":{"description":"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, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"rank\",\">\",\"100\"]
[[\"target\",\"like\",\"%forbes%\"], \"and\", [[\"rank\",\">\",\"100\"],\"or\",[\"intersections\",\">\",\"5\"]]]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"limit":{"description":"the maximum number of returned domains
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"main_domain":{"description":"indicates if only main domain of the target will be included in the search
optional field
if set to true, only the main domain will be included in search;
default value: true","type":["boolean","null"]},"offset":{"description":"offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive pages","type":["integer","null"]},"order_by":{"description":"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:
[\"rank,desc\"]
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:
[\"intersections,desc\",\"rank,asc\"]","items":{"type":"string"},"type":["array","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain, subdomain or webpage to get competitor domains for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlink competitors","catalog":"web.backlinks.competitors"},{"name":"backlinks_bulk_backlinks_live","description":"‌\nThis endpoint will provide you with the number of backlinks pointing to domains, subdomains, and pages specified in the targets array. The returned numbers correspond to all live backlinks, that is, total number of referring links with all attributes (e.g., nofollow, noreferrer, ugc, sponsored etc) that were found during the latest check.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"targets":["forbes.com","cnn.com","bbc.com","yelp.com","https://www.apple.com/iphone/","https://ahrefs.com/blog/","ibm.com","https://variety.com/","https://stackoverflow.com/","www.trustpilot.com"]}]],"items":{"oneOf":[{"examples":[[{"targets":["forbes.com","cnn.com","bbc.com","yelp.com","https://www.apple.com/iphone/","https://ahrefs.com/blog/","ibm.com","https://variety.com/","https://stackoverflow.com/","www.trustpilot.com"]}]],"properties":{"tag":{"description":"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","type":["string","null"]},"targets":{"description":"domains, subdomains or webpages to get the number of backlinks for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`","items":{"type":"string"},"type":"array"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks bulk backlinks live"},{"name":"backlinks_bulk_new_lost_backlinks_live","description":"‌\nThis endpoint will provide you with the number of new and lost backlinks for the domains, subdomains, and pages specified in the targets array.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2026-09-26 08:39:25","targets":["forbes.com","cnn.com","bbc.com","yelp.com","https://www.apple.com/iphone/","https://ahrefs.com/blog/","ibm.com","https://variety.com/","https://stackoverflow.com/","www.trustpilot.com"]}]],"items":{"oneOf":[{"examples":[[{"date_from":"2026-09-26 08:39:25","targets":["forbes.com","cnn.com","bbc.com","yelp.com","https://www.apple.com/iphone/","https://ahrefs.com/blog/","ibm.com","https://variety.com/","https://stackoverflow.com/","www.trustpilot.com"]}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
this field indicates the date which will be used as a threshold for new and lost backlinks;
the backlinks that appeared in our index after the specified date will be considered as new;
the backlinks that weren't found after the specified date, but were present before, will be considered as lost;
default value: today's date -(minus) one month;
e.g. if today is 2021-10-13, default date_from will be 2021-09-13.
minimum value equals today's date -(minus) one year;
e.g. if today is 2021-10-13, minimum date_from will be 2020-10-13.
date format: \"yyyy-mm-dd\"
example:
\"2021-01-01\"","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"targets":{"description":"domains, subdomains or webpages to get new & lost backlinks for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without `https://` and `www.` the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`","items":{"type":"string"},"type":"array"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks bulk new lost backlinks live"},{"name":"backlinks_bulk_new_lost_referring_domains_live","description":"‌\nThis endpoint will provide you with the number of referring domains pointing to the domains, subdomains and pages specified in the targets array.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"datetime_from":"2026-39-26","targets":["forbes.com","cnn.com","bbc.com","yelp.com","https://www.apple.com/iphone/","https://ahrefs.com/blog/","ibm.com","https://variety.com/","https://stackoverflow.com/","www.trustpilot.com"]}]],"items":{"oneOf":[{"examples":[[{"datetime_from":"2026-39-26","targets":["forbes.com","cnn.com","bbc.com","yelp.com","https://www.apple.com/iphone/","https://ahrefs.com/blog/","ibm.com","https://variety.com/","https://stackoverflow.com/","www.trustpilot.com"]}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
this field indicates the date which will be used as a threshold for new and lost referring domains;
the referring domains that appeared in our index after the specified date will be considered as new;
the referring domains that weren't found after the specified date, but were present before, will be considered as lost;
default value: today's date -(minus) one month;
e.g. if today is 2021-10-13, default date_from will be 2021-09-13.
minimum value equals today's date -(minus) one year;
e.g. if today is 2021-10-13, minimum date_from will be 2020-10-13.
date format: \"yyyy-mm-dd\"
example:
\"2021-01-01\"","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"targets":{"description":"domains, subdomains or webpages to get new & lost referring domains for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`","items":{"type":"string"},"type":"array"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks bulk new lost referring domains live"},{"name":"backlinks_bulk_pages_summary_live","description":"This endpoint will provide you with a comprehensive overview of backlinks and related data for a bulk of up to 1000 pages, domains, or subdomains. If you indicate a single page as a target, you will get comprehensive summary data on all backlinks for that page.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"targets":["https://dataforseo.com/solutions","https://dataforseo.com/about-us"]}]],"items":{"oneOf":[{"examples":[[{"targets":["https://dataforseo.com/solutions","https://dataforseo.com/about-us"]}]],"properties":{"include_subdomains":{"description":"indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"targets":{"description":"domains, subdomains or webpages to get summary data for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)
you can specify up to 1000 pages, domains, or subdomains in each request.
note that the URLs you set in a single request cannot belong to more than 100 different domains.","items":{"type":"string"},"type":"array"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks bulk pages summary live"},{"name":"backlinks_bulk_referring_domains_live","description":"‌\nThis endpoint will provide you with the number of referring domains pointing to domains, subdomains, and pages specified in the targets array. The returned numbers are based on all live referring domains, that is, total number of domains pointing to the target with any type of backlinks (e.g., nofollow, noreferrer, ugc, sponsored etc) that were found during the latest check.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"targets":["forbes.com","cnn.com","bbc.com","yelp.com","https://www.apple.com/iphone/","https://ahrefs.com/blog/","ibm.com","https://variety.com/","https://stackoverflow.com/","www.trustpilot.com"]}]],"items":{"oneOf":[{"examples":[[{"targets":["forbes.com","cnn.com","bbc.com","yelp.com","https://www.apple.com/iphone/","https://ahrefs.com/blog/","ibm.com","https://variety.com/","https://stackoverflow.com/","www.trustpilot.com"]}]],"properties":{"tag":{"description":"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","type":["string","null"]},"targets":{"description":"domains, subdomains or webpages to get the number of referring domains for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`","items":{"type":"string"},"type":"array"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks bulk referring domains live"},{"name":"backlinks_bulk_spam_score_live","description":"‌\nThis endpoint will provide you with spam scores of the domains, subdomains, and pages you specified in the targets array. Spam Score is DataForSEO’s proprietary metric that indicates how “spammy” your target is on a scale from 0 to 100. You can learn more about Spam Score, how it is calculated, and signals it takes into account in this help center article","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"targets":["forbes.com","cnn.com","bbc.com","yelp.com","https://www.apple.com/iphone/","https://ahrefs.com/blog/","ibm.com","https://variety.com/","https://stackoverflow.com/","www.trustpilot.com"]}]],"items":{"oneOf":[{"examples":[[{"targets":["forbes.com","cnn.com","bbc.com","yelp.com","https://www.apple.com/iphone/","https://ahrefs.com/blog/","ibm.com","https://variety.com/","https://stackoverflow.com/","www.trustpilot.com"]}]],"properties":{"tag":{"description":"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","type":["string","null"]},"targets":{"description":"domains, subdomains or webpages to get rank for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`","items":{"type":"string"},"type":"array"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks bulk spam score live"},{"name":"backlinks_domain_intersection_live","description":"‌\nThis endpoint will provide you with the list of domains pointing to the specified websites. This endpoint is especially useful for creating a Link Gap feature that shows what domains link to your competitors but do not link out to your website.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"exclude_internal_backlinks":true,"exclude_targets":["semrush.com"],"include_subdomains":false,"limit":5,"order_by":["1.backlinks,desc"],"targets":{"1":"moz.com","2":"ahrefs.com"}}]],"items":{"oneOf":[{"examples":[[{"exclude_internal_backlinks":true,"exclude_targets":["semrush.com"],"include_subdomains":false,"limit":5,"order_by":["1.backlinks,desc"],"targets":{"1":"moz.com","2":"ahrefs.com"}}]],"properties":{"backlinks_filters":{"description":"filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:
\"backlinks_filters\": [[\"dofollow\", \"=\", true]]","items":{"type":["object","null"]},"type":["array","null"]},"backlinks_status_type":{"description":"set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your targets;
possible values:
all - all backlinks will be returned and counted;
live - backlinks found during the last check will be returned and counted;
lost - lost backlinks will be returned and counted;
default value: live","type":["string","null"]},"exclude_internal_backlinks":{"description":"indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be omitted and you won't receive the same domain in the response;
default value: true","type":["boolean","null"]},"exclude_targets":{"description":"domains, subdomains or webpages you want to exclude
optional field
you can specify up to 10 domains, subdomains or webpages
if you use this array, results will contain the referring domains that link to targets but don't link to exclude_targets
example:
`\"exclude_targets\": [
\"bbc.com\",
\"https://www.apple.com/iphone/*\",
\"https://dataforseo.com/apis/*\"]`","items":{"type":"string"},"type":["array","null"]},"filters":{"description":"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, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"1.internal_links_count\",\">\",\"1\"]
[[\"2.referring_pages\",\">\",\"2\"], \"and\", [\"1.backlinks\",\">\",\"10\"]]
[[\"1.first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"], \"and\", [[\"2.target\",\"like\",\"%dataforseo.com%\"],\"or\",[\"1.referring_domains\",\">\",\"10\"]]]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_indirect_links":{"description":"indicates if indirect links to the targets will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to a target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true","type":["boolean","null"]},"include_subdomains":{"description":"indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
referring_links_tld
referring_links_types
referring_links_attributes
referring_links_platform_types
referring_links_semantic_locations
default value: 10
maximum value: 1000","type":["integer","null"]},"intersection_mode":{"description":"indicates whether to intersect backlinks
optional field
use this field to intersect or merge results for the specified domains
possible values: all, partial
all - results are based on all backlinks;
partial - results are based on the intersecting backlinks only;
default value: all","type":["string","null"]},"limit":{"description":"the maximum number of returned results
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the array of returned results
optional field
default value: 0
if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks","type":["integer","null"]},"order_by":{"description":"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:
[\"backlinks,desc\"]
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:
[\"backlinks,desc\",\"rank,asc\"]","items":{"type":"string"},"type":["array","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"targets":{"additionalProperties":{"type":["string","null"]},"description":"domains, subdomains or webpages to get links for
required field
you can set up to 20 domains, subdomains or webpages
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": {
\"1\": \"http://planet.postgresql.org/\",
\"2\": \"http://gborg.postgresql.org/\"
}`","type":["object","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks domain intersection live"},{"name":"backlinks_domain_pages_live","description":"‌‌\nThis endpoint will provide you with a detailed overview of domain pages with backlink data for each page.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["page_summary.backlinks",">",5],"and",["page","like","%sites%"]],"limit":5,"target":"forbes.com"}]],"items":{"oneOf":[{"examples":[[{"filters":[["page_summary.backlinks",">",5],"and",["page","like","%sites%"]],"limit":5,"target":"forbes.com"}]],"properties":{"backlinks_filters":{"description":"filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:
\"backlinks_filters\": [\"dofollow\", \"=\", true]","items":{"type":["object","null"]},"type":["array","null"]},"backlinks_status_type":{"description":"set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics;
possible values:
all - all backlinks will be returned and counted;
live - backlinks found during the last check will be returned and counted;
lost - lost backlinks will be returned and counted;
default value: live","type":["string","null"]},"exclude_internal_backlinks":{"description":"indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true","type":["boolean","null"]},"filters":{"description":"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, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"meta.internal_links_count\",\">\",\"1\"]
[[\"meta.external_links_count\",\">\",\"2\"], \"and\", [\"backlinks\",\">\",\"10\"]]
[[\"first_visited\",\">\",\"2017-10-23 11:31:45 +00:00\"], \"and\", [[\"title\",\"like\",\"%seo%\"],\"or\",[\"referring_domains\",\">\",\"10\"]]]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_subdomains":{"description":"indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
referring_links_tld
referring_links_types
referring_links_attributes
referring_links_platform_types
referring_links_semantic_locations
default value: 10
maximum value: 1000","type":["integer","null"]},"limit":{"description":"the maximum number of returned pages
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned pages
optional field
default value: 0
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages","type":["integer","null"]},"order_by":{"description":"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:
[\"page_summary.backlinks,desc\"]
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:
[\"page_summary.backlinks,desc\",\"page_summary.rank,asc\"]","items":{"type":"string"},"type":["array","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain or subdomain
required field
a domain or a subdomain should be specified without https:// and www.
example:
forbes.com","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks domain pages live"},{"name":"backlinks_domain_pages_summary_live","description":"This endpoint will provide you with detailed summary data on all backlinks and related metrics for each page of the target domain or subdomain you specify. If you indicate a single page as a target, you will get comprehensive summary data on all backlinks for that page.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"limit":4,"order_by":["backlinks,desc"],"target":"forbes.com"}]],"items":{"oneOf":[{"examples":[[{"limit":4,"order_by":["backlinks,desc"],"target":"forbes.com"}]],"properties":{"backlinks_filters":{"description":"filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:
\"backlinks_filters\": [[\"dofollow\", \"=\", true]]","items":{"type":["object","null"]},"type":["array","null"]},"backlinks_status_type":{"description":"set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values:
all - all backlinks will be returned and counted;
live - backlinks found during the last check will be returned and counted;
lost - lost backlinks will be returned and counted;
default value: live","type":["string","null"]},"exclude_internal_backlinks":{"description":"indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, backlinks from the subdomains of the target domain will be ommited and you won't receive the same domain in the response;
default value: true","type":["boolean","null"]},"filters":{"description":"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, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"referring_links_types.anchors\",\">\",\"1\"]
[[\"broken_pages\",\">\",\"2\"], \"and\", [\"backlinks\",\">\",\"10\"]]
[[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"], \"and\", [[\"anchor\",\"like\",\"%seo%\"],\"or\",[\"referring_domains\",\">\",\"10\"]]]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_indirect_links":{"description":"indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true","type":["boolean","null"]},"include_subdomains":{"description":"indicates if the subdomains of the target domain will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
referring_links_tld
referring_links_types
referring_links_attributes
referring_links_platform_types
referring_links_semantic_locations
default value: 10
maximum value: 1000","type":["integer","null"]},"limit":{"description":"the maximum number of returned anchors
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned anchors
optional field
default value: 0
if you specify the 10 value, the first ten anchors in the results array will be omitted and the data will be provided for the successive anchors","type":["integer","null"]},"order_by":{"description":"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:
[\"backlinks,desc\"]
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:
[\"backlinks,desc\",\"rank,asc\"]","items":{"type":"string"},"type":["array","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain, subdomain or webpage to get summary data for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks domain pages summary live"},{"name":"backlinks_history_live","description":"‌\nThis endpoint will provide you with historical backlinks data back to the beginning of 2019. You can receive the number of backlinks a given domain had in a specific time period, the number of new & lost backlinks, referring domains, and more.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2020-01-01","date_to":"2021-01-01","target":"cnn.com"}]],"items":{"oneOf":[{"examples":[[{"date_from":"2020-01-01","date_to":"2021-01-01","target":"cnn.com"}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
minimum value 2019-01-01
if you don't specify this field, the minimum value will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain
required field
a domain should be specified without https:// and www.","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks history live"},{"name":"backlinks_index","description":"‌\nThis endpoint will provide you with the total number of backlinks, domains, and pages our database contains for the moment when you make a request. You will also get stats for the last 12 months.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks index"},{"name":"backlinks_list","description":"‌\nThis endpoint will provide you with a list of backlinks and relevant data for the specified domain, subdomain, or webpage.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":["dofollow","=",true],"limit":5,"mode":"as_is","target":"forbes.com"}]],"items":{"oneOf":[{"examples":[[{"filters":["dofollow","=",true],"limit":5,"mode":"as_is","target":"forbes.com"}]],"properties":{"backlinks_status_type":{"description":"set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values:
all - all backlinks will be returned and counted;
live - backlinks found during the last check will be returned and counted;
lost - lost backlinks will be returned and counted;
default value: live","type":["string","null"]},"custom_mode":{"additionalProperties":{"type":["object","null"]},"description":"detailed results grouping type
optional field
use this object to get a specific number of backlinks per field
if you use custom_mode, then mode will be ignored
example:
\"custom_mode\": {\"field\": \"domain\", \"value\": 100}","type":["object","null"]},"exclude_internal_backlinks":{"description":"indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true","type":["boolean","null"]},"filters":{"description":"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:
=, <>, in, not_in, like, not_like, ilike, not_ilike, regex, not_regex, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"rank\",\">\",\"80\"]
[[\"page_from_rank\",\">\",\"55\"], \"and\", [\"dofollow\",\"=\",true]]
[[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"], \"and\", [[\"anchor\",\"like\",\"%seo%\"],\"or\",[\"text_pre\",\"like\",\"%seo%\"]]]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_subdomains":{"description":"indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"limit":{"description":"the maximum number of returned backlinks
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"mode":{"description":"results grouping type
optional field
possible grouping types:
as_is - returns all backlinks
one_per_domain - returns one backlink per domain
one_per_anchor - returns one backlink per anchor
default value: as_is","type":["string","null"]},"offset":{"description":"offset in the results array of the returned backlinks
optional field
default value: 0
if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks;
Note: the maximum value is 20,000, use the search_after_token if you would like to offset more results","type":["integer","null"]},"order_by":{"description":"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:
[\"rank,desc\"]
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:
[\"domain_from_rank,desc\",\"page_from_rank,asc\"]","items":{"type":"string"},"type":["array","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"search_after_token":{"description":"token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request;
by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;
search_after_token values are unique for each subsequent task ;
Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain, subdomain or webpage to get backlinks for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks list","catalog":"web.backlinks.list"},{"name":"backlinks_page_intersection_live","description":"‌\nThis endpoint will provide you with the list of referring pages pointing to the specified targets. It is especially useful for finding the backlinks that point to your competitors but don’t point to your website.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"exclude_targets":["skysports.com"],"filters":[["2.domain_from_rank",">",400],"and",["1.dofollow","=",true]],"limit":5,"order_by":["1.rank,desc"],"targets":{"1":"football.com","2":"fifa.com"}}]],"items":{"oneOf":[{"examples":[[{"exclude_targets":["skysports.com"],"filters":[["2.domain_from_rank",">",400],"and",["1.dofollow","=",true]],"limit":5,"order_by":["1.rank,desc"],"targets":{"1":"football.com","2":"fifa.com"}}]],"properties":{"backlinks_status_type":{"description":"set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your targets;
possible values:
all - all backlinks will be returned and counted;
live - backlinks found during the last check will be returned and counted;
lost - lost backlinks will be returned and counted;
default value: live","type":["string","null"]},"exclude_internal_backlinks":{"description":"indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the result
default value: true","type":["boolean","null"]},"exclude_targets":{"description":"domains, subdomains or webpages you want to exclude
optional field
you can set up to 10 domains, subdomains or webpages
if you use this array, results will contain the referring pages that link to targets but don't link to exclude_targets
example:
`\"exclude_targets\": [
\"bbc.com\",
\"https://www.apple.com/iphone/*\",
\"https://dataforseo.com/apis/*\"]`","items":{"type":"string"},"type":["array","null"]},"filters":{"description":"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, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"1.rank\",\">\",\"80\"]
[[\"2.page_from_rank\",\">\",\"55\"], \"and\", [\"1.original\",\"=\",\"true\"]]
[[\"1.first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"], \"and\", [[\"1.acnhor\",\"like\",\"%seo%\"],\"or\",[\"1.text_pre\",\"not_like\",\"%seo%\"]]]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_indirect_links":{"description":"indicates if indirect links to the targets will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to a target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true","type":["boolean","null"]},"include_subdomains":{"description":"indicates if the subdomains of the targets will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
attributes
domain_from_platform_type
default value: 10
maximum value: 1000","type":["integer","null"]},"intersection_mode":{"description":"indicates whether to intersect backlinks
optional field
use this field to intersect or merge results for the specified URLs
possible values: all, partial
all - results are based on all backlinks;
partial - results are based on the intersecting backlinks only;
default value: all","type":["string","null"]},"limit":{"description":"the maximum number of returned backlinks
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of the returned backlinks
optional field
default value: 0
if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks","type":["integer","null"]},"order_by":{"description":"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:
[\"rank,desc\"]
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:
[\"domain_from_rank,desc\",\"page_from_rank,asc\"]","items":{"type":"string"},"type":["array","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"targets":{"additionalProperties":{"type":["string","null"]},"description":"domains, subdomains or webpages to get links for
required field
you can set up to 20 domains, subdomains or webpages
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": {
\"1\": \"http://planet.postgresql.org/\",
\"2\": \"http://gborg.postgresql.org/\"
}`","type":["object","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks page intersection live"},{"name":"backlinks_referring_networks_live","description":"‌‌\nThis endpoint will provide you with a detailed overview of referring IPs and subnets pointing to the target you specify.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"backlinks_filters":["dofollow","=",true],"exclude_internal_backlinks":true,"filters":["backlinks",">",100],"limit":5,"network_address_type":"subnet","order_by":["rank,desc"],"target":"backlinko.com"}]],"items":{"oneOf":[{"examples":[[{"backlinks_filters":["dofollow","=",true],"exclude_internal_backlinks":true,"filters":["backlinks",">",100],"limit":5,"network_address_type":"subnet","order_by":["rank,desc"],"target":"backlinko.com"}]],"properties":{"backlinks_filters":{"description":"filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:
\"backlinks_filters\": [[\"dofollow\", \"=\", true]]","items":{"type":["object","null"]},"type":["array","null"]},"backlinks_status_type":{"description":"set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values:
all - all backlinks will be returned and counted;
live - backlinks found during the last check will be returned and counted;
lost - lost backlinks will be returned and counted;
default value: live","type":["string","null"]},"exclude_internal_backlinks":{"description":"indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be ommited and you won't receive the same domain in the response;
default value: true","type":["boolean","null"]},"filters":{"description":"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, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"referring_pages\",\">\",\"1\"]
[[\"referring_pages\",\">\",\"2\"], \"and\", [\"backlinks\",\">\",\"10\"]]
[[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"], \"and\", [[\"network_address\",\"like\",\"194.1.%\"],\"or\",[\"referring_ips\",\">\",\"10\"]]]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_indirect_links":{"description":"indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true","type":["boolean","null"]},"include_subdomains":{"description":"indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
referring_links_tld
referring_links_types
referring_links_attributes
referring_links_platform_types
referring_links_semantic_locations
default value: 10
maximum value: 1000","type":["integer","null"]},"limit":{"description":"the maximum number of returned networks
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"network_address_type":{"description":"indicates the type of network to get data for
optional field
possible values: ip, subnet
default value: ip","type":["string","null"]},"offset":{"description":"offset in the results array of returned networks
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive pages","type":["integer","null"]},"order_by":{"description":"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:
[\"backlinks,desc\"]
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:
[\"backlinks,desc\",\"rank,asc\"]","items":{"type":"string"},"type":["array","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain, subdomain or webpage to get referring networks for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks referring networks live"},{"name":"backlinks_summary","description":"‌\nThis endpoint will provide you with an overview of backlinks data available for a given domain, subdomain, or webpage.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"backlinks_filters":["dofollow","=",true],"backlinks_status_type":"all","include_subdomains":true,"internal_list_limit":10,"target":"explodingtopics.com"}]],"items":{"oneOf":[{"examples":[[{"backlinks_filters":["dofollow","=",true],"backlinks_status_type":"all","include_subdomains":true,"internal_list_limit":10,"target":"explodingtopics.com"}]],"properties":{"backlinks_filters":{"description":"filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:
\"backlinks_filters\": [\"dofollow\", \"=\", true]","items":{"type":["object","null"]},"type":["array","null"]},"backlinks_status_type":{"description":"set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values:
all - all backlinks will be returned and counted;
live - backlinks found during the last check will be returned and counted;
lost - lost backlinks will be returned and counted;
default value: live","type":["string","null"]},"exclude_internal_backlinks":{"description":"indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true","type":["boolean","null"]},"include_indirect_links":{"description":"indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true","type":["boolean","null"]},"include_subdomains":{"description":"indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
referring_links_tld
referring_links_types
referring_links_attributes
referring_links_platform_types
referring_links_semantic_locations
default value: 10
maximum value: 1000","type":["integer","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain, subdomain or webpage to get data for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks summary","catalog":"web.backlinks.summary"},{"name":"backlinks_timeseries_new_lost_summary_live","description":"‌\nThis endpoint will provide you with the number of new and lost backlinks and referring domains for the domain specified in the target field.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2021-12-01","date_to":"2022-02-01","group_range":"month","target":"dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"date_from":"2021-12-01","date_to":"2022-02-01","group_range":"month","target":"dataforseo.com"}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
this field indicates the date which will be used as a threshold for new and lost backlinks and referring domains;
the backlinks and referring domains that appeared in our index after the specified date will be considered as new;
the backlinks and referring domains that weren't found after the specified date, but were present before, will be considered as lost;
minimum value: 2019-01-30
maximum value shouldn't exceed the date specified in the date_to
date format: \"yyyy-mm-dd\"
example:
\"2021-01-01\"","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
minimum value shouldn't preceed the date specified in the date_from
maximum value: today's date
date format: \"yyyy-mm-dd\"
example:
\"2021-01-15\"","type":["string","null"]},"group_range":{"description":"time range which will be used to group the results
optional field
default value: month
possible values: day, week, month, year
note: for day, we will return items corresponding to all dates between and including date_from and date_to;
for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year
for example, if you specify:
\"group_range\": \"month\", \"date_from\": \"2022-03-23\", \"date_to\": \"2022-05-13\"
we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31
if there is no data for a certain day/week/month/year, we will return 0","type":["string","null"]},"include_subdomains":{"description":"indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain to get data for
required field
a domain should be specified without https:// and www.
example:
\"forbes.com\"","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks timeseries new lost summary live"},{"name":"backlinks_timeseries_summary_live","description":"‌\nThis endpoint will provide you with an overview of backlink data for the target domain available during a period between the two indicated dates. Backlink metrics will be grouped by the time range that you define: day, week, month, or year.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2021-12-01","date_to":"2022-02-01","group_range":"month","target":"dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"date_from":"2021-12-01","date_to":"2022-02-01","group_range":"month","target":"dataforseo.com"}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
this field indicates the date which will be used as a threshold for summary data;
minimum value: 2019-01-30
maximum value shouldn't exceed the date specified in the date_to
date format: \"yyyy-mm-dd\"
example:
\"2021-01-01\"","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
minimum value shouldn't preceed the date specified in the date_from
maximum value: today's date
date format: \"yyyy-mm-dd\"
example:
\"2021-01-15\"","type":["string","null"]},"group_range":{"description":"time range which will be used to group the results
optional field
default value: month
possible values: day, week, month, year
note: for day, we will return items corresponding to all dates between and including date_from and date_to;
for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year
for example, if you specify:
\"group_range\": \"month\", \"date_from\": \"2022-03-23\", \"date_to\": \"2022-05-13\"
we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31
if there is no data for a certain day/week/month/year, we will return 0","type":["string","null"]},"include_subdomains":{"description":"indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain to get data for
required field
a domain should be specified without https:// and www.
example:
\"forbes.com\"","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Backlinks timeseries summary live"},{"name":"business_data_business_listings_categories_aggregation_live","description":"‌‌\nBusiness Listings Categories Aggregation endpoint provides results containing information about groups of related categories along with the number of entities in each category. The provided results are specific to the specified parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"categories":["pizza_restaurant"],"description":"pizza","initial_dataset_filters":[["rating.value",">",3]],"is_claimed":true,"limit":3,"location_coordinate":"53.476225,-2.243572,10","title":"pizza"}]],"items":{"oneOf":[{"examples":[[{"categories":["pizza_restaurant"],"description":"pizza","initial_dataset_filters":[["rating.value",">",3]],"is_claimed":true,"limit":3,"location_coordinate":"53.476225,-2.243572,10","title":"pizza"}]],"properties":{"categories":{"description":"business categories
optional field
the categories you specify are used to search for business listings;
if you don't use this field, we will return business listings found in the specified location;
you can specify up to 10 categories","items":{"type":"string"},"type":["array","null"]},"description":{"description":"description of the element in SERP
optional field
the description of the business entity for which the results are collected;
can contain up to 200 characters","type":["string","null"]},"initial_dataset_filters":{"description":"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, like, not_like, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"rating.value\",\">\",3]
you can receive the list of available filters_by making a separate request to https://api.dataforseo.com/v3/business_data/business_listings/available_filters
the full list of possible filters is available here.
learn more about the initial dataset filters in this help center article.n","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the aggregated categories
default value: 10","type":["integer","null"]},"is_claimed":{"description":"indicates whether the business is verified by its owner on Google Maps
optional field","type":["boolean","null"]},"limit":{"description":"the maximum number of returned businesses
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_coordinate":{"description":"GPS coordinates of a location
optional field
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 1
the maximum value for \"radius\": 100000
example:
53.476225,-2.243572,200
learn more about how to set location parameters in this API on our Help Center","type":["string","null"]},"offset":{"description":"the maximum number of returned businesses
optional field","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]},"title":{"description":"title of the element in SERP
optional field
the name of the business entity for which the results are collected;
can contain up to 200 characters","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data business listings categories aggregation live"},{"name":"business_data_business_listings_search_live","description":"‌‌\nBusiness Listings Search API provides results containing information about business entities listed on Google Maps in the specified categories. You will receive the address, contacts, rating, working hours, and other relevant data. The provided results are specific to the selected location (see the List of Locations) settings.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"categories":["pizza_restaurant"],"description":"pizza","filters":[["rating.value",">",3]],"is_claimed":true,"limit":3,"location_coordinate":"53.476225,-2.243572,10","order_by":["rating.value,desc"],"title":"pizza"}]],"items":{"oneOf":[{"examples":[[{"categories":["pizza_restaurant"],"description":"pizza","filters":[["rating.value",">",3]],"is_claimed":true,"limit":3,"location_coordinate":"53.476225,-2.243572,10","order_by":["rating.value,desc"],"title":"pizza"}]],"properties":{"categories":{"description":"business categories
optional field
the categories you specify are used to search for business listings;
if you don't use this field, we will return business listings found in the specified location;
you can specify up to 10 categories","items":{"type":"string"},"type":["array","null"]},"description":{"description":"description of the element in SERP
optional field
the description of the business entity for which the results are collected;
can contain up to 200 characters","type":["string","null"]},"filters":{"description":"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, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"rating.value\",\">\",3]
you can receive the list of available filters_by making a separate request to https://api.dataforseo.com/v3/business_data/business_listings/available_filters
The full list of possible filters is available here.n","items":{"type":["object","null"]},"type":["array","null"]},"is_claimed":{"description":"indicates whether the business is verified by its owner on Google Maps
optional field","type":["boolean","null"]},"limit":{"description":"the maximum number of returned businesses
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_coordinate":{"description":"GPS coordinates of a location
optional field
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the value of \"radius\" is specified in kilometres (km)
the minimum value for \"radius\": 1
the maximum value for \"radius\": 100000
example:
53.476225,-2.243572,200
learn more about how to set location parameters in this API on our Help Center","type":["string","null"]},"offset":{"description":"offset in the results array of returned businesses
optional field
default value: 0
if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead","type":["integer","null"]},"offset_token":{"description":"token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;
offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center","type":["string","null"]},"order_by":{"description":"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 parameter
example:
[\"rating.value,desc\"]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:
[\"rating.value,desc\",\"rating.votes_count,desc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"title":{"description":"title of the element in SERP
optional field
the name of the business entity for which the results are collected;
can contain up to 200 characters","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data business listings search live"},{"name":"business_data_google_extended_reviews_task_get_id","description":"The returned results are specific to the indicated local establishment name, search engine, location and language parameters. We emulate set location and search engine with the highest accuracy so that the results you receive will match the actual search results for the specified parameters at the time of task setting. You can always check the returned results accessing the check_url in the Incognito mode to make sure the received data is entirely relevant. Note that user preferences, search history, and other personalized search factors are ignored by our system and thus would not be reflected in the returned results.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data google extended reviews task get id"},{"name":"business_data_google_extended_reviews_task_post","description":"‌‌\nThis endpoint provides results from the “Reviews” element of Google SERPs, including not only Google user reviews but also reviews from other reputable sources (e.g., TripAdvisor, Yelp, Trustpilot). The results are specific to the selected location (see the List of Locations) and language (see the List of Languages) parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"cid":"17626775537598922320","language_name":"english","location_name":"London,England,United Kingdom"}]],"items":{"oneOf":[{"examples":[[{"cid":"17626775537598922320","language_name":"english","location_name":"London,England,United Kingdom"}]],"properties":{"cid":{"description":"unique, google-defined id of the business entity
required field if you don't specify keyword or place_id
example:
194604053573767737
learn more about the identifier in this help center article
Note: if you use this field, your account will be charged two times the standard rate for tasks involving the Google Reviews API","type":"string"},"depth":{"description":"parsing depth
optional field
number of reviews in SERP
we strongly recommend setting the parsing depth in the multiples of twenty, because our systems processes twenty reviews in a row
default value: 20
maximum value: 1000
Your account will be billed per each SERP containing up to 20 results;
Setting depth above 20 may result in additional charges if the search engine returns more than 20 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"keyword":{"description":"keyword
required field if you don't specify cid or place_id
the keyword you specify should indicate the name of the local establishment;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;

if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’, the charge per task will be multiplied by 5
Note: queries containing the ‘cache:’ parameter are not supported and will return a validation error
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
Note: if you use this field, your account will be charged three times the standard rate for tasks involving the Google Reviews API","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
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/business_data/google/languages
example:
enn","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:
2840n","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:
53.476225,-2.243572,200n","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:
London,England,United Kingdom","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"place_id":{"description":"identifier of the business entity in Google Maps
required field if you don't specify keyword or cid
example:
GhIJQWDl0CIeQUARxks3icF8U8A
learn more about the identifier in this help center article
Note: if you use this field, your account will be charged two times the standard rate for tasks involving the Google Reviews API","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data google extended reviews task post"},{"name":"business_data_google_hotel_info_live_advanced","description":"‌‌\nGoogle Hotel Info will provide you with structured data available for a specific hotel entity on the Google Hotels platform: such as service description, location details, rating, amenities, reviews, images, prices, and more.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"hotel_identifier":"CgoI-KWyzenM_MV3EAE","language_code":"en","location_name":"New York,New York,United States"}]],"items":{"oneOf":[{"examples":[[{"hotel_identifier":"CgoI-KWyzenM_MV3EAE","language_code":"en","location_name":"New York,New York,United States"}]],"properties":{"adults":{"description":"number of adults
optional field
if you don't specify this field, two adults will be used by default
example:
1","type":["integer","null"]},"check_in":{"description":"check-in date
optional field
if you don't specify this field, tomorrow's date will be used by default;
the value must not be earlier than today's date
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"check_out":{"description":"check-out date
optional field
if you don't specify this field, our system will apply the date of two days from now by default;
Note: the value cannot be less than or equal to check_in;
the range between check_in and check_out values cannot exceed 30 days
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"children":{"description":"number and age of children
optional field
if you don't specify this field, no children will be included in the search;
set the following value if you want to include one 14-years-old child:
[14]
set the following value if you want to include one 13-years-old child and one 8-years-old child:
[13,8]","items":{"type":"string"},"type":["array","null"]},"currency":{"description":"currency
optional field
example:
\"USD\"","type":["string","null"]},"hotel_identifier":{"description":"unique hotel identifier
required field
unique identifier of a hotel entity in Google search;
you can obtain the value by making a request to Advanced Google SERP API (enclosed in the hotels element of the response), or the Hotel Searches endpoint of Business Data API
example:
ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
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 https://api.dataforseo.com/v3/business_data/google/languages
example:
enn","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:
English","type":"string"},"load_prices_by_dates":{"description":"load hotel stay prices by dates
optional field
if you specify this parameter with true, the response will include the prices_by_dates array with hotel stay prices divided by dates
if you use this parameter, you will be charged double the base price for a request","type":["boolean","null"]},"location_code":{"description":"search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:
2840n","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude, longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
Note: if the coordinates are used to set a location, the search will occur in the nearest settlement;
example:
53.476225,-2.243572n","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:
London,England,United Kingdom","type":"string"},"prices_date_range":{"description":"predefined period for retrieving daily price data
optional field
to use this parameter, you must specify load_prices_by_dates with true
if the prices_start_date is not specified, the start date is set to check_in date
possible values: month, three_months, six_months, year
default value: month","type":["string","null"]},"prices_end_date":{"description":"end date to load prices by dates
optional field
to use this parameter, you must specify load_prices_by_dates with true
if this parameter is not specified, you will get prices by date for the month
date format: yyyy-mm-dd
example:
2025-05-21","type":["string","null"]},"prices_start_date":{"description":"start date to load prices by dates
optional field
to use this parameter, you must specify load_prices_by_dates with true
if this parameter is not specified, the start date is set to check_in date
date format: yyyy-mm-dd
example:
2025-05-20","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data google hotel info live advanced"},{"name":"business_data_google_hotel_searches_live","description":"‌‌\nHotel Searches API provides results containing information about different hotels listed on Google Hotels. The provided results are specific to the selected location (see the List of Locations) and language (see the List of Languages) settings.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"adults":2,"check_in":"2023-06-01","check_out":"2023-06-30","children":["14"],"currency":"USD","keyword":"cheap hotel","language_code":"en","location_name":"New York,New York,United States","priority":2,"sort_by":"highest_rating","tag":"example"}]],"items":{"oneOf":[{"examples":[[{"adults":2,"check_in":"2023-06-01","check_out":"2023-06-30","children":["14"],"currency":"USD","keyword":"cheap hotel","language_code":"en","location_name":"New York,New York,United States","priority":2,"sort_by":"highest_rating","tag":"example"}]],"properties":{"adults":{"description":"number of adults
optional field
if you don't specify this field, the default value of 2 will be applied;
note that you can specify up to 6 persons including both adults and children
example:
1","type":["integer","null"]},"amenities":{"description":"hotel amenities
optional field
you can use this field to specify different hotel amenities
example:
[ \"free_parking\", \"pets_allowed\" ]
possible values:
`\"air_conditioning\",
\"all_inclusive_available\",
\"bar\",
\"free_breakfast\",
\"fitness_center\",
\"kid_friendly\",
\"free_parking\",
\"pets_allowed\",
\"pool\",
\"restaurant\",
\"room_service\",
\"spa\",
\"free_wifi\",
\"parking\",
\"indoor_pool\",
\"outdoor_pool\",
\"wheelchair_accessible\",
\"beach_access\"`","items":{"type":"string"},"type":["array","null"]},"check_in":{"description":"check-in date
optional field
if you don't specify this field, tomorrow's date will be used by default;
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"
Note: the value cannot precede the today's date","type":["string","null"]},"check_out":{"description":"check-out date
optional field
if you don't specify this field, our system will apply the date of two days from now by default;
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"
Note: the value cannot be less than or equal to check_in;
the range between check_in and check_out values cannot exceed 30 days","type":["string","null"]},"children":{"description":"number and age of children
optional field
if you don't specify this field, no children will be included in the search;
age of child can be from 0 to 17;
note that you can specify up to 6 persons including both adults and children
set the following value if you want to include one 14-year-old child:
[14]
set the following value if you want to include one 13-year-old child and one 8-year-old child:
[13,8]","items":{"type":"string"},"type":["array","null"]},"currency":{"description":"currency
optional field
example:
\"USD\"","type":["string","null"]},"depth":{"description":"parsing depth
optional field
number of results in Google Hotels
default value: 18 organic results
max value: 140
Note: your account will be billed per each 18 organic results regardless of paid listings in the response;
thus, setting a depth above 18 may result in additional charges if Google Hotels return more than 18 results;
if the specified depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance","type":["integer","null"]},"free_cancellation":{"description":"hotels with a free cancellation
optional field
set this field to true if you want to get the list of hotels with free cancellation of reservations
default value: false","type":["boolean","null"]},"is_vacation_rentals":{"description":"search for vacation rentals
optional field
set this field to true if you want to get the list of vacation rentals instead of hotels
default value: false","type":["boolean","null"]},"keyword":{"description":"keyword
optional field
the keyword you specify is used to search for the list of hotels;
if you don't use this field, we will return the list of hotels found in a specified location;
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
Note: in order to obtain accurate search results, the location name is appended to the keyword automatically
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":["string","null"]},"language_code":{"description":"search engine language code
required field if you don't specify language_name
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 https://api.dataforseo.com/v3/business_data/google/languages
example:
enn","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:
2840n","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
Note: if the coordinates are used to set a location, the search will occur in the nearest settlement
example:
53.476225,-2.243572n","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:
London,England,United Kingdom
Note: in order to obtain accurate search results, the location_name you specify will be automatically appended to the keyword","type":"string"},"max_price":{"description":"maximum price per night
optional field
the currency of this value depends on the currency field
example:
600","type":["integer","null"]},"min_price":{"description":"minimum price per night
optional field
the currency of this value depends on the currency field
example:
100","type":["integer","null"]},"min_rating":{"description":"minimum rating
optional field
you can use this field to specify guest rating higher than a certain value
example:
2.5","type":["number","null"]},"search_this_area":{"description":"show hotels from the displayed area
optional field
can take the values: true, false
default value: true
if set to false the search_this_area mode will be turned off
Note: if the search_this_area mode is turned off, the location_name won't be appended to the keyword during search
learn more about this parameter on our Help Center","type":["boolean","null"]},"sort_by":{"description":"results sorting parameters
optional field
you can use this field to sort the results
possible types of sorting:
relevance – sort by most relevant
lowest_price – sort by the lowest price
highest_rating – sort by highest rating
most_reviewed – sort by most reviewed
default value: relevance","type":["string","null"]},"stars":{"description":"hotel stars
optional field
set this field to [5] if you want to get the list of 5-star hotels only
example:
[3,4,5]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data google hotel searches live"},{"name":"business_data_google_locations_country","description":"You will receive the list of locations by this API call. You can filter the list of locations by country when setting a task.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data google locations country"},{"name":"business_data_google_my_business_info_live","description":"‌‌\nBusiness Data API provides results containing information about specific business entity from Google. The provided results are specific to the selected location (see the List of Locations) and language (see the List of Languages) settings.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"RustyBrick, Inc.","language_code":"en","location_name":"New York,New York,United States"}]],"items":{"oneOf":[{"examples":[[{"keyword":"RustyBrick, Inc.","language_code":"en","location_name":"New York,New York,United States"}]],"properties":{"keyword":{"description":"keyword
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
this field can also be used to pass the following parameters:
cid - a unique, google-defined id of the business entity;
place_id - an identifier of the business entity in Google Maps;
example:
cid:194604053573767737
place_id:GhIJQWDl0CIeQUARxks3icF8U8A
learn more about the cid and place_id identifiers in this help center article
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
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 https://api.dataforseo.com/v3/business_data/google/languages
example:
enn","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:
2840n","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:
53.476225,-2.243572,200n","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:
London,England,United Kingdom","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data google my business info live"},{"name":"business_data_google_my_business_updates_task_get_id","description":"GET /v3/business_data/google/my_business_updates/task_get/{id}","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data google my business updates task get id"},{"name":"business_data_google_my_business_updates_task_post","description":"‌‌\nThis endpoints provides the latest updates of a specific business entity from Google SERP. The provided results are specific to the selected location (see the List of Locations) and language (see the List of Languages) settings.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"RustyBrick, Inc.","language_code":"en","location_name":"New York,New York,United States"}]],"items":{"oneOf":[{"examples":[[{"keyword":"RustyBrick, Inc.","language_code":"en","location_name":"New York,New York,United States"}]],"properties":{"depth":{"description":"parsing depth
optional field
number of updates in SERP
we strongly recommend setting the parsing depth in the multiples of ten, because our systems processes ten updates in a row
please note that Google returns 4490 updates maximum
default value: 10","type":["integer","null"]},"keyword":{"description":"keyword
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;this field can also be used to pass cid (unique, google-defined id of the business entity) or place_id (identifier of the business entity in Google Maps) parameters
example:
cid:194604053573767737
place_id:GhIJQWDl0CIeQUARxks3icF8U8A
learn more about the cid and place_id identifiers in this help center article","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
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/business_data/google/languages
example:
enn","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:
2840n","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:
53.476225,-2.243572,200n","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:
London,England,United Kingdom","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data google my business updates task post"},{"name":"business_data_google_questions_and_answers_live","description":"‌‌\nThis endpoint will provide you with a detailed overview of questions and answers associated with a specific business entity listed on Google My Business. By submitting a request to this endpoint, you can access comprehensive data on the inquiries and responses related to a particular business, including the full text of the questions and answers, as well as metadata such as timestamps, user information.\n \nThe provided results are specific to the selected location (see the List of Locations) and language (see the List of Languages) settings.\n \nYour account will be billed for every 20 questions, the maximum number of answers returned for each question is 5.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"The Last Bookstore","language_code":"en","location_name":"Los Angeles,California,United States"}]],"items":{"oneOf":[{"examples":[[{"keyword":"The Last Bookstore","language_code":"en","location_name":"Los Angeles,California,United States"}]],"properties":{"depth":{"description":"parsing depth
optional field
number of results in SERP
default value: 20
max value: 100
Your account will be billed per each SERP containing up to 20 results;
Setting depth above 20 may result in additional charges if the search engine returns more than 20 results;
If the specified depth is higher than the number of questions in the response, the difference will be refunded automatically to your account balance;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"keyword":{"description":"keyword
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
this field can also be used to pass the following parameters:
cid - a unique, google-defined id of the business entity;
place_id - an identifier of the business entity in Google Maps;
example:
cid:194604053573767737
place_id:GhIJQWDl0CIeQUARxks3icF8U8A
learn more about the cid and place_id identifiers in this help center article
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
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 https://api.dataforseo.com/v3/business_data/google/languages
example:
enn","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:
2840n","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:
53.476225,-2.243572,200n","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:
London,England,United Kingdom","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data google questions and answers live"},{"name":"business_data_google_reviews_task_get_id","description":"The returned results are specific to the indicated local establishment name, search engine, location and language parameters. We emulate set location and search engine with the highest accuracy so that the results you receive will match the actual search results for the specified parameters at the time of task setting. You can always check the returned results accessing the check_url in the Incognito mode to make sure the received data is entirely relevant. Note that user preferences, search history, and other personalized search factors are ignored by our system and thus would not be reflected in the returned results.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data google reviews task get id"},{"name":"business_data_google_reviews_task_post","description":"‌‌\nThis endpoint provides results from the “Reviews” element of Google SERPs. The results are specific to the selected location (see the List of Locations) and language (see the List of Languages) parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"depth":50,"keyword":"hedonism wines","language_name":"English","location_name":"London,England,United Kingdom","sort_by":"highest_rating"}]],"items":{"oneOf":[{"examples":[[{"depth":50,"keyword":"hedonism wines","language_name":"English","location_name":"London,England,United Kingdom","sort_by":"highest_rating"}]],"properties":{"cid":{"description":"unique, google-defined id of the business entity
required field if you don't specify keyword or place_id
example:
194604053573767737
learn more about the identifier in this help center article","type":"string"},"depth":{"description":"parsing depth
optional field
number of reviews in SERP
we strongly recommend setting the parsing depth in the multiples of ten, because our systems processes ten reviews in a row
default value: 10
maximum value: 4490
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"keyword":{"description":"keyword
required field if you don't specify cid or place_id
the keyword you specify should indicate the name of the local establishment;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;

if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’, the charge per task will be multiplied by 5
Note: queries containing the ‘cache:’ parameter are not supported and will return a validation error
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
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/business_data/google/languages
example:
en","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:
2840","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:
53.476225,-2.243572,200","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:
London,England,United Kingdom","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"place_id":{"description":"identifier of the business entity in Google Maps
required field if you don't specify keyword or cid
example:
GhIJQWDl0CIeQUARxks3icF8U8A
learn more about the identifier in this help center article","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"sort_by":{"description":"results sorting parameters
optional field
you can use this field to sort the results
possible types of sorting:
newest – sort by newest first
highest_rating – sort by highest rating
lowest_rating – sort by lowest rating
relevant – sort by relevance
default value: relevant","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data google reviews task post"},{"name":"business_data_tripadvisor_locations_country","description":"You will receive the list of locations by this API call. You can filter the list of locations by country when setting a task. Note that supported location types in Tripadvisor Business Data API are City and Region only.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data tripadvisor locations country"},{"name":"business_data_tripadvisor_reviews_task_get_id","description":"This endpoint provides feedback data on businesses listed on the Tripadvisor platform, including their locations, ratings, review content and count. The results are specific to the URL path indicated in the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data tripadvisor reviews task get id"},{"name":"business_data_tripadvisor_reviews_task_post","description":"‌‌\nThis endpoint provides results from the “Reviews” element on the Tripadvisor platform. The results are specific to the URL path or keyword you indicate, and and the selected location (see the List of Locations).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"location_code":1003854,"pingback_url":"https://your-server.com/pingback.php?id=$id&tag=$tag","tag":"some_string_123","url_path":"Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html"}]],"items":{"oneOf":[{"examples":[[{"location_code":1003854,"pingback_url":"https://your-server.com/pingback.php?id=$id&tag=$tag","tag":"some_string_123","url_path":"Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html"}]],"properties":{"depth":{"description":"parsing depth
optional field
number of reviews in SERP;
we strongly recommend setting the parsing depth in the multiples of ten, because our systems processes ten reviews in a row;
default value: 10;
max value: 4490
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"keyword":{"description":"keyword
required field if you do not specify url_path
the keyword you specify should indicate a name of an existing business or prominent place on Tripadvisor;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”","type":"string"},"language_code":{"description":"search engine language code
optional field
if you use this field, your account will be charged for one extra request
you can receive the list of available languages with language_code by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/languages
example:
en
You will be additionally charged for setting a language parameter in this endpoint.
The cost can be calculated on the Pricing page.","type":["string","null"]},"language_name":{"description":"full name of search engine language
optional field
if you use this field, your account will be charged for one extra request
you can receive the list of available languages with language_name by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/languages
example:
English
You will be additionally charged for setting a language parameter in this endpoint.
The cost can be calculated on the Pricing page.","type":["string","null"]},"location_code":{"description":"search engine location code
required field if you don't specify location_name or url_path
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/locations
example:
1003854","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or url_path
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/locations
example:
London,England,United Kingdom","type":"string"},"months":{"description":"filter by months when a traveler made a visit
optional field
possible values: january, february, march, april, may, april, june, july, august, september, october, november, december
you can specify several values at once","items":{"type":"string"},"type":["array","null"]},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"ratings":{"description":"Tripadvisor traveler rating for a place of interest
optional field
rating based on the written reviews by a traveler after they visited a place.
possible values: excellent, very_good, average, poor, terrible
you can specify several values at once","items":{"type":"string"},"type":["array","null"]},"sort_by":{"description":"results sorting parameters
optional field
you can use this field to sort the results;
possible types of sorting:
most_recent
detailed_reviews","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"translate_reviews":{"description":"translate reviews according to the URL path
optional field
if set to true, returned reviews will be translated to the language matching the specified url_path;
for example, if url_path contains tripadvisor.it and translate_reviews is true, reviews will be translated to the Italian language;
default value: true
you can learn more about how reviews are translated in this Help Center article","type":["boolean","null"]},"url_path":{"description":"URL path of the business entity
required field if you do not specify keyword
URL path to the Tripadvisor page of the business entity;
examples:
Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html
https://www.tripadvisor.com/Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html","type":"string"},"visit_type":{"description":"filter by type of travelers who left a review
optional field
possible values: families, couples, solo, business, friends
you can specify several values at once","items":{"type":"string"},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data tripadvisor reviews task post"},{"name":"business_data_tripadvisor_search_task_get_id","description":"This endpoint will provide you with data on businesses listed on the Tripadvisor platform. The results obtained through this endpoint are specific to the location (see the List of Tripadvisor Locations) and keyword parameters used in the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data tripadvisor search task get id"},{"name":"business_data_tripadvisor_search_task_post","description":"‌‌\nThis endpoint provides a list of business profiles listed on the Tripadvisor platform. The returned results are relevant to the specified keyword and the selected location (see the List of Locations).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"depth":30,"keyword":"pizza","location_code":1003854}]],"items":{"oneOf":[{"examples":[[{"depth":30,"keyword":"pizza","location_code":1003854}]],"properties":{"depth":{"description":"parsing depth
optional field
number of search results to be returned from the API response
we strongly recommend setting the parsing depth in the multiples of thirty because our systems processes thirty search results in a row;
default value: 30;
maximum value: 210
Your account will be billed per each SERP containing up to 30 results;
Setting depth above 30 may result in additional charges if the search engine returns more than 30 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"keyword":{"description":"keyword
required field
the keyword you specify should indicate a business category, company name, or a prominent place;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/locations
example:
1003854","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/locations
example:
London,England,United Kingdom","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data tripadvisor search task post"},{"name":"business_data_trustpilot_reviews_task_get_id","description":"This endpoint provides reviews published on the Trustpilot platform The returned results are specific to the indicated business entity. We emulate set parameters with the highest accuracy so that the results you receive will match the actual search results for the specified parameters at the time of task setting. You can always check the returned results accessing the check_url in the Incognito mode to make sure the received data is entirely relevant. Note that user preferences, search history, and other personalized search factors are ignored by our system and thus would not be reflected in the returned results.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data trustpilot reviews task get id"},{"name":"business_data_trustpilot_reviews_task_post","description":"‌‌\nThis endpoint provides reviews published on the Trustpilot platform for the local establishment specified in the domain field.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"depth":40,"domain":"www.thepearlsource.com"}]],"items":{"oneOf":[{"examples":[[{"depth":40,"domain":"www.thepearlsource.com"}]],"properties":{"depth":{"description":"parsing depth
optional field
number of reviews to be returned from the API response
we strongly recommend setting the parsing depth in the multiples of twenty, because our system processes twenty reviews in a row
default value: 20
maximum value: 200
Your account will be billed per each SERP containing up to 20 results;
Setting depth above 20 may result in additional charges if the search engine returns more than 20 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"domain":{"description":"domain of the local establishment
required field
domain of the local establishment on Trustpilot;
you can find the domain in the URL of every business listed on Trustpilot
example:
www.thepearlsource.com
https://www.trustpilot.com/review/www.thepearlsource.com","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"sort_by":{"description":"results sorting parameter
optional field
you can use this field to sort the results;
possible sorting parameters:
recency — most recent reviews first;
relevance — most relevant reviews first;
default value: relevance","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data trustpilot reviews task post"},{"name":"business_data_trustpilot_search_task_get_id","description":"This endpoint provides a list of business profiles listed on the Trustpilot platform. The returned results are relevant to the keyword specified in a POST request. We emulate set parameters with the highest accuracy so that the results you receive match the actual search results for the specified parameters at the time of task setting. You can always check the returned results accessing the check_url in the Incognito mode to make sure the received data is entirely relevant. Note that user preferences, search history, and other personalized search factors are ignored by our system and thus will not be reflected in the returned results.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data trustpilot search task get id"},{"name":"business_data_trustpilot_search_task_post","description":"‌‌\nThis endpoint provides a list of business profiles listed on the Trustpilot platform. The returned results are relevant to the specified keyword.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"depth":20,"keyword":"pizza restaurant"}]],"items":{"oneOf":[{"examples":[[{"depth":20,"keyword":"pizza restaurant"}]],"properties":{"depth":{"description":"parsing depth
optional field
number of search results to be returned from the API response
we strongly recommend setting the parsing depth in the multiples of twenty because our systems processes twenty search results in a row;
default value: 10;
maximum value: 140
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"keyword":{"description":"keyword
required field
the keyword you specify should indicate a business category or company name;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Business data trustpilot search task post"},{"name":"content_analysis_category_trends_live","description":"‌\nThis endpoint will provide you with data on all citations in the target category for the indicated date range.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"category_code":10994,"date_from":"2022-09-01","date_group":"month","search_mode":"as_is"}]],"items":{"oneOf":[{"examples":[[{"category_code":10994,"date_from":"2022-09-01","date_group":"month","search_mode":"as_is"}]],"properties":{"category_code":{"description":"target category code
required field
to obtain a full list of available categories, refer to the Categories endpoint","type":["integer","null"]},"date_from":{"description":"starting date of the time range
required field
minimum value: 2022-10-31
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":"string"},"date_group":{"description":"time range which will be used to group the results
optional field
default value: month
possible values: day, week, month","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, today's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"initial_dataset_filters":{"description":"initial dataset filtering parameters
optional field
initial filtering parameters that apply to fields in the Search endpoint;
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, like,not_like, has, has_not, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"domain\",\"<>\", \"logitech.com\"]
[[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]]
[[\"domain\",\"<>\",\"logitech.com\"]], \"and\", [[\"content_info.connotation_types.negative\",\">\",1000], \"or\",
[\"content_info.text_category\",\"has\",10994]]]
for more information about filters, please refer to Content Analysis API - Filters
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
top_domains
text_categories
page_categories
countries
languages
default value: 1
maximum value: 20","type":["integer","null"]},"page_type":{"description":"target page types
optional field
use this parameter to filter the dataset by page types
possible values:
\"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\"","items":{"type":"string"},"type":["array","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works in this Help Center article","type":["string","null"]},"search_mode":{"description":"results grouping type
optional field
possible grouping types:
as_is - returns data on all citations for the target category_code
one_per_domain - returns data on one citation of the category_code per domain
default value: as_is","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Content analysis category trends live"},{"name":"content_analysis_phrase_trends_live","description":"‌\nThis endpoint will provide you with data on all citations of the target keyword for the indicated date range.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2022-09-01","date_group":"month","keyword":"logitech","search_mode":"as_is"}]],"items":{"oneOf":[{"examples":[[{"date_from":"2022-09-01","date_group":"month","keyword":"logitech","search_mode":"as_is"}]],"properties":{"date_from":{"description":"starting date of the time range
required field
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":"string"},"date_group":{"description":"time range which will be used to group the results
optional field
default value: month
possible values: day, week, month","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, today's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"initial_dataset_filters":{"description":"initial dataset filtering parameters
optional field
initial filtering parameters that apply to fields in the Search endpoint;
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, like,not_like, has, has_not, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters;
example:
[\"domain\",\"<>\", \"logitech.com\"]
[[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]]
[[\"domain\",\"<>\",\"logitech.com\"]], \"and\", [[\"content_info.connotation_types.negative\",\">\",1000], \"or\",
[\"content_info.text_category\",\"has\",10994]]]
for more information about filters, please refer to Content Analysis API - Filters
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
top_domains
text_categories
page_categories
countries
languages
default value: 1
maximum value: 20","type":["integer","null"]},"keyword":{"description":"target keyword
required field
UTF-8 encoding
the keywords will be converted to a lowercase format;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
\"keyword\": \"\\\"tesla palo alto\\\"\"
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"keyword_fields":{"additionalProperties":{"type":["string","null"]},"description":"target keyword fields and target keywords
optional field
use this parameter to filter the dataset by keywords that certain fields should contain;
fields you can specify: title, main_title, previous_title, snippet
you can indicate several fields;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
`\"keyword_fields\": {
\"snippet\": \"\\\"logitech mouse\\\"\",
\"main_title\": \"sale\"
}`","type":["object","null"]},"page_type":{"description":"target page types
optional field
use this parameter to filter the dataset by page types
possible values:
\"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\"","items":{"type":"string"},"type":["array","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works in this Help Center article","type":["string","null"]},"search_mode":{"description":"results grouping type
optional field
possible grouping types:
as_is - returns data on all citations for the target keyword
one_per_domain - returns data on one citation of the keyword per domain
default value: as_is","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Content analysis phrase trends live"},{"name":"content_analysis_rating_distribution_live","description":"‌\nThis endpoint will provide you with rating distribution data for the keyword and other parameters specified in the request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"internal_list_limit":10,"keyword":"logitech","search_mode":"as_is"}]],"items":{"oneOf":[{"examples":[[{"internal_list_limit":10,"keyword":"logitech","search_mode":"as_is"}]],"properties":{"initial_dataset_filters":{"description":"initial dataset filtering parameters
optional field
initial filtering parameters that apply to fields in the Search endpoint
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, like,not_like, has, has_not, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"domain\",\"<>\", \"logitech.com\"]
[[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]]
[[\"domain\",\"<>\",\"logitech.com\"]], \"and\", [[\"content_info.connotation_types.negative\",\">\",1000], \"or\",
[\"content_info.text_category\",\"has\",10994]]]
for more information about filters, please refer to Content Analysis API - Filters
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
top_domains
text_categories
page_categories
countries
languages
default value: 1
maximum value: 20","type":["integer","null"]},"keyword":{"description":"target keyword
required field
UTF-8 encoding
the keywords will be converted to a lowercase format;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
\"keyword\": \"\\\"tesla palo alto\\\"\"
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"keyword_fields":{"additionalProperties":{"type":["string","null"]},"description":"target keyword fields and target keywords
optional field
use this parameter to filter the dataset by keywords that certain fields should contain;
fields you can specify: title, main_title, previous_title, snippet
you can indicate several fields;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
`\"keyword_fields\": {
\"snippet\": \"\\\"logitech mouse\\\"\",
\"main_title\": \"sale\"
}`","type":["object","null"]},"page_type":{"description":"target page types
optional field
use this parameter to filter the dataset by page types
possible values:
\"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\"","items":{"type":"string"},"type":["array","null"]},"positive_connotation_threshold":{"description":"positive connotation threshold
optional field
specified as the probability index threshold for positive sentiment related to the citation content
if you specify this field, connotation_types object in the response will only contain data on citations with positive sentiment probability more than or equal to the specified value
possible values: from 0 to 1
default value: 0.4","type":["number","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works in this Help Center article","type":["string","null"]},"search_mode":{"description":"results grouping type
optional field
possible grouping types:
as_is - returns all citations for the target keyword
one_per_domain - returns one citation of the keyword per domain
default value: as_is","type":["string","null"]},"sentiments_connotation_threshold":{"description":"sentiment connotation threshold
optional field
specified as the probability index threshold for sentiment connotations related to the citation content
if you specify this field, sentiment_connotations object in the response will only contain data on citations where the probability per each sentiment is more than or equal to the specified value
possible values: from 0 to 1
default value: 0.4","type":["number","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Content analysis rating distribution live"},{"name":"content_analysis_search_live","description":"‌\nThis endpoint will provide you with detailed citation data available for the target keyword.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":["main_domain","=","reviewfinder.ca"],"keyword":"logitech","keyword_fields":{"snippet":"logitech"},"limit":10,"order_by":["content_info.sentiment_connotations.anger,desc"],"page_type":["ecommerce","news","blogs","message-boards","organization"],"search_mode":"as_is"}]],"items":{"oneOf":[{"examples":[[{"filters":["main_domain","=","reviewfinder.ca"],"keyword":"logitech","keyword_fields":{"snippet":"logitech"},"limit":10,"order_by":["content_info.sentiment_connotations.anger,desc"],"page_type":["ecommerce","news","blogs","message-boards","organization"],"search_mode":"as_is"}]],"properties":{"filters":{"description":"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, like,not_like, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"country\",\"=\", \"US\"]
[[\"domain_rank\",\">\",800],\"and\",[\"content_info.connotation_types.negative\",\">\",0.9]]
[[\"domain_rank\",\">\",800], \"and\", [[\"page_types\",\"has\",\"ecommerce\"], \"or\",
[\"content_info.text_category\",\"has\",10994]]]
for more information about filters, please refer to Content Analysis API - Filters","items":{"type":["object","null"]},"type":["array","null"]},"keyword":{"description":"target keyword
required field
UTF-8 encoding
the keywords will be converted to a lowercase format;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
`\"keyword\": \"\\\"tesla palo alto\\\"\"`
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"keyword_fields":{"additionalProperties":{"type":["string","null"]},"description":"target keyword fields and target keywords
optional field
use this parameter to filter the dataset by keywords that certain fields should contain;
fields you can specify: title, main_title, previous_title, snippet
you can indicate several fields;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
`\"keyword_fields\": {
\"snippet\": \"\\\"logitech mouse\\\"\",
\"main_title\": \"sale\"
}\"`","type":["object","null"]},"limit":{"description":"the maximum number of returned citations
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned citations
optional field
default value: 0
if you specify the 10 value, the first ten citations in the results array will be omitted and the data will be provided for the successive citations
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead.","type":["integer","null"]},"offset_token":{"description":"offset token for subsequent requests
optional field
provided in the identical field of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;
offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task
learn more about this parameter on our Help Center","type":["string","null"]},"order_by":{"description":"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:
[\"content_info.sentiment_connotations.anger,desc\"]
default rule:
[\"content_info.sentiment_connotations.anger,desc\"]
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:
[\"content_info.sentiment_connotations.anger,desc\",\"keyword_data.keyword_info.cpc,desc\"]","items":{"type":"string"},"type":["array","null"]},"page_type":{"description":"target page types
optional field
use this parameter to filter the dataset by page types
possible values:
\"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\"","items":{"type":"string"},"type":["array","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the domain_rank, and url_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works in this Help Center article","type":["string","null"]},"search_mode":{"description":"results grouping type
optional field
possible grouping types:
as_is - returns all citations for the target keyword
one_per_domain - returns one citation of the keyword per domain
default value: as_is","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Content analysis search live"},{"name":"content_analysis_sentiment_analysis_live","description":"This endpoint will provide you with sentiment analysis data for the citations available for the target keyword.\nfor more info please visit 'https://docs.dataforseo.com/v3/content_analysis/sentiment_analysis/live/?bash'","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"internal_list_limit":1,"keyword":"logitech"}]],"items":{"oneOf":[{"examples":[[{"internal_list_limit":1,"keyword":"logitech"}]],"properties":{"initial_dataset_filters":{"description":"initial dataset filtering parameters\noptional field\ninitial filtering parameters that apply to fields in the Search endpoint\nyou can add several filters at once (8 filters maximum)\nyou should set a logical operator and, or between the conditions\nthe following operators are supported:\nregex, not_regex, <, <=, >, >=, =, <>, in, not_in, like,not_like, has, has_not, match, not_match\nyou can use the % operator with like and not_like to match any string of zero or more characters\nexample:\n[\"domain\",\"<>\", \"logitech.com\"]\n[[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]]\n[[\"domain\",\"<>\",\"logitech.com\"]],\n\"and\",\n[[\"content_info.connotation_types.negative\",\">\",1000],\n\"or\",\n[\"content_info.text_category\",\"has\",10994]]]\nfor more information about filters, please refer to Content Analysis API – Filters\nlearn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays\noptional field\nyou can use this field to limit the number of elements within the following arrays:\ntop_domains\ntext_categories\npage_categories\ncountries\nlanguages\ndefault value: 1\nmaximum value: 20","type":["integer","null"]},"keyword":{"description":"target keyword\nrequired field\nUTF-8 encoding\nthe keywords will be converted to a lowercase format;\nNote: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;\nexample:\n\"keyword\": \"\\\"tesla palo alto\\\"\"\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"keyword_fields":{"additionalProperties":{"type":["string","null"]},"description":"target keyword fields and target keywords\noptional field\nuse this parameter to filter the dataset by keywords that certain fields should contain;\nfields you can specify: title, main_title, previous_title, snippet\nyou can indicate several fields;\nNote: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;\nexample:\n\"keyword_fields\": {\n \"snippet\": \"\\\"logitech mouse\\\"\",\n \"main_title\": \"sale\"\n}","type":["object","null"]},"page_type":{"description":"target page types\noptional field\nuse this parameter to filter the dataset by page types\npossible values:\n\"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\"","items":{"type":"string"},"type":["array","null"]},"positive_connotation_threshold":{"description":"positive connotation threshold\noptional field\nspecified as the probability index threshold for positive sentiment related to the citation content\nif you specify this field, connotation_types object in the response will only contain data on citations with positive sentiment probability more than or equal to the specified value\npossible values: from 0 to 1\ndefault value: 0.4","type":["number","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank values\noptional field\nyou can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale\npossible values:\none_hundred — rank values are displayed on a 0–100 scale\none_thousand — rank values are displayed on a 0–1000 scale\ndefault value: one_thousand\nlearn more about how this parameter works in this Help Center article","type":["string","null"]},"sentiments_connotation_threshold":{"description":"sentiment connotation threshold\noptional field\nspecified as the probability index threshold for sentiment connotations related to the citation content\nif you specify this field, sentiment_connotations object in the response will only contain data on citations where the probability per each sentiment is more than or equal to the specified value\npossible values: from 0 to 1\ndefault value: 0.4","type":["number","null"]},"tag":{"description":"user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Content analysis sentiment analysis live"},{"name":"content_analysis_summary_live","description":"‌\nThis endpoint will provide you with an overview of citation data available for the target keyword.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"internal_list_limit":8,"keyword":"logitech","page_type":["ecommerce","news","blogs","message-boards","organization"],"positive_connotation_threshold":0.5}]],"items":{"oneOf":[{"examples":[[{"internal_list_limit":8,"keyword":"logitech","page_type":["ecommerce","news","blogs","message-boards","organization"],"positive_connotation_threshold":0.5}]],"properties":{"initial_dataset_filters":{"description":"initial dataset filtering parameters
optional field
initial filtering parameters that apply to fields in the Search endpoint
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, like,not_like, has, has_not
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"domain\",\"<>\", \"logitech.com\"]
[[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]]
[[\"domain\",\"<>\",\"logitech.com\"]], \"and\", [[\"content_info.connotation_types.negative\",\">\",1000], \"or\",
[\"content_info.text_category\",\"has\",10994]]]
for more information about filters, please refer to Content Analysis API - Filters
learn more about the initial dataset filters in this help center article.","items":{"type":["object","null"]},"type":["array","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
top_domains
text_categories
page_categories
countries
languages
default value: 1
maximum value: 20","type":["integer","null"]},"keyword":{"description":"target keyword
required field
UTF-8 encoding
the keywords will be converted to a lowercase format;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
\"keyword\": \"\\\"tesla palo alto\\\"\"
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"keyword_fields":{"additionalProperties":{"type":["string","null"]},"description":"target keyword fields and target keywords
optional field
use this parameter to filter the dataset by keywords that certain fields should contain;
fields you can specify: title, main_title, previous_title, snippet
you can indicate several fields;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
\"keyword_fields\": { \"snippet\": \"\\\"logitech mouse\\\"\", \"main_title\": \"sale\" }","type":["object","null"]},"page_type":{"description":"target page types
optional field
use this parameter to filter the dataset by page types
possible values:
\"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\"","items":{"type":"string"},"type":["array","null"]},"positive_connotation_threshold":{"description":"positive connotation threshold
optional field
specified as the probability index threshold for positive sentiment related to the citation content
if you specify this field, connotation_types object in the response will only contain data on citations with positive sentiment probability more than or equal to the specified value
possible values: from 0 to 1
default value: 0.4","type":["number","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works in this Help Center article","type":["string","null"]},"sentiments_connotation_threshold":{"description":"sentiment connotation threshold
optional field
specified as the probability index threshold for sentiment connotations related to the citation content
if you specify this field, sentiment_connotations object in the response will only contain data on citations where the
probability per each sentiment is more than or equal to the specified value
possible values: from 0 to 1
default value: 0.4","type":["number","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Content analysis summary live"},{"name":"domain_analytics_technologies_aggregation_technologies_live","description":"‌‌\nThe Aggregation Technologies endpoint will provide you with a list of the most popular technologies websites use alongside the technologies you specify. Alternatively, you can specify technology categories or groups to obtain wider stats.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["country_iso_code","=","US"],"and",["domain_rank",">",800]],"keyword":"WordPress","limit":10,"mode":"entry","order_by":["groups_count,desc"],"technology":"Nginx"}]],"items":{"oneOf":[{"examples":[[{"filters":[["country_iso_code","=","US"],"and",["domain_rank",">",800]],"keyword":"WordPress","limit":10,"mode":"entry","order_by":["groups_count,desc"],"technology":"Nginx"}]],"properties":{"category":{"description":"id of the target technology category
required field if you don't specify group, keyword or technology
at least one field (group, category, keyword, technology) must be set
you can find the full list of technology category ids on this page
example:
\"crm\"","type":"string"},"filters":{"description":"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:
<, <=, >, >=, =, <>, in, not_in, like,not_like
you can use the % operator with like and not_like to match any string of zero or more characters
you can use the following parameters to filter the results: domain_rank, last_visited, country_iso_code, language_code, content_language_code
Note: all filtering parameters are taken from the domain_technology_item of the domain_technologies endpoint;
example:
[[\"country_iso_code\",\"=\",\"US\"], \"and\", [\"domain_rank\",\">\",800]]for more information about filters, please refer to Domain Analytics Technologies API - Filters","items":{"type":["object","null"]},"type":["array","null"]},"group":{"description":"id of the target technology group
required field if you don't specify technology, category or keyword
at least one field (group, category, keyword, technology) must be set
you can find the full list of technology group ids on this page
example:
\"marketing\"","type":"string"},"internal_categories_list_limit":{"description":"maximum number of returned technology categories within the same group
optional field
you can use this field to limit the number of items with identical \"category\" in the results
default value: 5
minimum value: 1
maximum value: 10000","type":["integer","null"]},"internal_groups_list_limit":{"description":"maximum number of returned technology groups
optional field
you can use this field to limit the number of items with identical \"group\" in the results
default value: 5
minimum value: 1
maximum value: 10000","type":["integer","null"]},"internal_list_limit":{"description":"maximum number of items with identical \"category\", \"group\", and \"technology\"
optional field
if you use this field, the values specified in internal_groups_list_limit, internal_categories_list_limit and internal_technologies_list_limit will be ignored;
you can use this field to limit the number of items with identical \"category\", \"group\", or \"technology\"
default value: 10
minimum value: 1
maximum value: 10000","type":["integer","null"]},"internal_technologies_list_limit":{"description":"maximum number of returned technologies within the same category
optional field
you can use this field to limit the number of items with identical \"technology\" in the results
default value: 10
minimum value: 1
maximum value: 10000","type":["integer","null"]},"keyword":{"description":"target keyword in the domain's meta keywords
required field if you don't specify group, category or technology
at least one field (group, category, keyword, technology) must be set
UTF-8 encoding
example:
\"seo\"learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"limit":{"description":"the maximum number of returned technologies
optional field
default value: 100
maximum value: 10000","type":["integer","null"]},"mode":{"description":"search mode
optional field
possible search mode types:
as_is - search for results exactly matching the specified group ids, category ids, or technology names
entry - search for results matching a part of the specified group ids, category ids, or technology names
default value: as_is","type":["string","null"]},"offset":{"description":"offset in the results array of returned domains
optional field
default value: 0
maximum value: 9999
if you specify the 10 value, the first ten technologies in the results array will be omitted and the data will be provided for the successive technologies","type":["integer","null"]},"order_by":{"description":"results sorting rules
optional field
you can use the following values to sort the results: groups_count, categories_count, technologies_count
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:
[\"groups_count,desc\"]
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:
[\"groups_count,desc\",\"technologies_count,desc\"]
default value:
[\"groups_count,desc\",\"categories_count,desc\",\"technologies_count,desc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"technology":{"description":"target technology
required field if you don't specify group, keyword or category
at least one field (group, category, keyword, technology) must be set
you can find the full list of technologies on this page
example:
\"Salesforce\"","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Domain analytics technologies aggregation technologies live"},{"name":"domain_analytics_technologies_domain_technologies_live","description":"‌‌\nUsing this endpoint you will get a list of technologies used in a particular domain.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"target":"dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"target":"dataforseo.com"}]],"properties":{"target":{"description":"target domain
required field
domain name of the website to analyze
Note: results will be returned for the specified domain only","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Domain analytics technologies domain technologies live"},{"name":"domain_analytics_technologies_domains_by_html_terms_live","description":"‌‌\nThis endpoint provides domains based on the HTML terms they use on their homepage. In addition to the list of domains, you will also get their technology profiles, the country and language they belong to, and other related data.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"limit":10,"offset":0,"order_by":["last_visited,desc"],"search_terms":["data-attrid"]}]],"items":{"oneOf":[{"examples":[[{"limit":10,"offset":0,"order_by":["last_visited,desc"],"search_terms":["data-attrid"]}]],"properties":{"filters":{"description":"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:
<, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"domain\",\"like\",\"%seo%\"]
[[\"country_iso_code\",\"=\",\"US\"], \"and\", [\"domain_rank\",\">\",100]]
[[\"domain_rank\",\">\",100], \"and\", [[\"country_iso_code\",\"=\",\"US\"],\"or\",[\"country_iso_code\",\"=\",\"CA\"]]]
for more information about filters, please refer to Domain Analytics Technologies API - Filters","items":{"type":["object","null"]},"type":["array","null"]},"keywords":{"description":"target keywords in the domain's title, description or meta keywords
optional field
UTF-8 encoding
maximum number of keywords you can specify: 10
example:
[\"seo\",\"software\"]
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":["array","null"]},"limit":{"description":"the maximum number of returned domains
optional field
default value: 100
maximum value: 10000","type":["integer","null"]},"mode":{"description":"search mode
optional field
possible search mode types:
strict_entry - search for results exactly matching the order, intervals and separators in the specified search terms
entry - search for results ignoring the order, intervals and separators in the specified search terms
default value: entry","type":["string","null"]},"offset":{"description":"offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive domains;
Note: the maximum value is 9999, the sum of limit and offset must not exceed 10000;
use the offset_token if you would like to offset more results","type":["integer","null"]},"offset_token":{"description":"token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;
offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center","type":["string","null"]},"order_by":{"description":"results sorting rules
optional field
available fields:
domain_rank, domain, last_visited, country_iso_code, language_code, content_language_code
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:
[\"last_visited,desc\"]
default rule:
[\"domain_rank,desc\"]
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:
[\"last_visited,desc\",\"domain_rank,desc\"]","items":{"type":"string"},"type":["array","null"]},"search_terms":{"description":"target search terms
required field
specify target HTML elements, tags, attributes, their content or all of the above
if you specify more than one search term, you will receive only the domains containing all of the specified terms in the HTML code of their homepage
maximum number of search terms you can specify: 10
example:
[\"data-attrid\"]","items":{"type":"string"},"type":"array"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Domain analytics technologies domains by html terms live"},{"name":"domain_analytics_technologies_domains_by_technology_live","description":"‌‌\nThis endpoint provides domains based on the technology they use. In addition to the list of domains, you will also get their technology profiles, the country and language they belong to, and other related data.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["country_iso_code","=","US"],"and",["domain_rank",">",800]],"limit":10,"order_by":["last_visited,desc"],"technologies":["Nginx"]}]],"items":{"oneOf":[{"examples":[[{"filters":[["country_iso_code","=","US"],"and",["domain_rank",">",800]],"limit":10,"order_by":["last_visited,desc"],"technologies":["Nginx"]}]],"properties":{"categories":{"description":"ids of the target technology categories
required field if you don't specify groups, technology_paths, keywords or technologies
you can find the full list of technology category ids on this page
note: you can specify up to 10 technology categories in this array
example:
[\"payment_processors\",\"crm\"]","items":{"type":"string"},"type":"array"},"filters":{"description":"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:
<, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"country_iso_code\",\"=\",\"US\"]
[[\"country_iso_code\",\"=\",\"US\"], \"and\", [\"domain_rank\",\">\",100]]
[[\"domain_rank\",\">\",100], \"and\", [[\"country_iso_code\",\"=\",\"US\"],\"or\",[\"country_iso_code\",\"=\",\"CA\"]]]
for more information about filters, please refer to Domain Analytics Technologies API - Filters","items":{"type":["object","null"]},"type":["array","null"]},"groups":{"description":"ids of the target technology groups
required field if you don't specify technologies, technology_paths, keywords or categories
you can find the full list of technology group ids on this page
note: you can specify up to 10 technology groups in this array
example:
[\"sales\", \"marketing\"]","items":{"type":"string"},"type":"array"},"keywords":{"description":"target keywords in the domain's title, description or meta keywords
required field if you don't specify groups, technology_paths, technologies or categories
optional field
you can specify the maximum of 10 keywords;
UTF-8 encoding;
example:
[\"seo\",\"software\"]
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"limit":{"description":"the maximum number of returned domains
optional field
default value: 100
maximum value: 10000","type":["integer","null"]},"mode":{"description":"search mode
optional field
possible search mode types:
as_is - search for results exactly matching the specified group ids, category ids, or technology names
entry - search for results matching a part of the specified group ids, category ids, or technology names
default value: as_is","type":["string","null"]},"offset":{"description":"offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive domains;
Note: the maximum value is 9999, the sum of limit and offset must not exceed 10000;
use the offset_token if you would like to offset more results","type":["integer","null"]},"offset_token":{"description":"token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;
offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center","type":["string","null"]},"order_by":{"description":"results sorting rules
optional field
available fields:
domain_rank, domain, last_visited, country_iso_code, language_code, content_language_code
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:
[\"last_visited,desc\"]
default rule:
[\"domain_rank,desc\"]
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:
[\"last_visited,desc\",\"domain_rank,desc\"]","items":{"type":"string"},"type":["array","null"]},"technologies":{"description":"target technologies
required field if you don't specify groups, technology_paths, keywords or categories
you can find the full list of technologies you can specify here on this page
note: you can specify up to 10 technologies in this array
example:
[\"Google Pay\",\"Salesforce\"]","items":{"type":"string"},"type":"array"},"technology_paths":{"description":"target technology paths
required field if you don't specify groups, technologies, keywords or categories
at least one field (technology_paths, groups, technologies, keywords or categories) must be set;
each technology path should be specified as a separate object containing \"path\" and \"name\", where \"path\" is specified as \"$group_id.$category_id\" and \"name\" - as the name of the target technology;
each object with a technology path should be separated with a comma
you can find the full list of technology group ids, category ids and technology names on this page
note: you can specify up to 10 technology paths in this array
example:
[{\"path\": \"content.cms\",\"name\": \"wordpress\"}, {\"path\": \"marketing.crm\",\"name\": \"salesforce\"}]","items":{"type":"string"},"type":"array"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Domain analytics technologies domains by technology live"},{"name":"domain_analytics_technologies_technologies","description":"This endpoint will provide you with the full list of available technologies structured by technology groups and categories each particular technology belongs to.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Domain analytics technologies technologies"},{"name":"domain_analytics_technologies_technologies_summary_live","description":"‌‌\nThe Technologies Summary endpoint will provide you with the number of domains across different countries and languages that use the specified technology names, technology groups, or technology categories.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["country_iso_code","=","US"],"and",["domain_rank",">",800]],"keywords":["WordPress"],"mode":"entry","technologies":["Ngi"]}]],"items":{"oneOf":[{"examples":[[{"filters":[["country_iso_code","=","US"],"and",["domain_rank",">",800]],"keywords":["WordPress"],"mode":"entry","technologies":["Ngi"]}]],"properties":{"categories":{"description":"ids of the target technology categories
required field if you don't specify groups, technology_paths, technologies, or keywords
you can find the full list of technology category ids on this page
note: you can specify up to 10 technology categories in this array
example:
[\"payment_processors\",\"crm\"]","items":{"type":"string"},"type":"array"},"filters":{"description":"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:
<, <=, >, >=, =, <>, in, not_in, like,not_like
you can use the % operator with like and not_like to match any string of zero or more characters
you can use the following parameters to filter the results: domain_rank, last_visited, country_iso_code, language_code, content_language_code
example:
[[\"country_iso_code\",\"=\",\"US\"], \"and\", [\"domain_rank\",\">\",800]]
for more information about filters, please refer to Domain Analytics Technologies API - Filters","items":{"type":["object","null"]},"type":["array","null"]},"groups":{"description":"ids of the target technology groups
required field if you don't specify technologies, technology_paths, categories, or keywords
you can find the full list of technology group ids on this page
note: you can specify up to 10 technology groups in this array
example:
[\"sales\", \"marketing\"]","items":{"type":"string"},"type":"array"},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
countries, languages, content_languages, keywords
default value: 10
minimum value: 1
maximum value: 10000","type":["integer","null"]},"keywords":{"description":"target keywords in the domain's title, description or meta keywords
required field if you don't specify groups, technology_paths, categories, or technologies
you can specify the maximum of 10 keywords;
UTF-8 encoding;
example:
[\"seo\",\"software\"]
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"mode":{"description":"search mode
optional field
possible search mode types:
as_is - search for results exactly matching the specified group ids, category ids, or technology names
entry - search for results matching a part of the specified group ids, category ids, or technology names
default value: as_is","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"technologies":{"description":"target technologies
required field if you don't specify groups, technology_paths, categories, or keywords
you can find the full list of technologies you can specify here on this page
note: you can specify up to 10 technologies in this array
example:
[\"Google Pay\",\"Salesforce\"]","items":{"type":"string"},"type":"array"},"technology_paths":{"description":"target technology paths
required field if you don't specify groups, technologies and categories
each technology path should be specified as a separate object containing \"path\" and \"name\", where \"path\" is specified as \"$group_id.$category_id\" and \"name\" - as the name of the target technology;
each object with a technology path should be separated with a comma
you can find the full list of technology group ids, category ids and technology names on this page
note: you can specify up to 10 technology paths in this array
example:
[{\"path\": \"content.cms\",\"name\": \"wordpress\"}, {\"path\": \"marketing.crm\",\"name\": \"salesforce\"}]","items":{"type":"string"},"type":"array"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Domain analytics technologies technologies summary live"},{"name":"domain_analytics_technologies_technology_stats_live","description":"‌‌\nThe Technology Stats endpoint will provide you with historical data on the number of domains across different countries and languages that use the specified technology.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2022-10-31","date_to":"2023-06-01","technology":"jQuery"}]],"items":{"oneOf":[{"examples":[[{"date_from":"2022-10-31","date_to":"2023-06-01","technology":"jQuery"}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
minimum value: 2022-10-31
if you don't specify this field, the minimum value will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2023-06-01\"","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2023-01-15\"","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"technology":{"description":"target technology
required field
you can find the full list of technologies you can specify here on this page
example:
\"Salesforce\"","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Domain analytics technologies technology stats live"},{"name":"domain_analytics_whois_overview_live","description":"‌\nThis endpoint will provide you with Whois data enriched with backlink stats, and ranking and traffic info from organic and paid search results. Using this endpoint you will be able to get all these data for the domains matching the parameters you specify in the request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["epp_status_codes","in",["client_transfer_prohibited","client_update_prohibited"]]],"limit":2}]],"items":{"oneOf":[{"examples":[[{"filters":[["epp_status_codes","in",["client_transfer_prohibited","client_update_prohibited"]]],"limit":2}]],"properties":{"filters":{"description":"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, <, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters","items":{"type":["object","null"]},"type":["array","null"]},"limit":{"description":"the maximum number of returned domains
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned items
optional field
default value: 0
if you specify the 10 value, the first ten items in the results array will be omitted and the data will be provided for the successive items;
Note: we recommend using this parameter only when retrieving up to 10,000 results for retrieving over 10,000 results, use the offset_token instead","type":["integer","null"]},"offset_token":{"description":"token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;
offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center","type":["string","null"]},"order_by":{"description":"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
the comma is used as a separator
example:
[\"metrics.organic.pos_1,desc\"]
default rule:
[\"metrics.organic.count,desc\"]
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:
[\"expiration_datetime,asc\",\"metrics.organic.etv,desc\",\"metrics.organic.pos_1,desc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Domain analytics whois overview live"},{"name":"google_serp","description":"Live SERP provides real-time data on search engine results for the specified keyword, search engine, and location.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"properties":{"depth":{"description":"
parsing depth
optional field
number of results in SERP
default value: 10
max value: 200

Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"device":{"description":"
device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop
","type":["string","null"]},"find_targets_in":{"description":"
SERP element types to check for targets
optional field
to enable this parameter, stop_crawl_on_match must also be enabled
specifies which SERP element types should be checked for target matches
if not specified, all first-level elements with url and domain fields are checked for targets
possible values: organic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitter
Note: cannot contain the same element types as ignore_targets_in
example:
\"find_targets_in\": [\"organic\", \"featured_snippet\"]
learn more about this parameter on our Help Center
","items":{"type":"string"},"type":["array","null"]},"group_organic_results":{"description":"
display related results
optional field
if set to true, the related_result element in the response will be provided as a snippet of its parent organic result;
if set to false, the related_result element will be provided as a separate organic result;
default value: true
","type":["boolean","null"]},"ignore_targets_in":{"description":"
SERP element types to exclude from target search
optional field
to enable this parameter, stop_crawl_on_match must also be enabled
specifies which SERP element types should be excluded when searching for target matches
possible values: organic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitter
Note: cannot contain the same element types as find_targets_in
example:
\"ignore_targets_in\": [\"paid\", \"images\"]
learn more about this parameter on our Help Center
","items":{"type":"string"},"type":["array","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”;
if this field contains such parameters as 'allinanchor:', 'allintext:', 'allintitle:', 'allinurl:', ‘cache:’, 'define:', 'filetype:', 'id:', 'inanchor:', 'info:', 'intext:', 'intitle:', 'inurl:', 'link:', 'site:', the charge per task will be multiplied by 5","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations
example:
2840
","type":"integer"},"location_coordinate":{"description":"
GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199 (mm)
the maximum value for \"radius\": 199999 (mm)
example:
53.476225,-2.243572,200
","type":"string"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations
example:
London,England,United Kingdom
","type":"string"},"match_type":{"description":"
target match type
required field if stop_crawl_on_match is specified
type of match for the match_value
possible values:
domain – specific domain or subdomain
with_subdomains – main domain and subdomains
wildcard – wildcard pattern
","type":"string"},"match_value":{"description":"
target domain, subdomain, or wildcard value
required field if stop_crawl_on_match is specified
specify a target domain, subdomain, or wildcard value;
Note: domain or subdomain must be specified without a request protocol;
example: \"match_value\": \"dataforseo.com\",
\"match_value\": \"/blog/post-*\"
","type":"string"},"max_crawl_pages":{"description":"
page crawl limit
optional field
number of search results pages to crawl
max value: 100
Note: you will be charged for each page crawled (10 organic results per page);
learn more about pricing on our Pricing page;
Note#2: the max_crawl_pages and depth parameters complement each other;
learn more at our help center
","type":["integer","null"]},"os":{"description":"
device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android
","type":["string","null"]},"se_domain":{"description":"
search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
google.co.uk, google.com.au, google.de, etc.
","type":["string","null"]},"search_param":{"description":"
additional parameters of the search query
optional field
get the list of available parameters and additional details here

Note: the following search engine parameters are not supported and will be automatically unset if specified: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype.","type":["string","null"]},"stop_crawl_on_match":{"description":"array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets","items":{"oneOf":[{"properties":{"match_type":{"description":"target match type\nrequired field if stop_crawl_on_match is specified;\ntype of match for the match_value\npossible values: domain, with_subdomains, wildcard","type":["string","null"]},"match_value":{"description":"arget domain or wildcard value\nrequired field if stop_crawl_on_match is specified;\nspecify a target domain or wildcard value;\nNote: domain name must be specified without a request protocol;\nexample: dataforseo.com","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"tag":{"description":"
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
","type":["string","null"]},"target":{"description":"
target domain, subdomain, or webpage to get results for
optional field
a domain or a subdomain should be specified without https:// and www.
note that the results of target-specific tasks will only include SERP elements that contain a url string;
you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results;
examples:
example.com - returns results for the website's home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;
example.com* - returns results for the domain, including all its pages;
*example.com* - returns results for the entire domain, including all its pages and subdomains;
*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com;
example.com/example-page - returns results for the exact URL;
example.com/example-page* - returns results for all domain's URLs that start with the specified string
","type":["string","null"]},"target_search_mode":{"description":"
target matching mode
optional field
to enable this parameter, stop_crawl_on_match must also be enabled
defines how the crawl should stop when multiple targets are specified in stop_crawl_on_match
possible values: all, any
all – the crawl stops only when all specified targets are found
any – the crawl stops when any single target is found
default value: any
learn more about this parameter on our Help Center
","type":["string","null"]},"url":{"description":"
direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS

Note: the following search engine parameters are not supported and will be automatically unset if specified in the URL: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype.","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Google serp","catalog":"google.serp.organic"},{"name":"keyword_ideas","description":"The Related Keywords endpoint provides keywords appearing in the “Searches Related to” SERP element.\n View the element.\nYou can get up to 4680 keyword ideas by specifying the search depth. Each related keyword comes with the list of relevant product categories, search volume rate for the last month, search volume trend for the previous 12 months, as well as current cost-per-click and competition values.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"phone","language_name":"English","limit":3,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"phone","language_name":"English","limit":3,"location_code":2840}]],"properties":{"depth":{"description":"keyword search depth
optional field
default value: 1
number of the returned results depends on the value you set in this field
you can specify a level from 0 to 4
estimated number of keywords for each level (maximum):
0 - the keyword set in the keyword field
1 – 8 keywords
2 – 72 keywords
3 – 584 keywords
4 – 4680 keywords","type":["integer","null"]},"filters":{"description":"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:
[\"keyword_data.keyword_info.search_volume\",\">\",0]
[[\"keyword_info.search_volume\",\"in\",[0,1000]], \"and\", [\"keyword_data.keyword_info.competition_level\",\"=\",\"LOW\"]]
[[\"keyword_data.keyword_info.search_volume\",\">\",100], \"and\", [[\"keyword_data.keyword_info.cpc\",\"<\",0.5], \"or\",
[\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"ignore_synonyms":{"description":"","type":["boolean","null"]},"include_clickstream_data":{"description":"","type":["boolean","null"]},"include_seed_keyword":{"description":"include data for the seed keyword
optional field
if set to true, data for the seed keyword specified in the keyword field will be provided in the seed_keyword_data array of the response
default value: false","type":["boolean","null"]},"include_serp_info":{"description":"include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false","type":["boolean","null"]},"keyword":{"description":"keyword
required field
UTF-8 encoding
the keywords will be converted to lowercase format
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_code by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_name by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
English","type":"string"},"limit":{"description":"the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
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
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or 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
example:
United Kingdom","type":"string"},"offset":{"description":"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","type":["integer","null"]},"order_by":{"description":"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:
[\"keyword_data.keyword_info.search_volume,desc\"]
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\"]","items":{"type":"string"},"type":["array","null"]},"replace_with_core_keyword":{"description":"return data for core keyword
optional field
if true, serp_info and related_keywords will be returned for the main keyword in the group that the specified keyword belongs to;
if false, serp_info and related_keywords will be returned for the specified keyword (if available);
refer to this help center article for more details;
default value: false","type":["boolean","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keyword ideas","catalog":"google.keywords.ideas"},{"name":"keyword_volume","description":"‌\nNote that Google Ads Keywords Data API is based on the latest version of the Google Ads API that has replaced legacy Google AdWords API. If you’re using DataForSEO Google AdWords API, you need to upgrade to DataForSEO Google Ads API.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2021-08-01","keywords":["buy laptop","cheap laptops for sale","purchase laptop"],"location_code":2840,"search_partners":true}]],"items":{"oneOf":[{"examples":[[{"date_from":"2021-08-01","keywords":["buy laptop","cheap laptops for sale","purchase laptop"],"location_code":2840,"search_partners":true}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
date format: \"yyyy-mm-dd\"
minimal value: 4 years from the current date
by default, data is returned for the past 12 months;
Note: the indicated date cannot be greater than that specified in date_to and/or yesterday's date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
Note: the indicated date cannot be greater than the past month, Google Ads does not return data on the current month;
if you don't specify this field, yesterday's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2022-11-30\"","type":["string","null"]},"include_adult_keywords":{"description":"include keywords associated with adult content
optional field
if set to_true, adult keywords will be included in the response
default value:_false
note_that the API may return no data for such keywords due to_Google Ads restrictionsn","type":["boolean","null"]},"keywords":{"description":"keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the keywords you specify will be converted to a lowercase format
Note #1: Google Ads may return no data for certain groups of keywords;
Note #2: Google Ads provides combined search volume values for groups of similar keywords
to obtain search volume for similar keywords, we recommend submitting such keywords in separate requests;
Note #3: Google Ads doesn't allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can't use them when setting a task;
to learn more about which symbols and characters can be used, please refer to this article
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"search engine language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of search engine language
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:
English","type":["string","null"]},"location_code":{"description":"search engine location code
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_coordinate;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:
2840","type":["integer","null"]},"location_coordinate":{"description":"GPS coordinates of a location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_code;
location_coordinate parameter should be specified in the \"latitude,longitude\" format;
the data will be provided for the country the specified coordinates belong to;
example:
52.6178549,-155.352142","type":["string","null"]},"location_name":{"description":"full name of search engine location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:
London,England,United Kingdom","type":["string","null"]},"search_partners":{"description":"include Google search partners
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search;
default value: false - results are returned for Google search sites","type":["boolean","null"]},"sort_by":{"description":"results sorting parameters
optional field
use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in the descending order
default value: relevance","type":["string","null"]},"tag":{"description":"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 array of the response","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keyword volume","catalog":"google.keywords.volume"},{"name":"keywords_data_bing_audience_estimation_industries","description":"By calling this API you will receive the list of industries with industry_id supported by Bing Ads Audience Estimation endpoint.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data bing audience estimation industries"},{"name":"keywords_data_bing_audience_estimation_job_functions","description":"By calling this API you will receive the list of job functions with job_function_id supported by Bing Ads Audience Estimation endpoint.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data bing audience estimation job functions"},{"name":"keywords_data_bing_audience_estimation_live","description":"This endpoint provides estimated audience size for an ad campaign based on specified targeting criteria. It returns data on the total estimated audience, such as suggested bid and budget for an ad campaign and estimated engagement metrics.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"age":["twenty_five_to_thirty_four","eighteen_to_twenty_four","unknown"],"bid":1,"daily_budget":24,"gender":["male"],"industry":["806303407","806301758"],"job_function":["806298607"],"location_coordinate":"29.6821525,-82.4098881,100"}]],"items":{"oneOf":[{"examples":[[{"age":["twenty_five_to_thirty_four","eighteen_to_twenty_four","unknown"],"bid":1,"daily_budget":24,"gender":["male"],"industry":["806303407","806301758"],"job_function":["806298607"],"location_coordinate":"29.6821525,-82.4098881,100"}]],"properties":{"age":{"description":"selection of age ranges for targeting
possible values: eighteen_to_twenty_four, fifty_to_sixty_four, sixty_five_and_above, thirteen_to_seventeen, thirty_five_to_forty_nine, twenty_five_to_thirty_four, unknown, zero_to_twelve","items":{"type":"string"},"type":["array","null"]},"bid":{"description":"desired bid setting value in USD
maximum value: 1000","type":["number","null"]},"daily_budget":{"description":"daily campaign budget value in USD
maximum value: 10000","type":["number","null"]},"gender":{"description":"gender to target
possible values: male, female, unknown","items":{"type":"string"},"type":["array","null"]},"industry":{"description":"industry of LinkedIn profile targeting
if you use this field, you can receive the list of available industry names with industry_id by making a separate request to the https://api.dataforseo.com/v3/keywords_data/bing/audience_estimation/industries
example: 806301758","items":{"type":"string"},"type":["array","null"]},"job_function":{"description":"job function of LinkedIn profile targeting
if you use this field, you can receive the list of available job function names with job_function_id by making a separate request to the https://api.dataforseo.com/v3/keywords_data/bing/audience_estimation/job_functions
example: 806300451","items":{"type":"string"},"type":["array","null"]},"location_code":{"description":"search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:
2840","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius (in km)\" format
the data will be provided for the country the specified coordinates belong to
example:
29.6821525,-82.4098881,100","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:
London,England,United Kingdom","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data bing audience estimation live"},{"name":"keywords_data_bing_keyword_performance_live","description":"‌\nYou can receive a set of keyword performance stats for a group of keywords depending on the specified match type, location and language parameters. Ad position, clicks, impressions, and other keyword metrics are aggregated for the last month for one or all of the following device types: mobile, desktop, tablet.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["dataforseo","seo","ranking"],"language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keywords":["dataforseo","seo","ranking"],"language_code":"en","location_code":2840}]],"properties":{"device":{"description":"device type
optional field
specify this field if you want to get the data for a particular device typepossible values: desktop, mobile, tablet, all
default value: all","type":["string","null"]},"keywords":{"description":"keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the specified keywords will be converted to lowercase, data will be provided in a separate array
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages
example:
\"en\"","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages
example:
2840","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:
52.6178549,-155.352142","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages
example:
\"United States\"","type":"string"},"match":{"description":"keywords match type
optional field
can take the following values:
aggregate returns data across all match types;
broad returns data for all user queries containing the specified keyword with varying word order;
phrase returns data for all user queries containing the specified keyword with identical word order;
exact returns data for user query that matches the specified keyword;Note: the aggregate match type is applied by default","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data bing keyword performance live"},{"name":"keywords_data_bing_keywords_for_keywords_live","description":"‌\nThis endpoint will select the relevant keywords for the specified ones. Set up to 200 keywords and get the results, which are suggested by Bing Ads for your query. You can get up to 3000 keyword suggestions using this function.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["average page rpm adsense","adsense blank ads how long","leads and prospects"],"language_name":"English","location_name":"United States"}]],"items":{"oneOf":[{"examples":[[{"keywords":["average page rpm adsense","adsense blank ads how long","leads and prospects"],"language_name":"English","location_name":"United States"}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
minimal value: 24 months from today's date;
if you don't specify this field, data will be provided for the last 12 months;
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior;
date format: \"yyyy-mm-dd\"
example:
\"2020-01-01\"
Note: we do not recommend using a custom time range for the past year's dates","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, data will be provided for the last 12 months;
minimum value: two years back from today’s date;
maximum value: one month from today's date;
date format: \"yyyy-mm-dd\"
example:
\"2020-03-15\"
Note: we do not recommend using a custom time range for the past year's dates","type":["string","null"]},"device":{"description":"device type
optional field
specify this field if you want to get the data for a particular device type;
possible values: all, mobile, desktop, tablet
default value: all","type":["string","null"]},"keywords":{"description":"keywords
required field
you can specify the maximum of 200 keywords with each keyword containing no more than 100 characters;
the specified keywords will be converted to lowercase, data will be provided in a separate array
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"keywords_negative":{"description":"keywords negative array
optional field
These keywords will be ignored in the results array;
You can specify a maximum of 200 terms that you want to exclude from the results;
the specified keywords will be converted to lowercase format","items":{"type":"string"},"type":["array","null"]},"language_code":{"description":"search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
supported languages:
en, fr, de","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
supported languages:
English, French, German","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:
2840","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:
52.6178549,-155.352142","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:
London,England,United Kingdom","type":"string"},"search_partners":{"description":"Bing search partners type
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search.
default value: false - results are returned for Bing, AOL, and Yahoo search networks","type":["boolean","null"]},"sort_by":{"description":"results sorting parameters
optional field
Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order
default value: relevance","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data bing keywords for keywords live"},{"name":"keywords_data_bing_keywords_for_site_live","description":"‌This endpoint will provide you with a list of keywords relevant to the specified URL along with their search volume for the last month, search volume trend for up to 24 past months (for estimating search volume dynamics), current cost-per-click and competition values for paid search. The maximum number of returned keywords is 3000.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"language_code":"en","location_code":2840,"target":"dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"language_code":"en","location_code":2840,"target":"dataforseo.com"}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
minimal value: 24 months from today's date;
if you don't specify this field, data will be provided for the last 12 months;
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior;
date format: \"yyyy-mm-dd\"
example:
\"2020-01-01\"
Note: we do not recommend using a custom time range for the past year's dates","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, data will be provided for the last 12 months;
minimum value: two years back from today’s date;
maximum value: one month from today's date;
note: we do not recommend using a custom time range for the past year's dates;
date format: \"yyyy-mm-dd\"
example:
\"2020-03-15\"
Note: we do not recommend using a custom time range for the past year's dates","type":["string","null"]},"device":{"description":"device type
optional field
specify this field if you want to get the data for a particular device typepossible values: all, mobile, desktop, tablet
default value: all","type":["string","null"]},"keywords_negative":{"description":"keywords negative array
optional field
These keywords will be ignored in the results array;
You can specify a maximum of 200 terms that you want to exclude from the results;
the specified keywords will be converted to lowercase format","items":{"type":"string"},"type":["array","null"]},"language_code":{"description":"search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
supported languages:
en, fr, de","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
supported languages:
English, French, German","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:
2840","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:
52.6178549,-155.352142","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:
London,England,United Kingdom","type":"string"},"search_partners":{"description":"Bing search partners type
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search.
default value: false - results are returned for Bing, AOL, and Yahoo search networks","type":["boolean","null"]},"sort_by":{"description":"results sorting parameters
optional field
Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order
default value: relevance","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain or URL
required field
the domain name or URL of the target website","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data bing keywords for site live"},{"name":"keywords_data_bing_search_volume_history_live","description":"‌This endpoint will provide you with historical search volume data for up to 1000 keywords in one request. You can get search volume for keywords in monthly, weekly, or daily format and specify the device type.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["10 minute timer"],"language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keywords":["10 minute timer"],"language_code":"en","location_code":2840}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
minimum value: 24 months back from today’s date;
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior;
date format: \"yyyy-mm-dd\"
example:
\"2020-01-01\"Note: we do not recommend using a custom time range;
Note 2: if date_from and date_to parameters are not specified, the data will be returned for the past 24 months;
if you specify the period parameter:
with value weekly, you will get results for the past 15 weeks;
with value daily, you will get results for the past 45 days","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional fieldminimum value: two years back from today’s date;
maximum value: one day from today's date;
date format: \"yyyy-mm-dd\"
example:
\"2020-03-15\"
Note: we do not recommend using a custom time range
Note 2: if date_from and date_to parameters are not specified, the data will be returned for the past 24 months
if you specify the period parameter:
with value weekly, you will get results for the past 15 weeks
with value daily, you will get results for the past 45 days","type":["string","null"]},"device":{"description":"device types
optional field
specify this field if you want to get the data for a particular device types
possible values: mobile, desktop, tablet, non_smartphones
default value: [\"mobile\", \"desktop\", \"tablet\", \"non_smartphones\"]","items":{"type":"string"},"type":["array","null"]},"keywords":{"description":"keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 100
the specified keywords will be converted to lowercase, data will be provided in a separate arraylearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engines with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/search_volume_history/locations_and_languages","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engines with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/search_volume_history/locations_and_languages","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/search_volume_history/locations_and_languages
example:
2840","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:
52.6178549,-155.352142","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/search_volume_history/locations_and_languages
example:
London,England,United Kingdom","type":"string"},"period":{"description":"aggregates the returned data to a certain time period
optional field
specify this field if you want to get the data in monthly, weekly or daily formatpossible values: monthly, weekly, daily
monthly - returns data up to past 24 months
weekly - returns data up to past 15 weeks
daily - returns data up to past 45 days
default value: monthly","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data bing search volume history live"},{"name":"keywords_data_bing_search_volume_live","description":"‌This endpoint will provide you with search volume data for the last month, search volume trend for up to 24 past months (that will let you estimate search volume dynamics), current cost-per-click and competition values for paid search.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["tom and jerry","silicon valley","spider man"],"language_code":"en","location_name":"United States"}]],"items":{"oneOf":[{"examples":[[{"keywords":["tom and jerry","silicon valley","spider man"],"language_code":"en","location_name":"United States"}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
minimal value: 24 months from today's date;
if you don't specify this field, data will be provided for the last 12 months;
minimum value: two years back from today’s date;
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior;
date format: \"yyyy-mm-dd\"
example:
\"2020-01-01\"Note: we do not recommend using a custom time range for the past year's dates","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, data will be provided for the last 12 months;
minimum value: two years back from today’s date;
maximum value: one month from today's date;
note: we do not recommend using a custom time range for the past year's dates;
date format: \"yyyy-mm-dd\"
example:
\"2020-03-15\"Note: we do not recommend using a custom time range for the past year's dates","type":["string","null"]},"device":{"description":"device type
optional field
specify this field if you want to get the data for a particular device type;
possible values: all, mobile, desktop, tablet
default value: all","type":["string","null"]},"keywords":{"description":"keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 100
the specified keywords will be converted to lowercase, data will be provided in a separate arraylearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
supported languages:
en, fr, de","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
supported languages:
English, French, German","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:
2840","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:
52.6178549,-155.352142","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:
London,England,United Kingdom","type":"string"},"search_partners":{"description":"Bing search partners type
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search.
default value: false - results are returned for Bing, AOL, and Yahoo search networks","type":["boolean","null"]},"sort_by":{"description":"results sorting parameters
optional field
Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order
default value: relevance","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data bing search volume live"},{"name":"keywords_data_clickstream_data_bulk_search_volume_live","description":"‌‌ \nThe Bulk Clickstream Search Volume endpoint of DataForSEO Keywords Data API is designed to provide clickstream-based search volume data for up to 1000 keywords in a single Live request. What’s more, it offers historical search volume values for up to 12 months (depending on keywords, location, and language parameters).","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["you tube","youtube","youtub"],"location_code":2840,"tag":"test-tag"}]],"items":{"oneOf":[{"examples":[[{"keywords":["you tube","youtube","youtub"],"location_code":2840,"tag":"test-tag"}]],"properties":{"keywords":{"description":"target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000;
each keyword should be at least 3 characters long;
the keywords will be converted to lowercase format;
Note: certain symbols and characters (e.g., UTF symbols, emojis) are not allowed
to learn more about which symbols and characters can be used, please refer to this article
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the
https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or 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/keywords_data/clickstream_data/locations_and_languages
example:
United Kingdom","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data clickstream data bulk search volume live"},{"name":"keywords_data_clickstream_data_dataforseo_search_volume_live","description":"‌","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["you tube","youtube","youtub"],"language_code":"en","location_code":2840,"tag":"test-tag"}]],"items":{"oneOf":[{"examples":[[{"keywords":["you tube","youtube","youtub"],"language_code":"en","location_code":2840,"tag":"test-tag"}]],"properties":{"keywords":{"description":"target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000
the keywords will be converted to lowercase format
Note: certain symbols and characters (e.g., UTF symbols, emojis) are not allowed
to learn more about which symbols and characters can be used, please refer to this article
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"search engine language code
required field if don’t 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/keywords_data/clickstream_data/locations_and_languages
example:
en","type":"string"},"language_name":{"description":"full name of search engine language
required field if don’t 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/keywords_data/clickstream_data/locations_and_languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don’t specify location_name
if you use this field, you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages
example:
2826","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don’t specify location_code
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages
example:
United Kingdom","type":"string"},"tag":{"description":"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","type":["string","null"]},"use_clickstream":{"description":"use clickstream data to provide results
optional field
if set to true, you will get DataForSEO search volume values based on clickstream data;
if set to false, Bing search volume data will be used to calculate DataForSEO search volume;
default value: true;
Note: Bing search volume is available for locations provided in Bing Search Volume History Locations and Bing Ads Locations endpoints; search volume values for any other location are calculated based on clickstream data even if you set this parameter to false","type":["boolean","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data clickstream data dataforseo search volume live"},{"name":"keywords_data_clickstream_data_global_search_volume_live","description":"‌‌ \nThe Clickstream Global Search Volume endpoint of DataForSEO Keywords Data API is designed to provide clickstream-based search volume data for up to 1000 keywords in a single Live request. What’s more, it offers geographical distribution of clickstream search volume values across all available locations.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["you tube","youtube","youtub"],"tag":"test-tag"}]],"items":{"oneOf":[{"examples":[[{"keywords":["you tube","youtube","youtub"],"tag":"test-tag"}]],"properties":{"keywords":{"description":"target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000;
each keyword should be at least 3 characters long;
the keywords will be converted to lowercase format;
Note: certain symbols and characters (e.g., UTF symbols, emojis) are not allowed
to learn more about which symbols and characters can be used, please refer to this article
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data clickstream data global search volume live"},{"name":"keywords_data_dataforseo_trends_demography_live","description":"This endpoint will provide you with the demographic breakdown (by age and gender) of keyword popularity per each specified term based on DataForSEO Trends data. You can check keyword trends for Google Search, Google News, and Google Shopping.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2023-01-01","date_to":"2024-01-01","keywords":["rugby","cricket"],"location_name":"United States","type":"web"}]],"items":{"oneOf":[{"examples":[[{"date_from":"2023-01-01","date_to":"2024-01-01","keywords":["rugby","cricket"],"location_name":"United States","type":"web"}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
if you don't specify this field, the current day and month of the preceding year will be used by default
minimal value for the web type: 2004-01-01
minimal value for other types: 2008-01-01
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"keywords":{"description":"keywords
required field
the maximum number of keywords you can specify: 5
avoid symbols and special characters (e.g., UTF symbols, emojis);
specifying non-Latin characters, you’ll get data for the countries where they are used
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"location_code":{"description":"search engine location code
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_code belongs to;
example:
2840","type":["integer","null"]},"location_name":{"description":"full name of search engine location
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_name belongs to;
example:
United Kingdom","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"time_range":{"description":"preset time ranges
optional field
if you specify date_from or date_to parameters, this field will be ignored when setting a task
possible values for all type parameters:
past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years","type":["string","null"]},"type":{"description":"type of element","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data dataforseo trends demography live"},{"name":"keywords_data_dataforseo_trends_explore_live","description":"This endpoint will provide you with the keyword popularity data from DataForSEO Trends. You can check keyword trends for Google Search, Google News, and Google Shopping.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["iphone 14","samsung s23"],"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keywords":["iphone 14","samsung s23"],"location_code":2840}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
if you don't specify this field, the current day and month of the preceding year will be used by default
minimal value for the web type: 2004-01-01
minimal value for other types: 2008-01-01
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"keywords":{"description":"keywords
required field
the maximum number of keywords you can specify: 5
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"location_code":{"description":"search engine location code
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_code belongs to;
example:
2840","type":["integer","null"]},"location_name":{"description":"full name of search engine location
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_name belongs to;
example:
United Kingdom","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"time_range":{"description":"preset time ranges
optional field
if you specify date_from or date_to parameters, this field will be ignored when setting a task
possible values for all type parameters:
past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years","type":["string","null"]},"type":{"description":"type of element","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data dataforseo trends explore live"},{"name":"keywords_data_dataforseo_trends_locations_country","description":"You will receive the list of DataForSEO Trends locations by calling this API. You can filter the list of locations by country when setting a task. Please note that the minimum geographic scope supported for the DataForSEO Trends API is country level.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data dataforseo trends locations country"},{"name":"keywords_data_dataforseo_trends_merged_data_live","description":"This endpoint will provide you with the keyword popularity data from DataForSEO Trends. In addition to keyword popularity rate over the given time range, you will get location-specific keyword popularity data, and a demographic breakdown of keyword popularity per each specified term along with comparative values.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2023-01-01","date_to":"2024-01-01","keywords":["rugby","cricket"],"location_name":"United States","type":"web"}]],"items":{"oneOf":[{"examples":[[{"date_from":"2023-01-01","date_to":"2024-01-01","keywords":["rugby","cricket"],"location_name":"United States","type":"web"}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
if you don't specify this field, the current day and month of the preceding year will be used by default
minimal value for the web type: 2004-01-01
minimal value for other types: 2008-01-01
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"keywords":{"description":"keywords
required field
the maximum number of keywords you can specify: 5
avoid symbols and special characters (e.g., UTF symbols, emojis);
specifying non-Latin characters, you’ll get data for the countries where they are used
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"location_code":{"description":"search engine location code
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_code belongs to;
example:
2840","type":["integer","null"]},"location_name":{"description":"full name of search engine location
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_name belongs to;
example:
United Kingdom","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"time_range":{"description":"preset time ranges
optional field
if you specify date_from or date_to parameters, this field will be ignored when setting a task
possible values for all type parameters:
past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years","type":["string","null"]},"type":{"description":"type of element","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data dataforseo trends merged data live"},{"name":"keywords_data_dataforseo_trends_subregion_interests_live","description":"This endpoint will provide you with location-specific keyword popularity data from DataForSEO Trends. You can check keyword trends for Google Search, Google News, and Google Shopping.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2023-01-01","date_to":"2024-01-01","keywords":["rugby","cricket"],"location_name":"United States","type":"web"}]],"items":{"oneOf":[{"examples":[[{"date_from":"2023-01-01","date_to":"2024-01-01","keywords":["rugby","cricket"],"location_name":"United States","type":"web"}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
if you don't specify this field, the current day and month of the preceding year will be used by default
minimal value for the web type: 2004-01-01
minimal value for other types: 2008-01-01
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"keywords":{"description":"keywords
required field
the maximum number of keywords you can specify: 5
avoid symbols and special characters (e.g., UTF symbols, emojis);
specifying non-Latin characters, you’ll get data for the countries where they are used
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"location_code":{"description":"search engine location code
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_code belongs to;
example:
2840","type":["integer","null"]},"location_name":{"description":"full name of search engine location
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_name belongs to;
example:
United Kingdom","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"time_range":{"description":"preset time ranges
optional field
if you specify date_from or date_to parameters, this field will be ignored when setting a task
possible values for all type parameters:
past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years","type":["string","null"]},"type":{"description":"type of element","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data dataforseo trends subregion interests live"},{"name":"keywords_data_google_ads_ad_traffic_by_keywords_live","description":"POST /v3/keywords_data/google_ads/ad_traffic_by_keywords/live","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"bid":999,"keywords":["seo marketing"],"language_code":"en","location_code":2840,"match":"exact"}]],"items":{"oneOf":[{"examples":[[{"bid":999,"keywords":["seo marketing"],"language_code":"en","location_code":2840,"match":"exact"}]],"properties":{"bid":{"description":"the maximum custom bid
required field
the collected data will be based on this value
it stands for the price you are willing to pay for an ad; the higher value you specify here, the higher values you will get in the returned metrics
learn more in this help center article","format":"int64","type":"integer"},"date_from":{"description":"starting date of the forecasting time range
required field if you specify date_to
if you indicate date_from and date_to, you don't need to specify date_interval
minimum value is tomorrow's date
the value you specify in date_from shouldn't be further than date_to
date format: \"yyyy-mm-dd\"
example:
\"2021-10-30\"if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior","type":"string"},"date_interval":{"description":"forecasting date interval
optional field
if you specify date_interval, you don't need to indicate date_from and date_to
possible values: next_week, next_month, next_quarter
default value: next_month","type":["string","null"]},"date_to":{"description":"ending date of the forecasting time range
required field if you specify date_from
if you indicate date_from and date_to, you don't need to specify date_interval
minimum value is date_from +1 day
maximum value is current day and month of the next year
date format: \"yyyy-mm-dd\"
example:
\"2022-10-30\"","type":"string"},"keywords":{"description":"keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the keywords you specify will be converted to a lowercase format
Note: Google Ads may return no data for certain groups of keywords
visit our Help Center to learn more
Also note that Google Ads doesn't allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can't use them when setting a task;
to learn more about which symbols and characters can be used, please refer to this article
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"search engine language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of search engine language
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:
English","type":["string","null"]},"location_code":{"description":"search engine location code
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_coordinate;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:
2840","type":["integer","null"]},"location_coordinate":{"description":"GPS coordinates of a location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_code;
location_coordinate parameter should be specified in the \"latitude,longitude\" format;
the data will be provided for the country the specified coordinates belong to;
example:
52.6178549,-155.352142","type":["string","null"]},"location_name":{"description":"full name of search engine location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:
London,England,United Kingdom","type":["string","null"]},"match":{"description":"keywords match-type
required field
can take the following values: exact, broad, phrase","type":"string"},"sort_by":{"description":"results sorting parameters
optional field
Use these parameters to sort the results by relevance, impressions, ctr, average_cpc, cost, or clicks in the descending order
default value: relevance","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data google ads ad traffic by keywords live"},{"name":"keywords_data_google_ads_keywords_for_keywords_live","description":"Note that Google Ads Keywords Data API is based on the latest version of the Google Ads API that has replaced legacy Google AdWords API. If you’re using DataForSEO Google AdWords API, you need to upgrade to DataForSEO Google Ads API.\n‌‌\nThis endpoint will provide relevant keywords for the specified terms. Set up to 20 keywords in the keywords array and get keyword suggestions from Google Ads.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["phone","cellphone"],"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keywords":["phone","cellphone"],"location_code":2840}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
date format: \"yyyy-mm-dd\"
minimal value: 4 years from the current date
by default, data is returned for the past 12 months;
Note: the indicated date cannot be greater than that specified in date_to and/or yesterday's date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
Note: the indicated date cannot be greater than yesterday's date;
if you don't specify this field, yesterday's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2022-11-30\"","type":["string","null"]},"include_adult_keywords":{"description":"include keywords associated with adult content
optional field
if set to true, adult keywords will be included in the response
default value: false
note that the API may return no data for such keywords due to Google Ads restrictions","type":["boolean","null"]},"keywords":{"description":"keywords
required field
The maximum number of keywords you can specify: 20
The maximum number of characters for each keyword: 80
the keywords you specify will be converted to a lowercase format
Note: Google Ads may return no data for certain groups of keywords
visit our Help Center to learn more
Also note that Google Ads doesn't allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can't use them when setting a task;
to learn more about which symbols and characters can be used, please refer to this article
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"search engine language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of search engine language
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:
English","type":["string","null"]},"location_code":{"description":"search engine location code
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_coordinate;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:
2840","type":["integer","null"]},"location_coordinate":{"description":"GPS coordinates of a location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_code;
location_coordinate parameter should be specified in the \"latitude,longitude\" format;
the data will be provided for the country the specified coordinates belong to;
example:
52.6178549,-155.352142","type":["string","null"]},"location_name":{"description":"full name of search engine location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:
London,England,United Kingdom","type":["string","null"]},"search_partners":{"description":"include Google search partners
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search;
default value: false - results are returned for Google search sites","type":["boolean","null"]},"sort_by":{"description":"results sorting parameters
optional field
Use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in descending order
default value: relevance","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data google ads keywords for keywords live"},{"name":"keywords_data_google_ads_keywords_for_site_live","description":"Note that Google Ads Keywords Data API is based on the latest version of the Google Ads API that has replaced legacy Google AdWords API. If you’re using DataForSEO Google AdWords API, you need to upgrade to DataForSEO Google Ads API.\n‌‌\nThis endpoint will provide you with a list of keywords relevant to the specified domain along with their bids, search volumes for the last month, search volume trends for the last year (for estimating search volume dynamics), and competition levels.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"location_code":2840,"target":"dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"location_code":2840,"target":"dataforseo.com"}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
date format: \"yyyy-mm-dd\"
minimal value: 4 years from the current date
by default, data is returned for the past 12 months;
Note: the indicated date cannot be greater than that specified in date_to and/or yesterday's date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
Note: the indicated date cannot be greater than yesterday's date;
if you don't specify this field, yesterday's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2022-11-30\"","type":["string","null"]},"include_adult_keywords":{"description":"include keywords associated with adult content
optional field
if set to true, adult keywords will be included in the response
default value: false
note that the API may return no data for such keywords due to Google Ads restrictions","type":["boolean","null"]},"language_code":{"description":"search engine language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of search engine language
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:
English","type":["string","null"]},"location_code":{"description":"search engine location code
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_coordinate;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:
2840","type":["integer","null"]},"location_coordinate":{"description":"GPS coordinates of a location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_code;
location_coordinate parameter should be specified in the \"latitude,longitude\" format;
the data will be provided for the country the specified coordinates belong to;
example:
52.6178549,-155.352142","type":["string","null"]},"location_name":{"description":"full name of search engine location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:
London,England,United Kingdom","type":["string","null"]},"search_partners":{"description":"include Google search partners
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search;
default value: false - results are returned for Google search sites","type":["boolean","null"]},"sort_by":{"description":"results sorting parameters
optional field
Use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in descending order
default value: relevance","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain or page
required field
the domain name of the target website or the url of the target page;
note: to obtain keywords for the target website, use the target_type parameter","type":"string"},"target_type":{"description":"search keywords for site or for url
optional field
possible values: site, page;
default value: page;
if set to site, keywords will be provided for the entire site;
if set to page, keywords will be provided for the specified webpage","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data google ads keywords for site live"},{"name":"keywords_data_google_ads_locations_country","description":"‌\nWe use Google Geographical Targeting. You can refer to Google Ads Target Types page to review the full list of possible location types. With Keywords Data API, you can select any location type supported by Google, except for “Okrug”.\nPostal Codes can be used to set a task, albeit API response will not return data for such tasks.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code\noptional field\nspecify the ISO code if you want to filter the list of locations by country\nexample:\nus","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data google ads locations country"},{"name":"keywords_data_google_trends_explore_live","description":"This endpoint will provide you with the keyword popularity data from the ‘Explore’ feature of Google Trends. You can check keyword trends for Google Search, Google News, Google Images, Google Shopping, and YouTube.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"category_code":3,"date_from":"2019-01-01","date_to":"2020-01-01","keywords":["rugby","cricket"],"location_name":"United States","type":"youtube"}]],"items":{"oneOf":[{"examples":[[{"category_code":3,"date_from":"2019-01-01","date_to":"2020-01-01","keywords":["rugby","cricket"],"location_name":"United States","type":"youtube"}]],"properties":{"category_code":{"description":"google trends search category
required field if you don't specify `keywords`
if you don't specify `keywords`, the value of this field must be greater than `0`
if you specify `keywords` and don't specify this field, the 0 value will be applied by default and the search will be carried out across all available categories
you can receive the list of available categories with their category_code by making a separate request to the https://api.dataforseo.com/v3/keywords_data/google_trends/categories","type":"integer"},"date_from":{"description":"starting date of the time range
optional field
if you don't specify this field, the current day and month of the preceding year will be used by default
minimal value for the web type: 2004-01-01
minimal value for other types: 2008-01-01
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2019-01-15\"","type":["string","null"]},"item_types":{"description":"types of items returned
optional field
to speed up the execution of the request, specify one item at a time;
possible values:
\"google_trends_graph\", \"google_trends_map\", \"google_trends_topics_list\",\"google_trends_queries_list\"
default value:
\"google_trends_graph\"
Note: to obtain google_trends_topics_list and google_trends_queries_list items, specify no more than 1 keyword in the keywords field","items":{"type":"string"},"type":["array","null"]},"keywords":{"description":"keywords
required field if you don't specify `category_code`
the maximum number of keywords you can specify: 5
the maximum number of characters you can specify in a keyword: 100
the minimum number of characters must be greater than 1
comma characters (,) in the specified keywords will be unset and ignored
Note: keywords cannot consist of a combination of the following characters: < > | \" - + = ~ ! : * ( ) [ ] { }
Note: to obtain google_trends_topics_list and google_trends_queries_list items, specify no more than 1 keyword
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"search engine language code
optional field
default value: en
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_trends/languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of search engine language
optional field
default value: English
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_trends/languages
example:
English","type":["string","null"]},"location_code":{"description":"search engine location code
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_name
you can use this field as an array to set several locations, each corresponding to a specific keyword - learn more;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_trends/locations
example:
2840","type":["string","null"]},"location_name":{"description":"full name of search engine location
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_code
you can use this field as an array to set several locations, each corresponding to a specific keyword - learn more;
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_trends/locations
example:
United Kingdom","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"time_range":{"description":"preset time ranges
optional field
if you specify date_from or date_to parameters, this field will be ignored when setting a task
possible values for all type parameters:
past_hour, past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years
possible values for web only:
2004_present
possible values for news, youtube, images, froogle:
2008_present","type":["string","null"]},"type":{"description":"type of element","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data google trends explore live"},{"name":"keywords_data_google_trends_locations_country","description":"‌","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Keywords data google trends locations country"},{"name":"labs_amazon_bulk_search_volume_live","description":"‌\nThis endpoint will provide you with search volume values for a maximum of 1,000 keywords in one API request. Here search volume represents the approximate number of monthly searches for a keyword on Amazon. The returned results are specific to the keywords, location, and language parameters specified in a POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["buy laptop","cheap laptops for sale","purchase laptop"],"language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keywords":["buy laptop","cheap laptops for sale","purchase laptop"],"language_code":"en","location_code":2840}]],"properties":{"keywords":{"description":"target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000;
the keywords will be converted to lowercase format
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"language code
required field if don't specify language_name
you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
Note: this endpoint currently supports these locations and languages only;
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if don't specify language_code
you can receive the list of available languages with their language_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
Note: this endpoint currently supports these locations and languages only;
example:
English","type":"string"},"location_code":{"description":"location code
required field if don't specify location_name
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports these locations and languages only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if don't specify location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;

Note: this endpoint currently supports the following locations and languages only:
Australia - 2036, en
Austria - 2040, de
Canada - 2124, en
Egypt - 2818, ar
France - 2250, fr
Germany - 2276, de
India - 2356, en
Italy - 2380, it
Mexico - 2484, es
Netherlands - 2528, nl
Saudi Arabia - 2682, ar
Singapore - 2702, en
Spain - 2724, es
United Arab Emirates - 2784, ar
United Kingdom - 2826, en
United States - 2840, en
example:
United States","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs amazon bulk search volume live"},{"name":"labs_amazon_product_competitors_live","description":"‌\nThis endpoint will provide you with a list of products that intersect with a target asin in Amazon SERPs. The data can help you identify product competitors for any listing published on Amazon. The returned results are specific to the asin as well as the location and language parameters specified in a POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"asin":"019005476X","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"asin":"019005476X","language_code":"en","location_code":2840}]],"properties":{"asin":{"description":"product ID
required field
unique product identifier (ASIN) on Amazon;
you can receive the asin parameter by making a separate request to the Amazon Products endpoint","type":"string"},"filters":{"description":"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, ilike, not_ilike, like, not_like, match, not_match
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:
[\"full_metrics.amazon_serp.pos_1\",\">\", 20]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"language_code":{"description":"language code
required field if don't 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
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if don't 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
example:
English","type":"string"},"limit":{"description":"the maximum number of products in the results array
optional field
default value: 100;
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if don't specify location_name
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if don't specify location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:
United States","type":"string"},"offset":{"description":"offset in the results array of returned product competitors
optional field
default value: 0
if you specify the 10 value, the first ten product competitors in the results array will be omitted and the data will be provided for the successive product competitors","type":["integer","null"]},"order_by":{"description":"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 parameter
example:
[\"full_metrics.amazon_serp.pos_1,desc\"]
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:
[\"full_metrics.amazon_serp.pos_1,desc\",\"avg_position,desc\"]
default rule:
[\"ranked_serp_element.serp_item.rank_group,asc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs amazon product competitors live"},{"name":"labs_amazon_product_keyword_intersections_live","description":"‌\nThis endpoint will provide you with a list of keywords for which the target products intersect in Amazon SERP. The returned results are specific to the asins specified in a POST request. Learn more about ASIN in this help center article.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"asins":{"1":"B09172433Z","2":"B07GBZ4Q68","3":"B07GCKQD77"},"language_name":"English","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"asins":{"1":"B09172433Z","2":"B07GBZ4Q68","3":"B07GCKQD77"},"language_name":"English","location_code":2840}]],"properties":{"asins":{"additionalProperties":{"type":["string","null"]},"description":"asins of target products
required field
product IDs of the products for which you need to find keyword intersections;
specify the ASINs as in the following example:
\"asins\": { \"1\": \"019005476X\", \"2\": \"0190074442\" }
the maximum number of ASINs you can specify in this object is 20;
learn more about the parameter on this help center page","type":["object","null"]},"filters":{"description":"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, ilike, not_ilike, like, not_like, match, not_match
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:
[\"avg_position\",\"<\", 10]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"intersection_mode":{"description":"mode for finding asin intersections
optional field
possible values: union, intersect;
default value: intersect;
learn more about the parameter in this help center guide","type":["string","null"]},"language_code":{"description":"language code
required field if don't 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
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if don't 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
example:
English","type":"string"},"limit":{"description":"the maximum number of products in the results array
optional field
default value: 100;
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if don't specify location_name
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if don't specify location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:
United Kingdom","type":"string"},"offset":{"description":"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","type":["integer","null"]},"order_by":{"description":"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 parameter
example:
[\"sum_position,desc\"]
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:
[\"intersections,desc\",\"avg_position,asc\"]
default rule:
[\"intersections,desc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs amazon product keyword intersections live"},{"name":"labs_amazon_product_rank_overview_live","description":"‌\nThis endpoint will provide you with ranking data from organic and paid Amazon SERPs for the target products. The returned results are specific to the asins specified in a POST request. Learn more about ASIN in this help center article.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"asins":["B001TJ3HUG","B01LW2SL7R"],"language_name":"English","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"asins":["B001TJ3HUG","B01LW2SL7R"],"language_name":"English","location_code":2840}]],"properties":{"asins":{"description":"product IDs to compare
required field
product IDs to receive ranking data for;
the maximum number of ASINs you can specify in this array is 1000;
you can receive the asin parameter by making a separate request to the Amazon Products endpoint
Note: all letters in ASIN code must be specified in uppercase format;
example:
B01LW2SL7R","items":{"type":"string"},"type":"array"},"language_code":{"description":"language code
required field if don't 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
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if don't 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
example:
English","type":"string"},"location_code":{"description":"location code
required field if don't specify location_name
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if don't specify location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:
United States","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs amazon product rank overview live"},{"name":"labs_amazon_ranked_keywords_live","description":"‌\nThis endpoint will provide you with a list of keywords the target product ranks for on Amazon. The returned results are specific to the asin specified in a POST request. Learn more about ASIN in this help center article.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"asin":"B00R92CL5E","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"asin":"B00R92CL5E","language_code":"en","location_code":2840}]],"properties":{"asin":{"description":"product ID
required field
unique product identifier (ASIN) on Amazon;
you can receive the asin parameter by making a separate request to the Amazon Products endpoint","type":"string"},"filters":{"description":"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, like, not_like, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"keyword_data.keyword_info.search_volume\",\"in\",[100,1000]];
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"ignore_synonyms":{"description":"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","type":["boolean","null"]},"language_code":{"description":"language code
required field if don't 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
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if don't 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
example:
English","type":"string"},"limit":{"description":"the maximum number of products in the results array
optional field
default value: 100;
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if don't specify location_name
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if don't specify location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:
United States","type":"string"},"offset":{"description":"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","type":["integer","null"]},"order_by":{"description":"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 parameter
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\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs amazon ranked keywords live"},{"name":"labs_amazon_related_keywords_live","description":"‌‌\nThe Related Keywords endpoint provides keywords appearing in the “Related Searches” section on Amazon.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"include_seed_keyword":true,"keyword":"computer mouse","language_name":"English","limit":5,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"include_seed_keyword":true,"keyword":"computer mouse","language_name":"English","limit":5,"location_code":2840}]],"properties":{"depth":{"description":"keyword search depth
optional field
default value: 1;
number of the returned results depends on the value you set in this field;
you can specify a level from 0 to 4;
estimated number of keywords for each level (maximum):
0 - the keyword set in the keyword field
1 – 6 keywords
2 – 42 keywords
3 – 258 keywords
4 – 1554 keywords","type":["integer","null"]},"ignore_synonyms":{"description":"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: falsen","type":["boolean","null"]},"include_seed_keyword":{"description":"include data for the seed keyword
optional field
if set to true, data for the seed keyword specified in the keyword field will be provided in the seed_keyword_data array of the response
default value: false","type":["boolean","null"]},"keyword":{"description":"keyword
required field
UTF-8 encoding
the keywords should be specified in the lowercase format
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
English","type":"string"},"limit":{"description":"the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:
United States","type":"string"},"offset":{"description":"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","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs amazon related keywords live"},{"name":"labs_apple_app_competitors_live","description":"‌\nThis endpoint will provide you with a list of mobile applications that intersect with the target app for its ranking keywords on App Store. You will obtain the IDs of competitor apps along with search volume and ranking data on competitor ranking keywords.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_id":"686449807","language_name":"English","limit":10,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_id":"686449807","language_name":"English","limit":10,"location_code":2840}]],"properties":{"app_id":{"description":"id of the app
required field
ID of the mobile application on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL https://apps.apple.com/us/app/id835599320
the id is 835599320","type":"string"},"filters":{"description":"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:
<, <=, >, >=, =, <>, in, not_in
example:
[\"intersections\",\">\",500]
[[\"competitor_metrics.app_store_search_organic.pos_1\",\"<>\",10],\"and\",[\"avg_position\",\">=\",\"10\"]]
[[[\"intersections\",\">=\",50],\"and\",[\"competitor_metrics.app_store_search_organic.pos_1\",\"in\",[1,5]]], \"or\", [\"sum_position\",\">=\",\"10000\"]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
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;
Note: this endpoint currently supports the English language only
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or 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;
Note: this endpoint currently supports the English language only;
example:
English","type":"string"},"limit":{"description":"the maximum number of returned apps
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
United States","type":"string"},"offset":{"description":"offset in the results array of returned apps
optional field
default value: 0
if you specify the 10 value, the first ten apps in the results array will be omitted and the data will be provided for the successive keywords","type":["integer","null"]},"order_by":{"description":"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 specify a sorting type;
example:
[\"intersections,asc\"]
Note: you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:
[\"intersections,desc\",\"sum_position,asc\"]
default rule:
[\"intersections,desc\"]
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","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs apple app competitors live"},{"name":"labs_apple_app_intersection_live","description":"‌\nThis endpoint will provide you with a list of keywords for which the mobile applications specified in the app_ids object rank within the same App Store SERP.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_ids":{"1":"686449807","2":"382617920"},"language_name":"English","limit":10,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_ids":{"1":"686449807","2":"382617920"},"language_name":"English","limit":10,"location_code":2840}]],"properties":{"app_ids":{"additionalProperties":{"type":["string","null"]},"description":"ids of the target apps
required field
IDs of the target mobile applications on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL https://apps.apple.com/us/app/id835599320
the id is 835599320;
the ids should be specified the following way:
`\"app_ids\": {
\"1\": \"686449807\",
\"2\": \"382617920\"
}`
if you specify a single ID here, the API will return results only for one application;
the maximum number of app IDs you can specify in this object is 20","type":["object","null"]},"filters":{"description":"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:
<, <=, >, >=, =, <>, in, not_in
example:
[\"keyword_data.keyword_info.search_volume\",\">\",500]
[[\"keyword_data.keyword_info.search_volume\",\"<>\",500],\"and\",[intersection_result.382617920.rank_group\",\">=\",\"10\"]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
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;
Note: this endpoint currently supports the English language only
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or 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;
Note: this endpoint currently supports the English language only;
example:
English","type":"string"},"limit":{"description":"the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
United States","type":"string"},"offset":{"description":"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","type":["integer","null"]},"order_by":{"description":"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 specify a sorting type;
example:
[\"intersection_result.382617920.rank_absolute,asc\"]
Note: you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:
[\"intersection_result.382617920.rank_absolute,desc\",\"keyword_data.keyword_info.search_volume,asc\"]
default rule:
[\"keyword_data.keyword_info.search_volume,desc\"]
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","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs apple app intersection live"},{"name":"labs_apple_bulk_app_metrics_live","description":"‌\nThis endpoint will provide you with ranking metrics for up to 1000 App Store applications.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_ids":["686449807","382617920"],"language_name":"English","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_ids":["686449807","382617920"],"language_name":"English","location_code":2840}]],"properties":{"app_ids":{"description":"ids of the apps
required field
IDs of mobile applications on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL https://apps.apple.com/us/app/id835599320
the id is 835599320;
the maximum number of IDs you can specify in this field is 1000","items":{"type":"string"},"type":"array"},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
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;
Note: this endpoint currently supports the English language only
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or 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;
Note: this endpoint currently supports the English language only;
example:
English","type":"string"},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
United States","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs apple bulk app metrics live"},{"name":"labs_apple_keywords_for_app_live","description":"‌\nThis endpoint will provide you with a list of keywords for which the target app ranks on App Store. You will obtain keyword data and discover the app’s ranking position for each returned keyword.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_id":"686449807","language_name":"English","limit":10,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_id":"686449807","language_name":"English","limit":10,"location_code":2840}]],"properties":{"app_id":{"description":"id of the app
required field
ID of the mobile application on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL https://apps.apple.com/us/app/id835599320
the id is 835599320","type":"string"},"filters":{"description":"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:
<, <=, >, >=, =, <>, in, not_in
example:
[\"keyword_data.keyword_info.search_volume\",\">\",500]
[[\"keyword_data.keyword_info.search_volume\",\"<>\",500],\"and\",[\"ranked_serp_element.serp_item.rank_group\",\">=\",\"10\"]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
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;
Note: this endpoint currently supports the English language only
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or 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;
Note: this endpoint currently supports the English language only;
example:
English","type":"string"},"limit":{"description":"the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
United States","type":"string"},"offset":{"description":"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","type":["integer","null"]},"order_by":{"description":"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 specify a sorting type;
example:
[\"ranked_serp_element.serp_item.rank_group,asc\"]
Note: you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:
[\"ranked_serp_element.serp_item.rank_group,desc\",\"keyword_data.keyword_info.search_volume,asc\"]
default rule:
[\"keyword_data.keyword_info.search_volume,desc\"]
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","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs apple keywords for app live"},{"name":"labs_google_app_competitors_live","description":"‌\nThis endpoint will provide you with a list of mobile applications that intersect with the target app for its ranking keywords on Google Play. You will obtain the IDs of competitor apps along with search volume and ranking data on competitor ranking keywords.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_id":"org.telegram.messenger","language_name":"English","limit":10,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_id":"org.telegram.messenger","language_name":"English","limit":10,"location_code":2840}]],"properties":{"app_id":{"description":"id of the app
required field
ID of the mobile application on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:
in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger
the id is org.telegram.messenger","type":"string"},"filters":{"description":"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:
<, <=, >, >=, =, <>, in, not_in
example:
[\"intersections\",\">\",500]
[[\"competitor_metrics.google_play_search_organic.pos_1\",\"<>\",10],\"and\",[\"avg_position\",\">=\",\"10\"]]
[[[\"intersections\",\">=\",50],\"and\",[\"competitor_metrics.google_play_search_organic.pos_1\",\"in\",[1,5]]], \"or\", [\"sum_position\",\">=\",\"10000\"]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
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;
Note: this endpoint currently supports the English language only
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or 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;
Note: this endpoint currently supports the English language only;
example:
English","type":"string"},"limit":{"description":"the maximum number of returned apps
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
United States","type":"string"},"offset":{"description":"offset in the results array of returned apps
optional field
default value: 0
if you specify the 10 value, the first ten apps in the results array will be omitted and the data will be provided for the successive keywords","type":["integer","null"]},"order_by":{"description":"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 specify a sorting type;
example:
[\"intersections,asc\"]
Note: you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:
[\"intersections,desc\",\"sum_position,asc\"]
default rule:
[\"intersections,desc\"]
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","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google app competitors live"},{"name":"labs_google_app_intersection_live","description":"‌\nThis endpoint will provide you with a list of keywords for which the mobile applications specified in the app_ids object rank within the same Google Play SERP.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_ids":{"1":"686449807","2":"382617920"},"language_name":"English","limit":10,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_ids":{"1":"686449807","2":"382617920"},"language_name":"English","limit":10,"location_code":2840}]],"properties":{"app_ids":{"additionalProperties":{"type":["string","null"]},"description":"ids of the target apps
required field
IDs of the target mobile applications on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:
in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger
the id is org.telegram.messenger;;
the ids should be specified the following way:
\"app_ids\": { \"1\": \"org.telegram.messenger\", \"2\": \"com.zhiliaoapp.musically\" }
if you specify a single ID here, the API will return results only for one application;
the maximum number of app IDs you can specify in this object is 20","type":["object","null"]},"filters":{"description":"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:
<, <=, >, >=, =, <>, in, not_in
example:
[\"keyword_data.keyword_info.search_volume\",\">\",500]
[[\"keyword_data.keyword_info.search_volume\",\"<>\",500],\"and\",[intersection_result.382617920.rank_group\",\">=\",\"10\"]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
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;
Note: this endpoint currently supports the English language only
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or 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;
Note: this endpoint currently supports the English language only;
example:
English","type":"string"},"limit":{"description":"the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
United States","type":"string"},"offset":{"description":"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","type":["integer","null"]},"order_by":{"description":"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 specify a sorting type;
example:
[\"intersection_result.382617920.rank_absolute,asc\"]
Note: you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:
[\"intersection_result.382617920.rank_absolute,desc\",\"keyword_data.keyword_info.search_volume,asc\"]
default rule:
[\"keyword_data.keyword_info.search_volume,desc\"]
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","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google app intersection live"},{"name":"labs_google_available_history","description":"By calling this endpoint, you will find obtain a list of dates available for setting in the first_date and second_date fields of the Domain Metrics by Categories endpoint.\nfor more info please visit 'https://docs.dataforseo.com/v3/dataforseo_labs/google/available_history/live/?bash'","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google available history"},{"name":"labs_google_bulk_app_metrics_live","description":"‌\nThis endpoint will provide you with ranking metrics for up to 1000 Google Play applications.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_ids":["org.telegram.messenger","com.zhiliaoapp.musically"],"language_name":"English","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_ids":["org.telegram.messenger","com.zhiliaoapp.musically"],"language_name":"English","location_code":2840}]],"properties":{"app_ids":{"description":"ids of the app
required field
IDs of the mobile applications on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:
in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger
the id is org.telegram.messenger;
the maximum number of IDs you can specify in this field is 1000","items":{"type":"string"},"type":"array"},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
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;
Note: this endpoint currently supports the English language only
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or 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;
Note: this endpoint currently supports the English language only;
example:
English","type":"string"},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
United States","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google bulk app metrics live"},{"name":"labs_google_bulk_keyword_difficulty_live","description":"This endpoint will provide you with the Keyword Difficulty metric for a maximum of 1,000 keywords in one API request. Keyword Difficulty stands for the relative difficulty of ranking in the first top-10 organic results for the related keyword. Keyword Difficulty in DataForSEO API responses indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["dentist new york","pizza brooklyn","car dealer los angeles"],"language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keywords":["dentist new york","pizza brooklyn","car dealer los angeles"],"language_code":"en","location_code":2840}]],"properties":{"keywords":{"description":"target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000
the keywords will be converted to lowercase format
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"language code
required field if don't 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
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if don't 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
example:
English","type":"string"},"location_code":{"description":"location code
required field if don't 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
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if don't 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
example:
United Kingdom","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google bulk keyword difficulty live"},{"name":"labs_google_bulk_traffic_estimation_live","description":"‌\nThis endpoint will provide you with estimated monthly traffic volumes for up to 1,000 domains, subdomains, or webpages. Along with organic search traffic estimations, you will also get separate values for paid search, featured snippet, and local pack results.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"item_types":["organic","paid"],"language_code":"en","location_code":2840,"targets":["dataforseo.com","cnn.com","forbes.com"]}]],"items":{"oneOf":[{"examples":[[{"item_types":["organic","paid"],"language_code":"en","location_code":2840,"targets":["dataforseo.com","cnn.com","forbes.com"]}]],"properties":{"ignore_synonyms":{"description":"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","type":["boolean","null"]},"item_types":{"description":"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
possible values:
[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]
default value:
[\"organic\", \"paid\"]","items":{"type":"string"},"type":["array","null"]},"language_code":{"description":"language code
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","type":["string","null"]},"language_name":{"description":"full name of the language
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","type":["string","null"]},"location_code":{"description":"location code
if you use this field, you don't have 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","type":["integer","null"]},"location_name":{"description":"full name of the location
if you use this field, you don't have 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","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"targets":{"description":"target domains, subdomains, and webpages
required field
you can specify domains, subdomains, and webpages in this field;
domains and subdomains should be specified without https:// and www.;
pages should be specified with absolute URL, including https:// and www.;
you can set up to 1000 domains, subdomains or webpages","items":{"type":"string"},"type":"array"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google bulk traffic estimation live"},{"name":"labs_google_categories_for_domain_live","description":"‌\nThis endpoint will provide you with Google product or service categories that include keywords the domain ranks for in search. Furthermore, you will obtain general rankings and traffic data for the keywords under a certain category.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"item_types":["paid","organic","featured_snippet","local_pack"],"language_code":"en","limit":3,"location_name":"United States","target":"dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"item_types":["paid","organic","featured_snippet","local_pack"],"language_code":"en","limit":3,"location_name":"United States","target":"dataforseo.com"}]],"properties":{"filters":{"description":"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
example:
[\"metrics.organic.pos_1,\">\",0]
[[[\"metrics.organic.count\",\">=\",100],\"and\",[\"metrics.organic.pos_1\",\">\",0]], \"or\", [\"metrics.organic.etv\",\"in\",[10,100]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"historical_serp_mode":{"description":"data collection mode
optional field
you can use this field to filter the results;
possible types of filtering:
live — return metrics for SERPs in which the specified target currently has ranking results;
lost — return metrics for SERPs in which the specified target had previously had ranking results, but didn't have them during the last check;
all — return metrics for both types of SERPs.
default value: live","type":["string","null"]},"include_clickstream_data":{"description":"include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to_true, you will receive clickstream_etv, clickstream_gender_distribution, and_clickstream_age_distribution_fields with clickstream data 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 articlen","type":["boolean","null"]},"include_subcategories":{"description":"indicates if the subcategories will be included in the search
optional field
if set to false, the subcategories will be ignored
default value: false
learn more about the parameter in this help center article","type":["boolean","null"]},"item_types":{"description":"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 the organic object, 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\"]
default value:
[\"organic\", \"paid\"]","items":{"type":"string"},"type":["array","null"]},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
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
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or 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
example:
English","type":"string"},"limit":{"description":"the maximum number of returned categories
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
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
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or 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
example:
United Kingdom","type":"string"},"offset":{"description":"offset in the results array of returned categories
optional field
default value: 0
if you specify the 10 value, the first ten categories in the results array will be omitted and the data will be provided for the successive categories","type":["integer","null"]},"order_by":{"description":"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 specify a sorting type
example:
[\"metrics.paid.etv,asc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:
[\"metrics.organic.etv,desc\",\"metrics.paid.count,asc\"]
default rule:
[\"metrics.organic.count,desc\"]
Note: if the item_types array contains item types that are different from the organic object, the results will be ordered by the first item type in the array","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain or subdomain
required field
the domain or subdomain name of the target website
the domain or subdomain should be specified without https:// and www.","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google categories for domain live"},{"name":"labs_google_categories_for_keywords_live","description":"This endpoint will provide you with Google product and service categories related for each specified keyword. You can indicate a maximum of 1,000 keywords in one API request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["dentist new york","pizza brooklyn","car dealer los angeles"],"language_code":"en"}]],"items":{"oneOf":[{"examples":[[{"keywords":["dentist new york","pizza brooklyn","car dealer los angeles"],"language_code":"en"}]],"properties":{"keywords":{"description":"target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000
the keywords will be converted to lowercase format
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"language code
required field if don't 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/google/categories_for_keywords/languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if don't 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/google/categories_for_keywords/languages
example:
English","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google categories for keywords live"},{"name":"labs_google_competitors_domain_live","description":"‌\nThis endpoint will provide you with a full overview of ranking and traffic data of the competitor domains from organic and paid search. In addition to that, you will get the metrics specific to the keywords both competitor domains and your domain rank for within the same SERP.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"intersecting_domains":["dentaly.org","health.com","trysnow.com"],"language_name":"English","limit":3,"location_code":2840,"target":"newmouth.com"}]],"items":{"oneOf":[{"examples":[[{"intersecting_domains":["dentaly.org","health.com","trysnow.com"],"language_name":"English","limit":3,"location_code":2840,"target":"newmouth.com"}]],"properties":{"exclude_domains":{"description":"exclude domains from the results
optional field
use this parameter to exclude specific domains from the results
Note: you can specify up to 1000 domains in this array
example:
\"exclude_domains\": [ \"reddit.com\", \"youtube.com\" ]","items":{"type":"string"},"type":["array","null"]},"exclude_top_domains":{"description":"indicates whether to exclude world's largest websites
optional field
default value: false
set to true if you want to get highly-relevant competitors excluding the websites listed below:
wikipedia.org pinterest.com amazon.com google.com facebook.com wordpress.com medium.com quora.com reddit.com youtube.com ebay.com uol.com.br instagram.com olx.com twitter.com linkedin.com slideshare.net","type":["boolean","null"]},"filters":{"description":"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
example:
[\"metrics.organic.count\",\">\",50]
[[[\"metrics.organic.count\",\">=\",50],\"and\",[\"metrics.organic.pos_1\",\"in\",[1,5]]], \"or\", [\"metrics.organic.etv\",\">=\",\"100\"]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"ignore_synonyms":{"description":"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: falsen","type":["boolean","null"]},"include_clickstream_data":{"description":"include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to_true, you will receive clickstream_etv, clickstream_gender_distribution, and_clickstream_age_distribution_fields with clickstream data 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 articlen","type":["boolean","null"]},"intersecting_domains":{"description":"additional domains for improving results accuracy
optional field
to improve the accuracy of the result, you can specify domains that are known to intersect with the target in SERPs;
if you use this array, metrics in the result will be based on SERPs where both target website and intersecting_domains appear;
Note: you can specify up to 20 domains in this array","items":{"type":"string"},"type":["array","null"]},"item_types":{"description":"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\"]
default value:
[\"organic\", \"paid\"]","items":{"type":"string"},"type":["array","null"]},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
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
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or 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
example:
English","type":"string"},"limit":{"description":"the maximum number of returned domains
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
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
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or 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
example:
United Kingdom","type":"string"},"max_rank_group":{"description":"maximum rank up to which competitors will be considered
optional field
default value: 100
if you specify 10 here, we will extract competitors from the top 10 Google search results only","type":["integer","null"]},"offset":{"description":"offset in the results array of returned domains
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","type":["integer","null"]},"order_by":{"description":"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 specify a sorting type
example:
[\"metrics.paid.etv,asc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:
[\"metrics.organic.etv,desc\",\"metrics.paid.count,asc\"]
default rule:
[\"metrics.organic.count,desc\"]
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","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain
required field
the domain name of the target website
the domain should be specified without https:// and www.
you can specify page URL, but the results will be specific to the domain in the specified URL","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google competitors domain live"},{"name":"labs_google_domain_intersection_live","description":"This endpoint will provide you with the keywords for which both specified domains rank within the same SERP. You will get search volume, competition, cost-per-click and other data on each intersecting keyword. Along with that, you will get data on the first and second domain’s SERP element discovered for this keyword, as well as the estimated traffic volume and cost of ad traffic. Domain Intersection endpoint supports organic, paid, local pack, and featured snippet results.\nfor more info please visit 'https://docs.dataforseo.com/v3/dataforseo_labs/google/domain_intersection/live/?bash'","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"include_serp_info":true,"language_code":"en","limit":3,"location_code":2840,"target1":"mom.com","target2":"quora.com"}]],"items":{"oneOf":[{"examples":[[{"include_serp_info":true,"language_code":"en","limit":3,"location_code":2840,"target1":"mom.com","target2":"quora.com"}]],"properties":{"filters":{"description":"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: [\"keyword_data.keyword_info.search_volume\",\"in\",[100,1000]] [[\"first_domain_serp_element.etv\",\">\",0],\"and\",[\"first_domain_serp_element.description\",\"like\",\"%goat%\"]] [[\"keyword_data.keyword_info.search_volume\",\">\",100], \"and\", [[\"first_domain_serp_element.description\",\"like\",\"%goat%\"], \"or\", [\"second_domain_serp_element.type\",\"=\",\"organic\"]]] for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"include_clickstream_data":{"description":"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, 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","type":["boolean","null"]},"include_serp_info":{"description":"include data from SERP for each keyword optional field if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response default value: false","type":["boolean","null"]},"intersections":{"description":"domain intersections in SERP optional field if you set intersections to true, you will get the keywords for which both target domains specified as target1 and target2 have results within the same SERP; the corresponding SERP elements for both domains will be provided in the results array Note: this endpoint will not provide results if the number of intersecting keywords exceeds 10 million if you specify intersections: false, you will get the keywords for which the domain specified as target1 has results in SERP, and the domain specified as target2 doesn't; thus, the corresponding SERP elements and other data will be provided for the domain specified as target1only default value: true","type":["boolean","null"]},"item_types":{"description":"search results type indicates type of search results included in the response optional field possible values: [\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"] default value: [\"organic\", \"paid\"]","items":{"type":"string"},"type":["array","null"]},"language_code":{"description":"language code required field if you don't specify language_name Note: it is required to specify either language_name or language_code 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 example: en","type":["string","null"]},"language_name":{"description":"full name of the language required field if you don't specify language_code Note: it is required to specify either language_name or 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 example: English","type":["string","null"]},"limit":{"description":"the maximum number of returned keywords optional field default value: 100 maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code required field if you don't specify location_name Note: it is required to specify either location_name or location_code 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 example: 2840","type":["integer","null"]},"location_name":{"description":"full name of the location required field if you don't specify location_code Note: it is required to specify either location_name or 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 example: United Kingdom","type":["string","null"]},"offset":{"description":"offset in the items 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","type":["integer","null"]},"order_by":{"description":"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 parameter example: [\"keyword_data.keyword_info.competition,desc\"] default rule: [\"keyword_data.keyword_info.search_volume,desc\"] 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\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"target1":{"description":"domain required field the domain name of the first target website the domain should be specified without https:// and www.","type":"string"},"target2":{"description":"domain required field the domain name of the second target website the domain should be specified without https:// and www.","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google domain intersection live"},{"name":"labs_google_domain_metrics_by_categories_live","description":"‌\nThis endpoint will provide you with dynamics of change in metrics of domains relevant to the specified product and service categories. You will receive historical ranking data from Google SERPs, along with valuable current and historical domain metrics, such as ETV, impressions ETV, estimated paid traffic cost, the total count of SERPs that contain domains, and more.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"category_codes":["13418","11494"],"first_date":"2021-06-01","language_code":"en","limit":3,"location_code":2840,"second_date":"2021-10-01"}]],"items":{"oneOf":[{"examples":[[{"category_codes":["13418","11494"],"first_date":"2021-06-01","language_code":"en","limit":3,"location_code":2840,"second_date":"2021-10-01"}]],"properties":{"category_codes":{"description":"product and service categories
required field
The maximum number of categories you can specify: 5
you can download the full list of possible categories","items":{"type":"string"},"type":"array"},"correlate":{"description":"correlate data with previously obtained datasets
optional field
default value: true;
if you use this parameter, our system will correlate data you obtain now with previously obtained datasets;
this parameter is intended to mitigate any inconsistencies that may result from changes to our database;
Note: we do not recommend setting correlate to false","type":["boolean","null"]},"etv_max":{"description":"maximum current organic ETV of the domain
optional field
if specified, the API will return only domains with organic_etv lesser than the specified value","type":["integer","null"]},"etv_min":{"description":"minimum current organic ETV of the domain
optional field
if specified, the API will return only domains with organic_etv greater than the specified value","type":["integer","null"]},"filters":{"description":"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:
[\"metrics_history.202110.organic.pos_1\", \">\", 15];
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"first_date":{"description":"first date of comparison period
required field
first date for which domain metrics will be provided;
date format: \"yyyy-mm-dd\";
example: \"2021-06-01\";
the list available dates is available through the available history endpoint;
Note: first_date cannot be greater than today's date;
Also note: the dates specified in first_date and second_date cannot point to the same month of the same year;
you can specify the dates in any order: first_date can be greater than second_date and vice versa;
minimum date: \"2020-10-01\"","type":"string"},"include_subdomains":{"description":"return subdomains in the API response
optional field
if false, the API response will contain main_domain only;
if true, the API will return main_domain plus its subdomains (if available);
default value: true","type":["boolean","null"]},"item_types":{"description":"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 the organic object, 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\"];
default value:
[\"organic\", \"paid\"]","items":{"type":"string"},"type":["array","null"]},"language_code":{"description":"unique language identifier
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code;
you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code;
you can receive the list of available languages with their language_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
example:
English","type":"string"},"limit":{"description":"the maximum number of domains in the results array
optional field
default value: 100;
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code;
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code;
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
example:
United Kingdom","type":"string"},"offset":{"description":"offset in the results array of returned domains
optional field
default value: 0;
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive domains","type":["integer","null"]},"order_by":{"description":"results sorting rules
optional field
you can use the same values as in the filters array to sort the results;
default rule: [\"organic_etv,desc\"];
possible sorting types:
asc - results will be sorted in ascending order
desc - results will be sorted in descending order;
you should use a comma to set up a sorting type;
example:
[\"organic_count,desc\"];
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:
[\"organic_etv,desc\",\"organic_count,asc\"]","items":{"type":"string"},"type":["array","null"]},"second_date":{"description":"second date of comparison period
required field
second date for which domain metrics will be provided;
date format: \"yyyy-mm-dd\";
example: \"2021-10-01\";
the list available dates is available through the available history endpoint;
Note: second_date cannot be greater than today's date;
Also note: the dates specified in first_date and second_date cannot point to the same month of the same year;
you can specify the dates in any order: second_date can be greater than first_date and vice versa;
minimum date: \"2020-10-01\"","type":"string"},"tag":{"description":"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","type":["string","null"]},"top_categories_count":{"description":"number of additional domain categories
optional field
by using this parameter, you can receive domains relevant to additional categories that are not specified in category_codes above;
to learn more about the parameter, please refer to this help center article;
by default, top_categories_count is equal to the number of categories specified in the category_codes array;
Note: top_categories_count cannot be less than the number of categories in the category_codes array;
maximum value: 5","format":"int64","type":["integer","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google domain metrics by categories live"},{"name":"labs_google_domain_rank_overview_live","description":"‌\nThis endpoint will provide you with ranking and traffic data from organic and paid search for the specified domain. You will be able to review the domain ranking distribution in SERPs as well as estimated monthly traffic volume for both organic and paid results.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"language_name":"English","location_code":2840,"target":"dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"language_name":"English","location_code":2840,"target":"dataforseo.com"}]],"properties":{"ignore_synonyms":{"description":"ignore highly similar keywords
optional field
if set to_true, all highly similar keywords will be excluded from the ranking and traffic calculations, the results will be based on data for main keywords from groups of synonyms
default value: falsen","type":["boolean","null"]},"language_code":{"description":"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","type":["string","null"]},"language_name":{"description":"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","type":["string","null"]},"limit":{"description":"the maximum number of returned results for domain
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"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","type":["integer","null"]},"location_name":{"description":"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","type":["string","null"]},"offset":{"description":"offset in the results array of returned items
optional field
default value: 0
if you specify the 10 value, the first ten items in the results array will be omitted and the data will be provided for the successive items","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain
required field
the domain name of the target website
the domain should be specified without https:// and www.","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google domain rank overview live"},{"name":"labs_google_historical_bulk_traffic_estimation_live","description":"‌\nThis endpoint will provide you with historical monthly traffic volumes for up to 1,000 domains collected within the specified time range through October 2020. If you do not specify the range, data will be returned for the previous 12 months. Along with organic search traffic estimations, you will also get separate values for paid search, featured snippet, and local pack results.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2021-01-01","date_to":"2021-03-29","item_types":["organic","paid"],"language_code":"en","location_code":2840,"targets":["dataforseo.com","cnn.com","forbes.com"]}]],"items":{"oneOf":[{"examples":[[{"date_from":"2021-01-01","date_to":"2021-03-29","item_types":["organic","paid"],"language_code":"en","location_code":2840,"targets":["dataforseo.com","cnn.com","forbes.com"]}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
if you don't specify this field, the data will be provided for the previous 12 months
minimal possible value: 2020-10-01
date format: \"yyyy-mm-dd\"","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default;
date format: \"yyyy-mm-dd\"
example:
\"2021-04-01\"","type":["string","null"]},"ignore_synonyms":{"description":"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: falsen","type":["boolean","null"]},"item_types":{"description":"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;
possible values:
[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]
default value:
[\"organic\", \"paid\"]","items":{"type":"string"},"type":["array","null"]},"language_code":{"description":"language code
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","type":["string","null"]},"language_name":{"description":"full name of the language
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","type":["string","null"]},"location_code":{"description":"location code
if you use this field, you don't have 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","type":["integer","null"]},"location_name":{"description":"full name of the location
if you use this field, you don't have 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","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"targets":{"description":"target domains and subdomains
required field
you can specify domains and subdomains in this field;
domains and subdomains should be specified without https:// and www.;
you can set up to 1000 domains or subdomains","items":{"type":"string"},"type":"array"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Estimate historical Google traffic for multiple targets"},{"name":"labs_google_historical_keyword_data_live","description":"‌‌ \nThis endpoint provides Google historical keyword data for specified keywords, including search volume, cost-per-click, competition values for paid search, monthly searches, and search volume trends. You can get historical keyword data since August, 2021, depending on keywords along with location and language combination. You can find the list of supported locations and languages here.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["iphone"],"language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keywords":["iphone"],"language_code":"en","location_code":2840}]],"properties":{"keywords":{"description":"keywords
required field
The maximum number of keywords you can specify: 700
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the specified keywords will be converted to lowercase format, data will be provided in a separate array
note that if some of the keywords specified in this array are omitted in the results you receive, then our database doesn't contain such keywords and cannot return data on them
you will not be charged for the keywords omitted in the results
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_code by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_name by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
English","type":"string"},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
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
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or 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
example:
United Kingdom","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google historical keyword data live"},{"name":"labs_google_historical_rank_overview_live","description":"‌\nThis endpoint will provide you with historical data on rankings and traffic of the specified domain, such as domain ranking distribution in SERPs and estimated monthly traffic volume for both organic and paid results.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"date_from":"2021-01-01","date_to":"2021-03-29","language_code":"en","location_code":2840,"target":"dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"date_from":"2021-01-01","date_to":"2021-03-29","language_code":"en","location_code":2840,"target":"dataforseo.com"}]],"properties":{"correlate":{"description":"correlate data with previously obtained datasets
optional field
default value: true
if you use this parameter, our system will correlate data you obtain now with previously obtained datasets
this parameter is intended to mitigate any inconsistencies that may result from changes to our database
we recommend always setting correlate to true","type":["boolean","null"]},"date_from":{"description":"starting date of the time range
optional field
if you don't specify this field, the data will be provided for the previous 6 months
minimal possible value: 2020-10-01
date format: \"yyyy-mm-dd\"","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:
\"2021-04-01\"","type":["string","null"]},"ignore_synonyms":{"description":"ignore highly similar keywords
optional field
if set to true, only data based on core keywords will be returned, data for all highly similar keywords will be excluded;
default value: false","type":["boolean","null"]},"include_clickstream_data":{"description":"include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_etv, clickstream_gender_distribution, and clickstream_age_distribution fields with clickstream data in the response;
default value: false;
Note: historical clickstream data is available from 2024/05 (May, 2024);
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","type":["boolean","null"]},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_code by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_name by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
English","type":"string"},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
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
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or 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
example:
United Kingdom","type":"string"},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain
required field
the domain name of the target website
the domain should be specified without https:// and www.","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google historical rank overview live"},{"name":"labs_google_historical_serps_live","description":"‌\nThis endpoint will provide you with Google SERPs collected within the specified time frame. You will also receive a complete overview of featured snippets and other extra elements that were present within the specified dates. The data will allow you to analyze the dynamics of keyword rankings over time for the specified keyword and location.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"datetime_from":"2026-10-06 08:39:25","datetime_to":"2026-10-16 08:39:25","keyword":"albert einstein","language_code":"en","limit":10,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"datetime_from":"2026-10-06 08:39:25","datetime_to":"2026-10-16 08:39:25","keyword":"albert einstein","language_code":"en","limit":10,"location_code":2840}]],"properties":{"date_from":{"description":"starting date of the time range
optional field
if you don't specify this field, the API will return all SERPs collected for 365 days starting from the current datetime value;
minimal possible value: 365 days from the current datetime value;
date format: \"yyyy-mm-dd\"","type":["string","null"]},"date_to":{"description":"ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default;
date format: \"yyyy-mm-dd\";
example:
\"2021-09-01\"","type":["string","null"]},"keyword":{"description":"keyword
required field
you can specify up to 700 characters in the keyword field;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”","type":"string"},"language_code":{"description":"unique language identifier
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code parameters by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name parameters by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
English","type":"string"},"location_code":{"description":"unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
United Kingdom","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google historical serps live"},{"name":"labs_google_keyword_ideas_live","description":"‌\nThe Keyword Ideas endpoint provides search terms that are relevant to the product or service categories of the specified keywords. The algorithm selects the keywords which fall into the same categories as the seed keywords specified in a POST array.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"include_serp_info":true,"keywords":["phone","watch"],"language_code":"en","limit":3,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"include_serp_info":true,"keywords":["phone","watch"],"language_code":"en","limit":3,"location_code":2840}]],"properties":{"closely_variants":{"description":"search mode
optional field
if set to_true the results will be based on the phrase-match search algorithm
if set to false the results will be based on the broad-match search algorithm
default value: falsen","type":["boolean","null"]},"filters":{"description":"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, not_ilike to match any string of zero or more characters
note that you can not filter the results by relevance
example:
[\"keyword_info.search_volume\",\">\",0]
[[\"keyword_info.search_volume\",\"in\",[0,1000]], \"and\", [\"keyword_info.competition_level\",\"=\",\"LOW\"]]
[[\"keyword_info.search_volume\",\">\",100], \"and\", [[\"keyword_info.cpc\",\"<\",0.5], \"or\",
[\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"ignore_synonyms":{"description":"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: falsen","type":["boolean","null"]},"include_clickstream_data":{"description":"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, 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","type":["boolean","null"]},"include_serp_info":{"description":"include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false","type":["boolean","null"]},"keywords":{"description":"keywords
required field
UTF-8 encoding
The maximum number of keywords you can specify: 200.
The keywords will be converted to lowercase format
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"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
example:
en
Note: if omitted, results default to the language with the most keyword records in the specified location;
refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language","type":["string","null"]},"language_name":{"description":"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
example:
English
Note: if omitted, results default to the language with the most keyword records in the specified location;
refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language","type":["string","null"]},"limit":{"description":"the maximum number of keywords in the results array
optional field
default value: 700
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
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
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or 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
example:
United Kingdom","type":"string"},"offset":{"description":"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
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead.","type":["integer","null"]},"offset_token":{"description":"offset token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;
offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.
learn more about this parameter on our Help Center","type":["string","null"]},"order_by":{"description":"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 parameter
default rule:
[\"relevance,desc\"]
relevance is used as the default sorting rule to provide you with the closest keyword ideas. We recommend using this sorting rule to get highly-relevant search terms. Note that relevance is only our internal system identifier, so it can not be used as a filter, and you will not find this field in the result array. The relevance score is based on a similar principle as used in the Keywords For Keywords endpoint.
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:
[\"relevance,desc\",\"keyword_info.search_volume,desc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google keyword ideas live"},{"name":"labs_google_keyword_overview_live","description":"‌‌ \nThis endpoint provides Google keyword data for specified keywords. For each keyword, you will receive current cost-per-click, competition values for paid search, search volume, search intent, monthly searches, as well as SERP and backlink information. Additionally, you can obtain clickstream data, such as clickstream search volume, by specifying the include_clickstream_data parameter.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"include_clickstream_data":true,"include_serp_info":true,"keywords":["iphone"],"language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"include_clickstream_data":true,"include_serp_info":true,"keywords":["iphone"],"language_code":"en","location_code":2840}]],"properties":{"include_clickstream_data":{"description":"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, 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","type":["boolean","null"]},"include_serp_info":{"description":"include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false","type":["boolean","null"]},"keywords":{"description":"keywords
required field
The maximum number of keywords you can specify: 700
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the specified keywords will be converted to lowercase format, data will be provided in a separate array
note that if some of the keywords specified in this array are omitted in the results you receive, then our database doesn't contain such keywords and cannot return data on them
you will not be charged for the keywords omitted in the results
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_code by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_name by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
English","type":"string"},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
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
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or 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
example:
United Kingdom","type":"string"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google keyword overview live"},{"name":"labs_google_keyword_suggestions_live","description":"‌‌\nThe Keyword Suggestions endpoint provides search queries that include the specified seed keyword.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"include_seed_keyword":true,"include_serp_info":true,"keyword":"phone","language_code":"en","limit":1,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"include_seed_keyword":true,"include_serp_info":true,"keyword":"phone","language_code":"en","limit":1,"location_code":2840}]],"properties":{"exact_match":{"description":"search for the exact phrase
optional field
if set to true, the returned keywords will include the exact keyword phrase you specified, with potentially other words before or after that phrase
default value: false","type":["boolean","null"]},"filters":{"description":"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:
[\"keyword_info.search_volume\",\">\",0]
[[\"keyword_info.search_volume\",\"in\",[0,1000]], \"and\", [\"keyword_info.competition_level\",\"=\",\"LOW\"]][[\"keyword_info.search_volume\",\">\",100], \"and\", [[\"keyword_info.cpc\",\"<\",0.5], \"or\", [\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"ignore_synonyms":{"description":"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","type":["boolean","null"]},"include_clickstream_data":{"description":"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, 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","type":["boolean","null"]},"include_seed_keyword":{"description":"include data for the seed keyword
optional field
if set to true, data for the seed keyword specified in the keyword field will be provided in the seed_keyword_data array of the response
default value: false","type":["boolean","null"]},"include_serp_info":{"description":"include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false","type":["boolean","null"]},"keyword":{"description":"keyword
required field
UTF-8 encoding
the keywords will be converted to lowercase format;
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"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
example:
en
Note: if omitted, results default to the language with the most keyword records in the specified location;
refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language","type":["string","null"]},"language_name":{"description":"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
example:
English
Note: if omitted, results default to the language with the most keyword records in the specified location;
refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language","type":["string","null"]},"limit":{"description":"the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"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","type":["integer","null"]},"location_name":{"description":"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","type":["string","null"]},"offset":{"description":"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
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead.","type":["integer","null"]},"offset_token":{"description":"offset token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;
offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.
learn more about this parameter on our Help Center","type":["string","null"]},"order_by":{"description":"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
a comma is used as a separator
example:
[\"keyword_info.competition,desc\"]
default rule:
[\"keyword_info.search_volume,desc\"]
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_info.search_volume,desc\",\"keyword_info.cpc,desc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google keyword suggestions live"},{"name":"labs_google_keywords_for_app_live","description":"‌\nThis endpoint will provide you with a list of keywords for which the target app ranks on Google Play. You will obtain keyword data and discover the app’s ranking position for each returned keyword.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"app_id":"org.telegram.messenger","language_name":"English","limit":10,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"app_id":"org.telegram.messenger","language_name":"English","limit":10,"location_code":2840}]],"properties":{"app_id":{"description":"id of the apps
required field
ID of the mobile application on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:
in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger
the id is org.telegram.messenger","type":"string"},"filters":{"description":"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:
<, <=, >, >=, =, <>, in, not_in
example:
[\"keyword_data.keyword_info.search_volume\",\">\",500]
[[\"keyword_data.keyword_info.search_volume\",\"<>\",500],\"and\",[\"ranked_serp_element.serp_item.rank_group\",\">=\",\"10\"]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
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;
Note: this endpoint currently supports the English language only
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or 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;
Note: this endpoint currently supports the English language only;
example:
English","type":"string"},"limit":{"description":"the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:
United States","type":"string"},"offset":{"description":"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","type":["integer","null"]},"order_by":{"description":"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 specify a sorting type;
example:
[\"ranked_serp_element.serp_item.rank_group,asc\"]
Note: you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:
[\"ranked_serp_element.serp_item.rank_group,desc\",\"keyword_data.keyword_info.search_volume,asc\"]
default rule:
[\"keyword_data.keyword_info.search_volume,desc\"]
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","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google keywords for app live"},{"name":"labs_google_keywords_for_categories_live","description":"‌\nThis endpoint will provide you with a list of keywords relevant to the specified product categories. You will get the search volume rate for the last month, search volume trend for the previous 12 months, as well as current cost-per-click and competition values for each keyword.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"category_codes":["12191","12193"],"include_serp_info":true,"language_name":"English","limit":3,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"category_codes":["12191","12193"],"include_serp_info":true,"language_name":"English","limit":3,"location_code":2840}]],"properties":{"category_codes":{"description":"product and service categories
required field
The maximum number of categories you can specify: 20
you can download the full list of possible categories","items":{"type":"string"},"type":"array"},"category_intersection":{"description":"category intersections
optional field
if set to true, you will get keywords featured in all specified categories;
if set to false, you will keywords that are specified in any of the specified categories;
default value: true","type":["boolean","null"]},"filters":{"description":"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, not_ilike to match any string of zero or more characters
example:
[\"keyword_info.search_volume\",\">\",0]
[[\"keyword_info.search_volume\",\"in\",[0,1000]], \"and\", [\"keyword_info.competition_level\",\"=\",\"LOW\"]]
[[\"keyword_info.search_volume\",\">\",100], \"and\", [[\"keyword_info.cpc\",\"<\",0.5], \"or\", [\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"ignore_synonyms":{"description":"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","type":["boolean","null"]},"include_clickstream_data":{"description":"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, 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","type":["boolean","null"]},"include_serp_info":{"description":"include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false","type":["boolean","null"]},"language_code":{"description":"unique language identifier
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
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
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or 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
example:
English","type":"string"},"limit":{"description":"the maximum number of keywords in the results array
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
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
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or 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
example:
United Kingdom","type":"string"},"offset":{"description":"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
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead.","type":["integer","null"]},"offset_token":{"description":"offset token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;
offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.
learn more about this parameter on our Help Center","type":["string","null"]},"order_by":{"description":"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_info.competition,desc\"]
default rule:
[\"keyword_info.search_volume,desc\"]
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_info.search_volume,desc\",\"keyword_info.competition,asc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google keywords for categories live"},{"name":"labs_google_keywords_for_site_live","description":"‌\nThe Keywords For Site endpoint will provide you with a list of keywords relevant to the target domain, subdomain, or webpage. Each keyword is supplied with relevant categories, search volume data for the last month, cost-per-click, competition, and search volume trend values for the past 12 months.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":["serp_info.se_results_count",">",0],"include_serp_info":true,"include_subdomains":true,"language_code":"en","limit":3,"location_code":2840,"target":"apple.com"}]],"items":{"oneOf":[{"examples":[[{"filters":["serp_info.se_results_count",">",0],"include_serp_info":true,"include_subdomains":true,"language_code":"en","limit":3,"location_code":2840,"target":"apple.com"}]],"properties":{"filters":{"description":"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
note that you can not filter the results by relevance
example:
[\"keyword_info.search_volume\",\">\",0]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"include_clickstream_data":{"description":"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, 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","type":["boolean","null"]},"include_serp_info":{"description":"include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false","type":["boolean","null"]},"include_subdomains":{"description":"indicates if the subdomains will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"language_code":{"description":"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
example:
en
Note: if omitted, results default to the language with the most keyword records in the specified location;
refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language","type":["string","null"]},"language_name":{"description":"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
example:
English
Note: if omitted, results default to the language with the most keyword records in the specified location;
refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language","type":["string","null"]},"limit":{"description":"the maximum number of keywords in the results array
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
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
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or 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
example:
United Kingdom","type":"string"},"offset":{"description":"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
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead.","type":["integer","null"]},"offset_token":{"description":"offset token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;
offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.
learn more about this parameter on our Help Center","type":["string","null"]},"order_by":{"description":"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 parameter
default rule:
[\"relevance,desc\"]
relevance is used as the default sorting rule to provide you with the closest keyword ideas. We recommend using this sorting rule to get highly-relevant search terms. Note that relevance is only our internal system identifier, so it can not be used as a filter, and you will not find this field in the result array. The relevance score is based on a similar principle as used in the Keywords For Keywords endpoint.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:
[\"relevance,desc\",\"keyword_info.search_volume,desc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"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","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google keywords for site live"},{"name":"labs_google_page_intersection_live","description":"This endpoint will provide you with the keywords for which specified pages rank within the same SERP. You will get search volume, competition, cost-per-click data on each intersecting keyword. Along with that, you will get data on SERP elements that specified pages rank for in search results, as well as the estimated traffic volume and cost of ad traffic. Page Intersection endpoint supports organic, paid, local pack and featured snippet results.\nfor more info please visit 'https://docs.dataforseo.com/v3/dataforseo_labs/google/page_intersection/live/?bash'","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"include_serp_info":true,"language_name":"English","limit":3,"location_code":2840,"pages":{"1":"https://forbes.com","2":"https://cnn.com/*"}}]],"items":{"oneOf":[{"examples":[[{"include_serp_info":true,"language_name":"English","limit":3,"location_code":2840,"pages":{"1":"https://forbes.com","2":"https://cnn.com/*"}}]],"properties":{"exclude_pages":{"description":"URLs of pages you want to excludeoptional fieldyou can set up to 10 pages in this arrayif you use this array, results will contain the keywords for which URLs from the pages object rank, but URLs from exclude_pages array do not;note that if you specify this field, the results will be based on the keywords any URL from pages ranks for regardless of intersections between them. However, you can set intersection_mode to intersect and results will contain the keywords all URLs from pages rank for in the same SERP and URLs from exclude_pages do not. use a wildcard ('*') character to specify the search patternexample:\"exclude_pages\":[\"https://www.apple.com/iphone/*\",\"https://dataforseo.com/apis/*\",\"https://www.microsoft.com/en-us/industry/services/\"]","items":{"type":"string"},"type":["array","null"]},"filters":{"description":"array of results filtering parametersoptional fieldyou can add several filters at once (8 filters maximum)you should set a logical operator and, or between the conditionsthe following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, ilike, not_ilike, like, not_like, match, not_matchyou can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more charactersnote that if you want to filter by any field in the intersection_result array you need to specify the number of corresponding pagefor instance, if you want to filter results by the ranking of the first specified URL, you should set the following filter:[intersection_result.1.rank_absolute,\"=\",1]if you want to filter results and receive only organic listings for the third specified URL, you should set the following filter:[intersection_result.3.type,\"=\",\"organic\"] , etc.example:[\"keyword_data.keyword_info.search_volume\",\"in\",[100,1000]][[\"intersection_result.1.etv\",\">\",0],\"and\",[\"intersection_result.1.description\",\"like\",\"%goat%\"]][[\"keyword_data.keyword_info.search_volume\",\">\",100],\"and\",[[\"intersection_result.2.description\",\"like\",\"%goat%\"],\"or\",[\"intersection_result.2.type\",\"=\",\"organic\"]]]for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"ignore_synonyms":{"description":"ignore highly similar keywordsoptional fieldif set to true only core keywords will be returned, all highly similar keywords will be excluded; default value: false","type":["boolean","null"]},"include_clickstream_data":{"description":"include or exclude data from clickstream-based metrics in the resultoptional fieldif the parameter is set to true, you will receive clickstream_keyword_info, clickstream_etv, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the responsedefault value: falsewith this parameter enabled, you will be charged double the price for the requestlearn more about how clickstream-based metrics are calculated in this help center article","type":["boolean","null"]},"include_serp_info":{"description":"include data from SERP for each keywordoptional fieldif set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the responsedefault value: false","type":["boolean","null"]},"include_subdomains":{"description":"indicates if the subdomains will be included in the searchoptional fieldif set to false, the subdomains will be ignoreddefault value: true","type":["boolean","null"]},"intersection_mode":{"description":"indicates whether to intersect keywordsoptional fielduse this field to intersect or merge results for the specified URLspossible values: union, intersectunion - results are based on all keywords any URL from pages rank for;intersect - results are based on the keywords all URLs from pages rank for in the same SERP:by default, results are based on the intersect mode if you specify only pages array. If you specify exclude_pages as well, results are based on the union mode","type":["string","null"]},"item_types":{"description":"search results typeindicates type of search results included in the responseoptional fieldpossible values: [\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]default value: [\"organic\", \"paid\"]","items":{"type":"string"},"type":["array","null"]},"language_code":{"description":"language coderequired field if you don't specify language_nameNote: it is required to specify either language_name or language_codeyou 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_languagesexample:en","type":["string","null"]},"language_name":{"description":"full name of the languagerequired field if you don't specify language_codeNote: it is required to specify either language_name or language_codeyou 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_languagesexample:English","type":["string","null"]},"limit":{"description":"the maximum number of returned keywordsoptional fielddefault value: 100maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location coderequired field if you don't specify location_nameNote: it is required to specify either location_name or location_codeyou 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_languagesexample:2840","type":["integer","null"]},"location_name":{"description":"full name of the locationrequired field if you don't specify location_codeNote: it is required to specify either location_name or location_codeyou 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_languagesexample:United Kingdom","type":["string","null"]},"offset":{"description":"offset in the items array of returned keywordsoptional fielddefault value: 0if you specify 10 here, 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":"results sorting rulesoptional fieldyou can use the same values as in the filters array to sort the resultspossible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending orderyou should use a comma to set up a sorting parameterexample:[\"keyword_data.keyword_info.competition,desc\"]default rule:[\"keyword_data.keyword_info.search_volume,desc\"]note that you can set no more than three sorting rules in a single requestyou should use a comma to separate several sorting rulesexample:[\"intersection_result.1.rank_group,asc\",\"intersection_result.2.rank_absolute,asc\"]","items":{"type":"string"},"type":["array","null"]},"pages":{"additionalProperties":{"type":["string","null"]},"description":"target URLs of pagesrequired fieldyou can set up to 20 pages in this objectthe pages should be specified with absolute URLs (including http:// or https://)example:\"pages\": {\"1\":\"https://www.apple.com/mac/*\",\"2\":\"https://dataforseo.com/*\",\"3\":\"https://support.microsoft.com/\"}if you specify a single page here, we will return results only for this page;you can also use a wildcard ('') character to specify the search patternexample:\"example.com\"search for the exact URL\"example.com/eng/\"search for the example.com page and all its related URLs which start with '/eng/', such as \"example.com/eng/index.html\" and \"example.com/eng/help/\", etc.note: a wilcard should be placed after the slash ('/') character in the end of the URL, it is not possible to place it after the domain in the following way:https://dataforseo.comuse https://dataforseo.com/ insteadNote: this endpoint will not provide results if the number of intersecting keywords exceeds 10 million","type":["object","null"]},"tag":{"description":"user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google page intersection live"},{"name":"labs_google_relevant_pages_live","description":"‌","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["metrics.organic.pos_1","<>",0],"or",["metrics.organic.pos_2_3","<>",0]],"language_name":"English","limit":3,"location_code":2840,"target":"amazon.com"}]],"items":{"oneOf":[{"examples":[[{"filters":[["metrics.organic.pos_1","<>",0],"or",["metrics.organic.pos_2_3","<>",0]],"language_name":"English","limit":3,"location_code":2840,"target":"amazon.com"}]],"properties":{"filters":{"description":"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
example:
[\"metrics.paid.count\",\">\",0]
[[\"metrics.organic.count\",\">\",50],\"and\",[\"metrics.organic.pos_1\",\"<>\",0]]
[[\"\"metrics.organic.count\",\">\",50\"], \"and\", [[\"metrics.organic.pos_1\",\"<>\",0],\"or\",[\"metrics.organic.pos_2_3\",\"<>\",0]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"historical_serp_mode":{"description":"data collection mode
optional field
you can use this field to filter the results;
possible types of filtering:
live — return metrics for SERPs in which the specified target currently has ranking results;
lost — return metrics for SERPs in which the specified target had previously had ranking results, but didn't have them during the last check;
all — return metrics for both types of SERPs.
default value: live","type":["string","null"]},"ignore_synonyms":{"description":"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","type":["boolean","null"]},"include_clickstream_data":{"description":"include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_etv, clickstream_gender_distribution, and clickstream_age_distribution fields with clickstream data 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","type":["boolean","null"]},"item_types":{"description":"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\"]
default value:
[\"organic\", \"paid\"]","items":{"type":"string"},"type":["array","null"]},"language_code":{"description":"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","type":["string","null"]},"language_name":{"description":"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","type":["string","null"]},"limit":{"description":"the maximum number of returned pages
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"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","type":["integer","null"]},"location_name":{"description":"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","type":["string","null"]},"offset":{"description":"offset in the results array of returned pages
optional field
default value: 0
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages","type":["integer","null"]},"order_by":{"description":"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 specify a sorting type
example:
[\"metrics.paid.etv,asc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:
[\"metrics.organic.etv,desc\",\"metrics.paid.count,asc\"]
default rule:
[\"metrics.organic.count,desc\"]
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","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain
required field
the domain name of the target website
the domain should be specified without https:// and www.","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google relevant pages live"},{"name":"labs_google_search_intent_live","description":"‌\nThis endpoint will provide you with search intent data for up to 1,000 keywords. For each keyword that you specify when setting a task, the API will return the keyword’s search intent and intent probability. Besides the highest probable search intent, the results will also provide you with other likely search intent(s) and their probability.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keywords":["login page","audi a7","elon musk","milk store new york"]}]],"items":{"oneOf":[{"examples":[[{"keywords":["login page","audi a7","elon musk","milk store new york"]}]],"properties":{"keywords":{"description":"target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000;
the keywords will be converted to lowercase format
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google search intent live"},{"name":"labs_google_serp_competitors_live","description":"‌\nThis endpoint will provide you with a list of domains ranking for the keywords you specify. You will also get SERP rankings, rating, estimated traffic volume, and visibility values the provided domains gain from the specified keywords.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"item_types":["organic"],"keywords":["phone"],"language_name":"English","limit":5,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"item_types":["organic"],"keywords":["phone"],"language_name":"English","limit":5,"location_code":2840}]],"properties":{"filters":{"description":"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:
[\"median_position\",\"in\",[1,10]]
[[\"median_position\",\"in\",[1,10]],\"and\",[\"domain\",\"not_like\",\"%wikipedia.org%\"]]
[[\"domain\",\"not_like\",\"%wikipedia.org%\"], \"and\", [[\"relevant_serp_items\",\">\",0],\"or\",[\"median_position\",\"in\",[1,10]]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"include_subdomains":{"description":"indicates if the subdomains will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"item_types":{"description":"search results type
indicates type of search results included in the response
optional field
possible values:
[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]
default value:
[\"organic\", \"paid\"]","items":{"type":"string"},"type":["array","null"]},"keywords":{"description":"keywords array
required field
the results will be based on the keywords you specify in this array
UTF-8 encoding;
the keywords will be converted to lowercase format;
you can specify the maximum of 200 keywords
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","items":{"type":"string"},"type":"array"},"language_code":{"description":"unique language identifier
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code parameters by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name parameters by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
English","type":"string"},"limit":{"description":"the maximum number of returned domains
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code parameters by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with location_name parameters by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
United Kingdom","type":"string"},"offset":{"description":"offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive domains","type":["integer","null"]},"order_by":{"description":"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
the comma is used as a separator
example:
[\"avg_position,asc\"]
default rule:
[\"rating,desc\"]
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:
[\"avg_position,asc\",\"etv,desc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google serp competitors live"},{"name":"labs_google_subdomains_live","description":"‌‌\nThis endpoint will provide you with a list of subdomains of the specified domain, along with the ranking distribution across organic and paid search. In addition to that, you will also get the estimated traffic volume of subdomains based on search volume and impressions.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["metrics.organic.pos_1","<>",0],"or",["metrics.organic.pos_2_3","<>",0]],"language_name":"English","location_code":2840,"target":"dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"filters":[["metrics.organic.pos_1","<>",0],"or",["metrics.organic.pos_2_3","<>",0]],"language_name":"English","location_code":2840,"target":"dataforseo.com"}]],"properties":{"filters":{"description":"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
example:
[\"metrics.paid.count\",\">\",0]
[[\"metrics.paid.count\",\">\",0],\"and\",[\"metrics.paid.etv\",\">\",\"50\"]]
[[\"metrics.organic.count\",\">\",\"10\"], \"and\", [[\"metrics.organic.pos_1\",\"<>\",0],\"or\",[\"metrics.organic.pos_2_3\",\"<>\",0]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"historical_serp_mode":{"description":"data collection mode
optional field
you can use this field to filter the results;
possible types of filtering:
live — return metrics for SERPs in which the specified target currently has ranking results;
lost — return metrics for SERPs in which the specified target had previously had ranking results, but didn't have them during the last check;
all — return metrics for both types of SERPs.
default value: live","type":["string","null"]},"ignore_synonyms":{"description":"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","type":["boolean","null"]},"include_clickstream_data":{"description":"include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_etv, clickstream_gender_distribution, and clickstream_age_distribution fields with clickstream data 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","type":["boolean","null"]},"item_types":{"description":"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\"]
default value:
[\"organic\", \"paid\"]","items":{"type":"string"},"type":["array","null"]},"language_code":{"description":"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","type":["string","null"]},"language_name":{"description":"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","type":["string","null"]},"limit":{"description":"the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"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","type":["integer","null"]},"location_name":{"description":"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","type":["string","null"]},"offset":{"description":"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","type":["integer","null"]},"order_by":{"description":"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 specify a sorting type
example:
[\"metrics.paid.etv,asc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:
[\"metrics.organic.etv,desc\",\"metrics.paid.count,asc\"]
default rule:
[\"metrics.organic.count,desc\"]
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","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain
required field
the domain name of the target website
the domain should be specified without https:// and www.","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google subdomains live"},{"name":"labs_google_top_searches_live","description":"‌‌\nThe Top Searches endpoint of DataForSEO Labs API can provide you with over 7 billion keywords from the DataForSEO Keyword Database. Each keyword in the API response is provided with a set of relevant keyword data with Google Ads metrics, product categories, and Google SERP data.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"language_name":"English","limit":3,"location_code":2840}]],"items":{"oneOf":[{"examples":[[{"language_name":"English","limit":3,"location_code":2840}]],"properties":{"filters":{"description":"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:
[\"keyword_info.search_volume\",\">\",0]
[[\"keyword_info.search_volume\",\"in\",[0,1000]], \"and\", [\"keyword_info.competition_level\",\"=\",\"LOW\"]]
[[\"keyword_info.search_volume\",\">\",100], \"and\", [[\"keyword_info.cpc\",\"<\",0.5], \"or\",
[\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide","items":{"type":["object","null"]},"type":["array","null"]},"ignore_synonyms":{"description":"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","type":["boolean","null"]},"include_clickstream_data":{"description":"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, 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","type":["boolean","null"]},"include_serp_info":{"description":"include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false","type":["boolean","null"]},"language_code":{"description":"language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_code by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
en","type":["string","null"]},"language_name":{"description":"full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_name by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
English","type":"string"},"limit":{"description":"the maximum number of returned keywords
optional field
note: you can get more than 1000 results by using the offset_token provided in the response to each subsequent request
default value: 1000
maximum value: 1000","type":["integer","null"]},"location_code":{"description":"location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
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
example:
2840","type":"integer"},"location_name":{"description":"full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or 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
example:
United Kingdom","type":"string"},"offset":{"description":"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
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead.","type":["integer","null"]},"offset_token":{"description":"offset token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;
offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.
learn more about this parameter on our Help Center","type":["string","null"]},"order_by":{"description":"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_info.competition,desc\"]
default rule:
[\"keyword_info.search_volume,desc\"]
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_info.search_volume,desc\",\"keyword_info.cpc,desc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Dataforseo labs google top searches live"},{"name":"linking_domains","description":"‌‌\nThis endpoint will provide you with a detailed overview of referring domains pointing to the target you specify.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"backlinks_filters":["dofollow","=",true],"exclude_internal_backlinks":true,"filters":["backlinks",">",100],"limit":5,"order_by":["rank,desc"],"target":"backlinko.com"}]],"items":{"oneOf":[{"examples":[[{"backlinks_filters":["dofollow","=",true],"exclude_internal_backlinks":true,"filters":["backlinks",">",100],"limit":5,"order_by":["rank,desc"],"target":"backlinko.com"}]],"properties":{"backlinks_filters":{"description":"filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:
\"backlinks_filters\": [\"dofollow\", \"=\", true]","items":{"type":["object","null"]},"type":["array","null"]},"backlinks_status_type":{"description":"set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values:
all - all backlinks will be returned and counted;
live - backlinks found during the last check will be returned and counted;
lost - lost backlinks will be returned and counted;
default value: live","type":["string","null"]},"exclude_internal_backlinks":{"description":"indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be ommited and you won't receive the same domain in the response;
default value: true","type":["boolean","null"]},"filters":{"description":"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, like, not_like, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"referring_pages\",\">\",\"1\"]
[[\"referring_pages\",\">\",\"2\"], \"and\", [\"backlinks\",\">\",\"10\"]]
[[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"], \"and\", [[\"domain\",\"like\",\"%dataforseo.com%\"],\"or\",[\"referring_domains\",\">\",\"10\"]]]
The full list of possible filters is available here.","items":{"type":["object","null"]},"type":["array","null"]},"include_indirect_links":{"description":"indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true","type":["boolean","null"]},"include_subdomains":{"description":"indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true","type":["boolean","null"]},"internal_list_limit":{"description":"maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:
referring_links_tld
referring_links_types
referring_links_attributes
referring_links_platform_types
referring_links_semantic_locations
default value: 10
maximum value: 1000","type":["integer","null"]},"limit":{"description":"the maximum number of returned domains
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive pages","type":["integer","null"]},"order_by":{"description":"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:
[\"backlinks,desc\"]
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:
[\"backlinks,desc\",\"rank,asc\"]","items":{"type":"string"},"type":["array","null"]},"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"domain, subdomain or webpage to get referring domains for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Linking domains","catalog":"web.linking_domains.list"},{"name":"merchant_amazon_asin_live_advanced","description":"‌‌\nThis endpoint will provide you with a full list of ASINs assigned to different modifications of a product.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"asin":"B0756FCPPN","language_code":"en_US","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"asin":"B0756FCPPN","language_code":"en_US","location_code":2840}]],"properties":{"asin":{"description":"product ID
required field
unique product identifier (ASIN) in Amazon
you can receive the asin parameter by making a separate request to the Amazon Products endpoint","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
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 parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:
en_GB","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
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 parameters by making a separate request to the
https://api.dataforseo.com/v3/merchant/amazon/languages
example:
English (United Kingdom)","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with their location_code parameters by making a separate request to the
https://api.dataforseo.com/v3/merchant/amazon/locations
example:
9045969","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:
53.476225,-2.243572,200","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with their location_name parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:
HA1,England,United Kingdom","type":"string"},"se_domain":{"description":"search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
amazon.com, amazon.co.uk, amazon.fr, etc.","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Merchant amazon asin live advanced"},{"name":"merchant_amazon_locations_country","description":"You will receive the list of supported Amazon locations by this API call. You can filter the list of locations by country when setting a task.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Merchant amazon locations country"},{"name":"merchant_amazon_products_live_advanced","description":"‌‌\nThis endpoint provides results from Amazon product listings according to the specified keyword (product name), location, and language parameters.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"shoes","language_code":"en_US","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"shoes","language_code":"en_US","location_code":2840}]],"properties":{"department":{"description":"amazon product department
optional field
specify one of the following amazon departments for extracting product listings:
\"Arts & Crafts\", \"Automotive\", \"Baby\", \"Beauty & Personal Care\", \"Books\", \"Computers\", \"Digital Music\", \"Electronics\", \"Kindle Store\", \"Prime Video\", \"Women's Fashion\", \"Men's Fashion\", \"Girls' Fashion\", \"Boys' Fashion\", \"Deals\", \"Health & Household\", \"Home & Kitchen\", \"Industrial & Scientific\", \"Luggage\", \"Movies & TV\", \"Music, CDs & Vinyl\", \"Pet Supplies\", \"Software\", \"Sports & Outdoors\", \"Tools & Home Improvement\", \"Toys & Games\", \"Video Games\"","type":["string","null"]},"depth":{"description":"parsing depth
optional field
number of results to be retrieved from the Amazon results page
default value: 100
max value: 700
Your account will be billed per each SERP containing up to 100 results;
Setting depth above 100 may result in additional charges if the search engine returns more than 100 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"keyword":{"description":"keyword
required field
you can specify up to 700 characters in this field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
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 parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:
en_GB","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
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 parameters by making a separate request to the
https://api.dataforseo.com/v3/merchant/amazon/languages
example:
English (United Kingdom)","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with their location_code parameters by making a separate request to the
https://api.dataforseo.com/v3/merchant/amazon/locations
example:
9045969","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:
53.476225,-2.243572,200","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with their location_name parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:
HA1,England,United Kingdom","type":"string"},"max_crawl_pages":{"description":"page crawl limit
optional field
number of search results pages to crawl
max value: 7
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center","type":["integer","null"]},"price_max":{"description":"maximum product price
optional field
maximum price of the returned products listed on Amazon for the specified query
example:
100
Note: if you specify price_max, the search_param parameter will be ignored","type":["integer","null"]},"price_min":{"description":"minimum product price
optional field
minimum price of the returned products listed on Amazon for the specified query
example:
5
Note: if you specify price_min, the search_param parameter will be ignored","type":["integer","null"]},"se_domain":{"description":"search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
amazon.com, amazon.co.uk, amazon.fr, etc.","type":["string","null"]},"search_param":{"description":"additional parameters of the search query
optional field
you can use the following Amazon search URL parameters for customizing the search
example:
&low-price=52 - search for products that cost more than 52 USD;
&high-price=45 - search for products that cost less than 45 USD;
&sort=relevancerank - sort results by relevance;
&sort=featured-rank - sort results by featured products;
&sort=price-asc-rank - sort by ascending price;
&sort=price-desc-rank - sort by descending price;
&sort=review-rank - sort by the average customer reviews value;
&sort=date-desc-rank - sort by the newest arrival
Note that search_param values will be ignored if any of the following parameters is used: price_min, price_max, sort_by","type":["string","null"]},"sort_by":{"description":"results sorting rules
optional field
the following sorting rules are supported:
relevance, price_low_to_high, price_high_to_low, featured, avg_customer_review, newest_arrival
example:
sort_by:\"relevance\"
Note: if you specify sort_by, the search_param parameter will be ignored","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"url":{"description":"direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.amazon.com/s/?field-keywords=shoes&language=en_US","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Merchant amazon products live advanced"},{"name":"merchant_amazon_sellers_live_advanced","description":"‌‌\nThis endpoint provides a list of sellers of the specified product on Amazon. The data provided for each seller includes related product condition, pricing, shipment, and rating details.\nThe results are specific to the selected location (see the List of Locations) and language (see the List of Languages) settings.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"asin":"B07D528W98","language_code":"en_US","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"asin":"B07D528W98","language_code":"en_US","location_code":2840}]],"properties":{"asin":{"description":"unique product identifier on Amazon
required field
you can get this value making a separate request to the Amazon Products endpoint
note that there is no full list of possible values as the asin values is a dynamic value assigned by Amazon
example:
B085RFFC9Q
learn more about the identifier in this help center guide","type":"string"},"language_code":{"description":"language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available Amazon languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:
en_US","type":"string"},"language_name":{"description":"full name of the language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available Amazon languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:
English (United States)","type":"string"},"location_code":{"description":"location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available Amazon locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:
2840","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:
53.476225,-2.243572,200","type":"string"},"location_name":{"description":"full name of the location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available Amazon locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:
London,England,United Kingdom","type":"string"},"se_domain":{"description":"search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
amazon.co.uk, amazon.com.au, amazon.de, etc.","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Merchant amazon sellers live advanced"},{"name":"merchant_google_locations_country","description":"GET /v3/merchant/google/locations/{country}","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Merchant google locations country"},{"name":"merchant_google_product_info_task_get_advanced_id","description":"Description of the fields for sending a request:","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Merchant google product info task get advanced id"},{"name":"merchant_google_product_info_task_post","description":"‌‌\nThis endpoint provides data on a product listed on Google Shopping, including product description, images, rating, variations, specifications and sellers. In order to set a task, you have to specify one of the following fields: product_id, data_docid, or gid.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"language_code":"en","location_code":2840,"product_id":"1113158713975221117"}]],"items":{"oneOf":[{"examples":[[{"language_code":"en","location_code":2840,"product_id":"1113158713975221117"}]],"properties":{"data_docid":{"description":"unique identifier of the SERP data element
required field if product_id or gid is not specified
we recommend specifying data_docid together with product_id and gid for optimal results;
you can get this value for a certain element by making a separate request to the Google Shopping Products endpoint
example:
13071766526042404278","type":"string"},"gid":{"description":"global product identifier on Google Shopping
required field if product_id or data_docid is not specified
we recommend specifying gid together with product_id and data_docid for optimal results;
you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint
example:
4702526954592161872
learn more about the parameter in this help center guide","type":"string"},"language_code":{"description":"language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available Google Shopping languages with their language_code_by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages
example:
en","type":"string"},"language_name":{"description":"full name of the language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available Google Shopping languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages
example:
English","type":"string"},"location_code":{"description":"location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available Google Shopping locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations
example:
2840","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:
53.476225,-2.243572,200","type":"string"},"location_name":{"description":"full name of the location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available Google Shopping locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations
example:
London,England,United Kingdom","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_data":{"description":"postback_url datatype
optional field
corresponds to the datatype that will be sent to your server
possible values:
advanced","type":["string","null"]},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"product_id":{"description":"unique product identifier on Google Shopping
required field if data_docid or gid is not specified
we recommend specifying product_id together with data_docid and gid for optimal results;
you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint
example:
4485466949985702538
learn more about the parameter in this help center guide","type":"string"},"se_domain":{"description":"search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
google.co.uk, google.com.au, google.de, etc.","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Merchant google product info task post"},{"name":"merchant_google_products_task_get_advanced_id","description":"Description of the fields for sending a request:","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Merchant google products task get advanced id"},{"name":"merchant_google_products_task_post","description":"‌‌\nGoogle Shopping Products endpoint will provide you with the list of products found on Google Shopping for the specified query. The results include product title, description in Google Shopping SERP, product rank, price, reviews and rating as well as the related domain.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"iphone","language_code":"en","location_code":2840,"price_min":5}]],"items":{"oneOf":[{"examples":[[{"keyword":"iphone","language_code":"en","location_code":2840,"price_min":5}]],"properties":{"depth":{"description":"parsing depth
optional field
number of results to be retrieved from Google Shopping SERP
default value: 40
max value: 120
Your account will be billed per each SERP containing up to 40 results;
Setting depth above 40 may result in additional charges if the search engine returns more than 40 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"keyword":{"description":"keyword
required field
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available Google Shopping languages with their language_code_by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages
example:
en","type":"string"},"language_name":{"description":"full name of the language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available Google Shopping languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages
example:
English","type":"string"},"location_code":{"description":"location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available Google Shopping locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations
example:
2840","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:
53.476225,-2.243572,200","type":"string"},"location_name":{"description":"full name of the location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available Google Shopping locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations
example:
London,England,United Kingdom","type":"string"},"max_crawl_pages":{"description":"page crawl limit
optional field
number of search results pages to crawl
max value: 7
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center","type":["integer","null"]},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_data":{"description":"postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:
advanced, html","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"price_max":{"description":"maximum product price
optional field
maximum price of the returned products listed on Google Shopping for the specified query
example:
100
Note: if you specify price_max, the search_param parameter will be ignored","type":["integer","null"]},"price_min":{"description":"minimum product price
optional field
minimum price of the returned products listed on Google Shopping for the specified query
example:
5
Note: if you specify price_min, the search_param parameter will be ignored","type":["integer","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"se_domain":{"description":"search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
google.co.uk, google.com.au, google.de, etc.","type":["string","null"]},"search_param":{"description":"additional parameters of the search query
optional field
you can use the following search URL parameters for customizing the search;
example:
&tbs=ppr_min:45 – search for products that cost more than 45 USD;
&tbs=ppr_max:50 – search for products that cost less than 50 USD;
&tbs=p_ord:p – sort by ascending price;
&tbs=p_ord:pd – sort by descending price;
&tbs=p_ord:rv – sort by review score;
&tbs=ppr_max:50,p_ord:rv – sort by review score with the maximum price of 50 USD.;
&udm=28 – use new Google Shopping markup with 40 SERP results returned by default (the cost for one SERP is deducted accordingly); the maximum depth is 200; this parameter must be specified without tbm=shop in the url;
&shoprs=$value – specify advanced filtering and sorting in the new Shopping markup; replace $value with a string in protobuf Base64 format; learn more on our help center.

Note that search_param values will be ignored if any of the following parameters are used: price_min, price_max, sort_by","type":["string","null"]},"sort_by":{"description":"results sorting rules
optional field
the following sorting rules are supported:
review_score, price_low_to_high, price_high_to_low
example:
sort_by:\"review_score\"
Note: if you specify sort_by, the search_param parameter will be ignored","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"url":{"description":"direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.com/search?q=fish&hl=en&gl=US&gws_rd=cr&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Merchant google products task post"},{"name":"merchant_google_sellers_ad_url_shop_ad_aclk","description":"Google Shopping Sellers Ad URL is designed to provide you with a full URL of the advertisement containing all additional parameters set by the seller.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"shop_ad_aclk":{"description":"unique ad click referral parameter
you can obtain this parameter with Google Shopping Products or Google Shopping Sellers","type":"string"}},"required":["shop_ad_aclk"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Merchant google sellers ad url shop ad aclk"},{"name":"merchant_google_sellers_task_get_advanced_id","description":"Description of the fields for sending a request:","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Merchant google sellers task get advanced id"},{"name":"merchant_google_sellers_task_post","description":"‌‌\nGoogle Shopping Sellers endpoint will provide you with the list of top 10 sellers that listed the specified product on Google Shopping. The provided data for each seller includes related product base and total price, shipment and purchase details and special offers. The results are specific to the selected location (see the List of Locations) and language (see the List of Languages) settings.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"language_code":"en","location_code":2840,"product_id":"1113158713975221117"}]],"items":{"oneOf":[{"examples":[[{"language_code":"en","location_code":2840,"product_id":"1113158713975221117"}]],"properties":{"additional_specifications":{"additionalProperties":{"type":["string","null"]},"description":"object containing additional url parameters
you can get additional information about the product by using the \"additional_specifications object, which you can get by making a separate request to the Google Shopping Products endpoint
example:
\"additional_specifications\": { \"eto\": \"16157121050167572763_0\" }","type":["object","null"]},"data_docid":{"description":"unique identifier of the SERP data element
required field if product_id or gid is not specified
we recommend specifying data_docid together with product_id and gid for optimal results;
you can get this value for a certain element by making a separate request to the Google Shopping Products endpoint
example:
13071766526042404278","type":"string"},"depth":{"description":"parsing depth
optional field
number of results to be retrieved from Google Shopping SERP
default value: 10
max value: 200
your account will be billed per each SERP containing up to 10 results;
setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
the cost can be calculated on the Pricing page","type":["integer","null"]},"get_shops_on_google":{"description":"include \"buy on Google\" shops
optional field
if set to true, the response will contain the list of sellers that allow to purchase a given product directly on Google
Note: if set to true, the cost of a task will be doubled","type":["boolean","null"]},"gid":{"description":"global product identifier on Google Shopping
required field if product_id or data_docid is not specified
we recommend specifying gid together with product_id and data_docid for optimal results;
you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint
example:
4702526954592161872
learn more about the parameter in this help center guide","type":"string"},"language_code":{"description":"language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available Google Shopping languages with their language_code_by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages
example:
en","type":"string"},"language_name":{"description":"full name of the language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available Google Shopping languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages
example:
English","type":"string"},"location_code":{"description":"location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available Google Shopping locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations
example:
2840","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:
53.476225,-2.243572,200","type":"string"},"location_name":{"description":"full name of the location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available Google Shopping locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations
example:
London,England,United Kingdom","type":"string"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_data":{"type":["string","null"]},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"product_id":{"description":"unique product identifier on Google Shopping
required field if data_docid or gid is not specified
we recommend specifying product_id together with data_docid and gid for optimal results;
you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint
example:
4485466949985702538
learn more about the parameter in this help center guide","type":"string"},"pvf":{"description":"product variant filter on Google Shopping
optional field
parameter in Google Shopping URL, setting optional product variant filtration;
example:
Eg4iBWNvbG9yKgV3aGl0ZRISIgxwYWNrYWdlIHNpemUqAjE0EgoiBHNpemUqAnhs","type":["string","null"]},"se_domain":{"description":"search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
google.co.uk, google.com.au, google.de, etc.","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Merchant google sellers task post"},{"name":"on_page_content_parsing","description":"‌‌\nThis endpoint allows parsing the content on any page you specify and will return the structured content of the target page, including link URLs, anchors, headings, and textual content.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"id":"11161551-1535-0216-0000-500b3f307f92","url":"https://dataforseo.com/blog/a-versatile-alternative-to-google-trends-exploring-the-power-of-dataforseo-trends-api"}]],"items":{"oneOf":[{"examples":[[{"id":"11161551-1535-0216-0000-500b3f307f92","url":"https://dataforseo.com/blog/a-versatile-alternative-to-google-trends-exploring-the-power-of-dataforseo-trends-api"}]],"properties":{"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
note: the enable_content_parsing parameter in the POST request must be set to true
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"markdown_view":{"description":"return page content as markdown
optional field
if set to true, the markdown-formatted content of the page will be returned in the page_as_markdown field of the response;
default value: false","type":["boolean","null"]},"url":{"description":"URL of the content to parse
required field
URL of the page to parse
example:
`https://dataforseo.com/blog/a-versatile-alternative-to-google-trends-exploring-the-power-of-dataforseo-trends-api`","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page content parsing"},{"name":"on_page_content_parsing_live","description":"‌‌\nThis endpoint allows parsing the content on any page you specify and will return the structured content of the target page, including link URLs, anchors, headings, and textual content.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"url":"https://dataforseo.com/blog/a-versatile-alternative-to-google-trends-exploring-the-power-of-dataforseo-trends-api"}]],"items":{"oneOf":[{"examples":[[{"url":"https://dataforseo.com/blog/a-versatile-alternative-to-google-trends-exploring-the-power-of-dataforseo-trends-api"}]],"properties":{"accept_language":{"description":"language header for accessing the website
optional field
all locale formats are supported (xx, xx-XX, xxx-XX, etc.)
Note: if you do not specify this parameter, some websites may deny access; in this case, pages will be returned with the \"type\":\"broken in the response array","type":["string","null"]},"browser_preset":{"description":"preset for browser screen parameters
optional field
if you use this field, you don't need to indicate browser_screen_width, browser_screen_height, browser_screen_scale_factor
possible values:
desktop, mobile, tablet
desktop preset will apply the following values:
browser_screen_width: 1920
browser_screen_height: 1080
browser_screen_scale_factor: 1
mobile preset will apply the following values:
browser_screen_width: 390
browser_screen_height: 844
browser_screen_scale_factor: 3
tablet preset will apply the following values:
browser_screen_width: 1024
browser_screen_height: 1366
browser_screen_scale_factor: 2
Note: to use this parameter, set enable_javascript or enable_browser_rendering to true","type":["string","null"]},"browser_screen_height":{"description":"browser screen height
optional field
you can set a custom browser screen height to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;
Note: to use this parameter, set enable_javascript or enable_browser_rendering to true
minimum value, in pixels: 240
maximum value, in pixels: 9999","type":["integer","null"]},"browser_screen_scale_factor":{"description":"browser screen scale factor
optional field
you can set a custom browser screen resolution ratio to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;
Note: to use this parameter, set enable_javascript or enable_browser_rendering to true
minimum value: 0.5
maximum value: 3","type":["number","null"]},"browser_screen_width":{"description":"browser screen width
optional field
you can set a custom browser screen width to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;
Note: to use this parameter, set enable_javascript or enable_browser_rendering to true
minimum value, in pixels: 240
maximum value, in pixels: 9999","format":"int64","type":["integer","null"]},"custom_user_agent":{"description":"custom user agent
optional field
custom user agent for crawling a website
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36
default value: Mozilla/5.0 (compatible; RSiteAuditor)","type":["string","null"]},"disable_cookie_popup":{"description":"disable the cookie popup
optional field
set to true if you want to disable the popup requesting cookie consent from the user;
default value:
false","type":["boolean","null"]},"enable_browser_rendering":{"description":"emulate browser rendering to measure Core Web Vitals
optional field
by using this parameter you will be able to emulate a browser when loading a web page;
enable_browser_rendering loads styles, images, fonts, animations, videos, and other resources on a page;
default value: false
set to true to obtain Core Web Vitals (FID, CLS, LCP) metrics in the response;
if you use this field, enable_javascript, and load_resources parameters must be set to true
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page","type":["boolean","null"]},"enable_javascript":{"description":"load javascript on a page
optional field
set to true if you want to load the scripts available on a page
default value: false
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page","type":["boolean","null"]},"enable_xhr":{"description":"enable XMLHttpRequest on a page
optional field
set to true if you want our crawler to request data from a web server using the XMLHttpRequest object
default value:
false
if you use this field, enable_javascript must be set to true;","type":["boolean","null"]},"ip_pool_for_scan":{"description":"proxy pool
optional field
you can choose a location of the proxy pool that will be used to obtain the requested data;
the parameter can be used if page content is inaccessible in one of the locations, resulting in occasional site_unreachable errors
possible values: us, de","type":["string","null"]},"markdown_view":{"description":"return page content as markdown
optional field
if set to true, the markdown-formatted content of the page will be returned in the page_as_markdown field of the response;
default value: false","type":["boolean","null"]},"store_raw_html":{"description":"store HTML of a crawled page
optional field
set to true if you want to get the HTML of the page using the OnPage Raw HTML endpoint
default value: false","type":["boolean","null"]},"switch_pool":{"description":"switch proxy pool
optional field
if true, additional proxy pools will be used to obtain the requested data;
the parameter can be used if a multitude of tasks is set simultaneously, resulting in occasional rate-limit and/or site_unreachable errors","type":["boolean","null"]},"url":{"description":"URL of the content to parse
required field
URL of the page to parse
example:
`https://www.fujielectric.com/`","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page content parsing live"},{"name":"on_page_duplicate_content","description":"‌‌\nThis endpoint returns a list of pages that have content similar to the page specified in the request. The response also contains data related to page performance and the similarity index that indicates how similar the compared pages are.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"id":"07281559-0695-0216-0000-c269be8b7592","url":"https://www.etsy.com/"}]],"items":{"oneOf":[{"examples":[[{"id":"07281559-0695-0216-0000-c269be8b7592","url":"https://www.etsy.com/"}]],"properties":{"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"limit":{"description":"the maximum number of returned pages
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned pages
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages","type":["integer","null"]},"similarity":{"description":"content similarity score
by default, the content is considered duplicate if the value is greater than or equals 6
you can specify any similarity score in the 0-to-10 range","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]},"url":{"description":"page URL
required field
specify the initial page you want to receive duplicate content for","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page duplicate content"},{"name":"on_page_duplicate_tags","description":"‌‌\nThis endpoint returns a list of pages that contain duplicate title or description tags. The response also contains data related to page performance.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"id":"07281559-0695-0216-0000-c269be8b7592","limit":10,"type":"duplicate_description"}]],"items":{"oneOf":[{"examples":[[{"id":"07281559-0695-0216-0000-c269be8b7592","limit":10,"type":"duplicate_description"}]],"properties":{"accumulator":{"description":"tag value
optional field
specify a title or description here if you want to receive a list of duplicate pages that contains this tag","type":["string","null"]},"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"limit":{"description":"the maximum number of returned pages
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned pages
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]},"type":{"description":"type of element","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page duplicate tags"},{"name":"on_page_keyword_density","description":"‌‌\nThis endpoint will provide you with keyword density and keyword frequency data for terms appearing on the specified website or web page. You can filter and sort the data that will be retrieved with this API call.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":["frequency",">",5],"id":"09101923-1535-0216-0000-2389a8854b70","keyword_length":2,"url":"https://dataforseo.com/"}]],"items":{"oneOf":[{"examples":[[{"filters":["frequency",">",5],"id":"09101923-1535-0216-0000-2389a8854b70","keyword_length":2,"url":"https://dataforseo.com/"}]],"properties":{"filters":{"description":"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, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"keyword\",\"=\",\"%seo%\"]
[[\"keyword\",\"=\",\"%seo%\"], \"and\", [\"frequency\",\"<\",\"6\"]]
[[\"keyword\",\"not_like\",\"%seo%\"], \"and\", [[\"frequency\",\">\",\"6\"],\"or\",[\"density\",\">\",\"0.02\"]]]
The full list of possible filters is available by this link.","items":{"type":["object","null"]},"type":["array","null"]},"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"keyword_length":{"description":"number of words for a keyword
required field
possible values:
1, 2, 3, 4, 5","type":"integer"},"limit":{"description":"the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"order_by":{"description":"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:
[\"frequency,desc\"]
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,asc\",\"frequency,desc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"url":{"description":"page URL
optional field
if you do not specify a page here, the results will be provided for the whole website
if you use this field, the API response will contain only keywords from the specified page
a page should be specified with absolute URL (including http:// or https://)","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page keyword density"},{"name":"on_page_lighthouse_audits","description":"The OnPage Lighthouse API is based on Google’s open-source Lighthouse project and provides data on the quality of web pages.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page lighthouse audits"},{"name":"on_page_lighthouse_live_json","description":"‌The OnPage Lighthouse API is based on Google’s open-source Lighthouse project for measuring the quality of web pages and web apps.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"for_mobile":true,"tag":"some_string_123","url":"https://dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"for_mobile":true,"tag":"some_string_123","url":"https://dataforseo.com"}]],"properties":{"audits":{"description":"Lighthouse audits
optional field
audits are individual tests Lighthouse runs for each specific feature/optimization/metric to produce a numeric score (see official definition);
if you ignore this field, we will return data for all audits;
use this field to get data for specific audits you indicate here;
Note: that some audits do not belong to a specific category and are stand-alone page quality measurements;
in general, there can be several use cases:
1. if you ignore categories, you can use this field to get data for the specified audits only
for example, if you ignore \"categories\" and specify \"audits\": [\"metrics/cumulative-layout-shift\",\"metrics/largest-contentful-paint\",\"metrics/total-blocking-time\"], you will get data only for these audits
2. if you specify a category, you can use this field to additionally receive audits that do not belong to the category(-ies) you specified
for example, if you specify \"categories\": [\"seo\"] and \"audits\": [\"metrics/cumulative-layout-shift\",\"metrics/largest-contentful-paint\",\"metrics/total-blocking-time\"], you will get only these audits under \"performance\" and all audits under \"seo\"
you can get the full list of possible audits here","items":{"type":"string"},"type":["array","null"]},"browser_cpu_throttling_multiplier":{"description":"browser CPU throttling multiplier
required if browser_network_throttling_method is set to devtools;
set the CPU throttling multiplier to simulate device performance conditions during the Lighthouse audit;
can be specified within the following range: 1–4;
Note: this parameter is applied only when browser_network_throttling_method is set to devtools;","type":["number","null"]},"browser_network_throttling":{"description":"browser network throttling
required if browser_network_throttling_method is set to devtools;
set the network throttling profile to simulate connection speed conditions during the Lighthouse audit;
possible values: no_throttling, fast_4g, slow_4g, regular_3g, pc;
Note: this parameter is applied only when browser_network_throttling_method is set to devtools;","type":["string","null"]},"browser_network_throttling_method":{"description":"browser network throttling method
optional field
defines the method used to apply throttling during the Lighthouse audit;
possible vaules:
simulate - calculates estimated performance metrics without applying explicit throttling;
devtools - applies the throttling settings specified in browser_network_throttling and browser_cpu_throttling_multiplier;
provided - uses the network conditions of the crawling environment;","type":["string","null"]},"browser_screen_height":{"description":"browser screen height
optional field
set the screen height of the browser used for the Lighthouse audit to emulate a specific device;
can be specified within the following range: 240–9999;","type":["integer","null"]},"browser_screen_scale_factor":{"description":"browser screen scale factor
optional field
set the device pixel ratio of the browser used for the Lighthouse audit;
can be specified within the following range: 0.5–3;","type":["number","null"]},"browser_screen_width":{"description":"browser screen width
optional field
set the screen width of the browser used for the Lighthouse audit to emulate a specific device;
can be specified within the following range: 240–9999;","format":"int64","type":["integer","null"]},"categories":{"description":"categories of Lighthouse audits
optional field
each category is a collection of audits and audit groups that applies weighting and scoring to the section (see official definition)
if you ignore this field, we will return data for all categories unless you specify audits
use this field to get data for specific categories you indicate here
possible values:
seo, performance, best_practices, accessibility","items":{"type":"string"},"type":["array","null"]},"custom_user_agent":{"description":"custom user agent
optional field
specify the custom user agent used by the browser when running the Lighthouse audit;
can be specified with up to 254 characters;","type":["string","null"]},"for_mobile":{"description":"applies mobile emulation
optional field
if set to true, Lighthouse will use mobile device and screen emulation to test the page against mobile environment
if set to false, the results will be provided for desktop
default value: false","type":["boolean","null"]},"language_code":{"description":"lighthouse language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/on_page/lighthouse/languages
default value:
en","type":["string","null"]},"language_name":{"description":"lighthouse language name
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/on_page/lighthouse/languages
default value:
English","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"url":{"description":"target URL
required field
target page should be specified with its absolute URL (including http:// or https://)
example:
https://dataforseo.com/","type":"string"},"version":{"description":"lighthouse version
optional field
you can obtain the results specific to a certain Lighthouse version by specifying its number
the list of available versions is available through the Lighthouse Versions endpoint","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page lighthouse live json"},{"name":"on_page_links","description":"‌‌\nThis endpoint will provide you with a list of internal and external links detected on a target website.\nThe following link types are supported:\nanchor – links that point to a specific portion of a webpage;\nimage – links that point to an image;\ncanonical – links that point to a canonical page;\nmeta – links with meta http-equiv=refresh ;\nalternate – links with link rel=\"alternate\" pointing to an alternative version of a webpage ;\nredirect – links with redirect status.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["dofollow","=",true],"and",["direction","=","external"]],"id":"07281559-0695-0216-0000-c269be8b7592","limit":10,"page_from":"/apis/google-trends-api"}]],"items":{"oneOf":[{"examples":[[{"filters":[["dofollow","=",true],"and",["direction","=","external"]],"id":"07281559-0695-0216-0000-c269be8b7592","limit":10,"page_from":"/apis/google-trends-api"}]],"properties":{"filters":{"description":"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, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"direction\",\"=\",\"external\"]
[[\"domain_to\",\"<>\",\"example.com\"], \"and\", [\"link_from\",\"not_like\",\"%example.com/blog%\"]]
[[\"direction\",\"=\",\"external\"], \"and\", [[\"link_from\",\"like\",\"%example.com/blog%\"],\"or\",[\"link_from\",\"like\",\"%example.com/help%\"]]]
The full list of possible filters is available by this link.","items":{"type":["object","null"]},"type":["array","null"]},"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"limit":{"description":"the maximum number of returned links
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned links
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten links in the results array will be omitted and the data will be provided for the successive links","type":["integer","null"]},"page_from":{"description":"relative page URL
optional field
if you use this field, the API response will contain only links from the specified page
note that in this field you can specify relative URLs only","type":["string","null"]},"page_to":{"description":"relative page URL
optional field
if you use this field, the API response will contain only internal links pointing to the specified page
note that in this field you can specify relative URLs only","type":["string","null"]},"search_after_token":{"description":"token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request;
by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;
search_after_token values are unique for each subsequent task ;
Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request","type":["string","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page links"},{"name":"on_page_microdata","description":"‌‌\nThis endpoint is designed to validate structured JSON-LD data and Microdata. Using this function you will obtain microdata available on the specified page of the target website and detailed results of its validation.\nTo use this endpoint, set the validate_micromarkup parameter to true in the POST request to OnPage API.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"id":"02241700-1535-0216-0000-034137259bc1","url":"https://dataforseo.com/apis"}]],"items":{"oneOf":[{"examples":[[{"id":"02241700-1535-0216-0000-034137259bc1","url":"https://dataforseo.com/apis"}]],"properties":{"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"tag":{"description":"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","type":["string","null"]},"url":{"description":"resource URL
required field
you can get this URL in the response of the Pages endpoint
example:
https://dataforseo.com/apis","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page microdata"},{"name":"on_page_non_indexable","description":"‌‌\nThis endpoint returns a list of pages that are blocked from being indexed by Google and other search engines through robots.txt, HTTP headers, or meta tags settings.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["reason","=","robots_txt"],"and",["url","like","%go%"]],"id":"07281559-0695-0216-0000-c269be8b7592","limit":10}]],"items":{"oneOf":[{"examples":[[{"filters":[["reason","=","robots_txt"],"and",["url","like","%go%"]],"id":"07281559-0695-0216-0000-c269be8b7592","limit":10}]],"properties":{"filters":{"description":"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, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[[\"reason\",\"<>\",\"robots_txt\"], \"and\", [\"url\",\"not_like\",\"%/wp-admin/%\"]]
[[\"url\",\"not_like\",\"%/wp-admin/%\"], \"and\", [[\"reason\",\"<>\",\"meta_tag\"],\"or\",[\"reason\",\"<>\",\"http_header\"]]]
The full list of possible filters is available by this link.","items":{"type":["object","null"]},"type":["array","null"]},"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"limit":{"description":"the maximum number of returned pages
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned pages
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages","type":["integer","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page non indexable"},{"name":"on_page_page_screenshot","description":"‌‌\nUsing this endpoint, you can capture a full high-quality screenshot of any webpage. In this way, you can review the target page as the DataForSEO crawler and Googlebot see it.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"url":"https://dataforseo.com/apis"}]],"items":{"oneOf":[{"examples":[[{"url":"https://dataforseo.com/apis"}]],"properties":{"accept_language":{"description":"language header for accessing the website
optional field
all locale formats are supported (xx, xx-XX, xxx-XX, etc.)
note: if you do not specify this parameter, some websites may deny access; in this case, you will obtain \"error_message\":\"Screenshot is empty\" in the response array","type":["string","null"]},"browser_preset":{"description":"preset for browser screen parameters
optional field
if you use this field, you don't need to indicate browser_screen_width, browser_screen_height, browser_screen_scale_factor
possible values:
desktop, mobile, tablet
desktop preset will apply the following values:
browser_screen_width: 1920
browser_screen_height: 1080
browser_screen_scale_factor: 1
mobile preset will apply the following values:
browser_screen_width: 390
browser_screen_height: 844
browser_screen_scale_factor: 3
tablet preset will apply the following values:
browser_screen_width: 1024
browser_screen_height: 1366
browser_screen_scale_factor: 2
Note: in this endpoint, the enable_browser_rendering, enable_javascript, load_resources, and enable_xhr parameters are always enabled.","type":["string","null"]},"browser_screen_height":{"description":"browser screen height
optional field
you can set a custom browser screen height to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;
minimum value, in pixels: 240
maximum value, in pixels: 9999","type":["integer","null"]},"browser_screen_scale_factor":{"description":"browser screen scale factor
optional field
you can set a custom browser screen resolution ratio to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;
minimum value: 0.5
maximum value: 3","type":["number","null"]},"browser_screen_width":{"description":"browser screen width
optional field
you can set a custom browser screen width to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;
minimum value, in pixels: 240
maximum value, in pixels: 9999","format":"int64","type":["integer","null"]},"custom_user_agent":{"description":"custom user agent
optional field
custom user agent for crawling a website
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36
default value: Mozilla/5.0 (compatible; RSiteAuditor)","type":["string","null"]},"disable_cookie_popup":{"description":"disable the cookie popup
optional field
set to true if you want to disable the popup requesting cookie consent from the user;
default value:
false","type":["boolean","null"]},"full_page_screenshot":{"description":"take a screenshot of the full page
optional field
set to false if you want to capture only the part of the page displayed before scrolling
default value: true","type":["boolean","null"]},"ip_pool_for_scan":{"description":"proxy pool
optional field
you can choose a location of the proxy pool that will be used to obtain the requested data;
the parameter can be used if page content is inaccessible in one of the locations, resulting in occasional site_unreachable errors
possible values: us, de","type":["string","null"]},"switch_pool":{"description":"switch proxy pool
optional field
if true, additional proxy pools will be used to obtain the requested data;
the parameter can be used if a multitude of tasks is set simultaneously, resulting in occasional rate-limit and/or site_unreachable errors","type":["boolean","null"]},"url":{"description":"page url
required field
absolute URL of the page to snap
note: if the URL you indicate here returns a 404 status code or the indicated value is not a valid URL, you will obtain \"error_message\":\"Screenshot is empty\" in the response array","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page page screenshot"},{"name":"on_page_pages","description":"This endpoint returns a list of crawled pages with on-page check-ups and other metrics related to the page performance.\nUsing this function you will get page-specific data with detailed information on how well your pages are optimized for search.\nfor more info please visit 'https://docs.dataforseo.com/v3/on_page/pages/?bash'","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["resource_type","=","html"],"and",["meta.scripts_count",">",40]],"id":"07281559-0695-0216-0000-c269be8b7592","limit":10,"order_by":["meta.content.plain_text_word_count,desc"]}]],"items":{"oneOf":[{"examples":[[{"filters":[["resource_type","=","html"],"and",["meta.scripts_count",">",40]],"id":"07281559-0695-0216-0000-c269be8b7592","limit":10,"order_by":["meta.content.plain_text_word_count,desc"]}]],"properties":{"filters":{"description":"array of results filtering parametersoptional fieldyou can add several filters at once (8 filters maximum)you should set a logical operator and, or between the conditionsthe following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_likeyou can use the % operator with like and not_like to match any string of zero or more charactersexample:[\"meta.external_links_count\",\"<=\",50][\"url\",\"like\",\"https://dataforseo.com/apis/dataforseo-labs-api\"][[\"checks.high_waiting_time\",\"=\",false],\"and\",[\"resource_type\",\"=\",\"html\"]][[\"page_timing.duration_time\",\"<\",100],\"and\",[[\"checks.large_page_size\",\"=\",false],\"or\",[\"checks.high_waiting_time\",\"=\",false]]]The full list of possible filters is available by this link.","items":{"type":["object","null"]},"type":["array","null"]},"id":{"description":"ID of the taskrequired fieldyou can get this ID in the response of the Task POST endpointexample:\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"limit":{"description":"the maximum number of returned pagesoptional fielddefault value: 100maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned pagesoptional fielddefault value: 0maximum value: 2000000if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages","type":["integer","null"]},"order_by":{"description":"results sorting rulesoptional fieldyou can use the same values as in the filters array to sort the resultspossible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending orderyou should use a comma to set up a sorting typeexample:[\"meta.external_links_count,desc\"]note that you can set no more than three sorting rules in a single requestyou should use a comma to separate several sorting rulesexample:[\"page_timing.dom_complete,asc\",\"size,desc\"]","items":{"type":"string"},"type":["array","null"]},"search_after_token":{"description":"token for subsequent requestsoptional fieldprovided in the identical filed of the response to each request;use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request;by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;search_after_token values are unique for each subsequent task ;Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request","type":["string","null"]},"tag":{"description":"user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page pages"},{"name":"on_page_pages_by_resource","description":"‌‌\nThis endpoint will return the list of pages where a specific resource is located. Using this function you will also get the data related to the pages that contain a specified resource.\nYou can get the URL of a resource using the Resources endpoint.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"id":"02241700-1535-0216-0000-034137259bc1","url":"https://www.etsy.com/about/jobs.workco2018.js?"}]],"items":{"oneOf":[{"examples":[[{"id":"02241700-1535-0216-0000-034137259bc1","url":"https://www.etsy.com/about/jobs.workco2018.js?"}]],"properties":{"filters":{"description":"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, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"meta.external_links_count\",\"<=\",50][\"url\",\"like\",\"https://dataforseo.com/apis/dataforseo-labs-api\"]
[[\"checks.high_waiting_time\",\"=\",false], \"and\",[\"resource_type\",\"=\",\"html\"]]
[[\"page_timing.duration_time\",\"<\",100],\"and\",[[\"checks.large_page_size\",\"=\",false],\"or\",[\"checks.high_waiting_time\",\"=\",false]]]
The full list of possible filters is available by this link.","items":{"type":["object","null"]},"type":["array","null"]},"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"limit":{"description":"the maximum number of returned pages
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned pages
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages","type":["integer","null"]},"order_by":{"description":"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:
[\"meta.external_links_count,desc\"]
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:
[\"page_timing.dom_complete,asc\",\"size,desc\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"url":{"description":"resource URL
required field
you can get this URL in the response of the Resources endpoint
example:
https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page pages by resource"},{"name":"on_page_raw_html","description":"‌‌\nThis endpoint returns the HTML of a page you indicate in the request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"id":"07281559-0695-0216-0000-c269be8b7592","url":"https://dataforseo.com/apis"}]],"items":{"oneOf":[{"examples":[[{"id":"07281559-0695-0216-0000-c269be8b7592","url":"https://dataforseo.com/apis"}]],"properties":{"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"url":{"description":"page url
required field
the absolute URL of a page to request HTML
Note: this field is optional if the task was set using the Instant Pages endpoint","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page raw html"},{"name":"on_page_redirect_chains","description":"‌‌\nRedirect chains occur when there are at least two redirects between the initial URL and the destination URL. For example, if page A redirects to page B which redirects to page C, such a series of redirects is considered a redirect chain. Sometimes, if page B redirects back to page A, the redirect chain becomes closed and is considered a redirect loop.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"id":"03051327-4536-0216-1000-3b458a2cfcca","url":"https://test_rdr.dataforseo.com/a/"}]],"items":{"oneOf":[{"examples":[[{"id":"03051327-4536-0216-1000-3b458a2cfcca","url":"https://test_rdr.dataforseo.com/a/"}]],"properties":{"filters":{"description":"array of results filtering parameters
optional field
you can use only one filtering parameter with this endpoint
the following filtering parameter is supported:
is_redirect_loop
the following operators are supported:
regex, not_regex, =, <>
examples:
[\"is_redirect_loop\",\"=\",\"true\"]
[\"is_redirect_loop\",\"<>\",\"false\"]","items":{"type":["object","null"]},"type":["array","null"]},"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"limit":{"description":"the maximum number of returned redirect chains
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned redirect chains
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten redirect chains in the results array will be omitted and the data will be provided for the successive redirect chains","type":["integer","null"]},"tag":{"description":"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","type":["string","null"]},"url":{"description":"page URL
optional field
absolute URL of the target page
if you use this field, the API response will return only redirect chains which contain the specified URL","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page redirect chains"},{"name":"on_page_resources","description":"‌‌\nThis endpoint will provide you with a list of resources, including images, scripts, stylesheets, and broken elements.\nYou will get a detailed overview of every resource found on the crawled pages.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["resource_type","=","image"],"and",["size",">",100000]],"id":"07281559-0695-0216-0000-c269be8b7592","limit":10,"order_by":["size,desc"]}]],"items":{"oneOf":[{"examples":[[{"filters":[["resource_type","=","image"],"and",["size",">",100000]],"id":"07281559-0695-0216-0000-c269be8b7592","limit":10,"order_by":["size,desc"]}]],"properties":{"filters":{"description":"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, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"resource_type\",\"=\",\"stylesheet\"]
[[\"resource_type\",\"=\",\"image\"], \"and\",[\"checks.is_https\",\"=\",false]]
[[\"fetch_timing.duration_time\",\">\",1],\"and\",[[\"total_transfer_size\",\">\",100],\"or\",[\"checks.high_loading_time\",\"=\",true]]]
The full list of possible filters is available by this link.","items":{"type":["object","null"]},"type":["array","null"]},"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"limit":{"description":"the maximum number of returned resources
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned resources
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten resources in the results array will be omitted and the data will be provided for the successive resources","type":["integer","null"]},"order_by":{"description":"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:
[\"size,desc\"]
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:
[\"size,desc\",\"fetch_timing.fetch_end,desc\"]","items":{"type":"string"},"type":["array","null"]},"relevant_pages_filters":{"description":"filter the resources by relevant pages
optional field
you can use this field to obtain resources from pages matching to the defined parameters
you can apply the same filters here as available for the pages endpoint
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, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[\"checks.no_image_title\",\"=\",true]","items":{"type":"string"},"type":["array","null"]},"search_after_token":{"description":"token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request;
by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;
search_after_token values are unique for each subsequent task ;
Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"url":{"description":"page URL
optional field
specify this field if you want to get the resources for a specific page
note that to obtain resource's meta from a particular URL, you should specify the URL in this field;
if you do not indicate a url when setting a task, resource's meta in the results will be returned based on the data from the page where our crawler first saw the resource","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page resources"},{"name":"on_page_summary_id","description":"‌\nUsing this function, you can get the overall information on a website as well as drill down into exact on-page issues of a website that has been scanned. As a result, you will know what functions to use for receiving detailed data for each of the found issues.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
required field
you can get this ID in the response of the Task POST endpoint
example:
“07131248-1535-0216-1000-17384017ad04”","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page summary id"},{"name":"on_page_task_post","description":"‌\nOnPage API checks websites for 60+ customizable on-page parameters defines and displays all found flaws and opportunities for optimization so that you can easily fix them. It checks meta tags, duplicate content, image tags, response codes, and other parameters on every page. You can find the full list of OnPage API check-up parameters in the Pages section.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"custom_js":"meta = {}; meta.url = document.URL; meta;","enable_javascript":true,"load_resources":true,"max_crawl_pages":10,"pingback_url":"https://your-server.com/pingscript?id=$id&tag=$tag","tag":"some_string_123","target":"dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"custom_js":"meta = {}; meta.url = document.URL; meta;","enable_javascript":true,"load_resources":true,"max_crawl_pages":10,"pingback_url":"https://your-server.com/pingscript?id=$id&tag=$tag","tag":"some_string_123","target":"dataforseo.com"}]],"properties":{"accept_language":{"description":"language header for accessing the website
optional field
all locale formats are supported (xx, xx-XX, xxx-XX, etc.)
Note: if you do not specify this parameter, some websites may deny access; in this case, pages will be returned with the \"type\":\"broken in the response array","type":["string","null"]},"allow_subdomains":{"description":"include pages on subdomains
optional field
set to true if you want to crawl all subdomains of a target website
default value: false","type":["boolean","null"]},"allowed_subdomains":{"description":"subdomains to crawl
optional field
specify subdomains that you want to crawl
example: [\"blog.site.com\", \"my.site.com\", \"shop.site.com\"]
Note: to use this parameter, the allow_subdomains parameter should be set to false;
otherwise, the content of allowed_subdomains field will be ignored and the results will be returned for all subdomains","items":{"type":"string"},"type":["array","null"]},"browser_preset":{"description":"preset for browser screen parameters
optional field
if you use this field, you don't need to indicate browser_screen_width, browser_screen_height, browser_screen_scale_factorpossible values:
desktop, mobile, tabletdesktop preset will apply the following values:browser_screen_width: 1920
browser_screen_height: 1080
browser_screen_scale_factor: 1mobile preset will apply the following values:browser_screen_width: 390
browser_screen_height: 844
browser_screen_scale_factor: 3tablet preset will apply the following values:browser_screen_width: 1024
browser_screen_height: 1366
browser_screen_scale_factor: 2
Note: to use this parameter, set enable_javascript or enable_browser_rendering to true","type":["string","null"]},"browser_screen_height":{"description":"browser screen height
optional field
you can set a custom browser screen height to perform an audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;
Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value, in pixels: 240
maximum value, in pixels: 9999","type":["integer","null"]},"browser_screen_scale_factor":{"description":"browser screen scale factor
optional field
you can set a custom browser screen resolution ratio to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;
Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value: 0.5
maximum value: 3","type":["number","null"]},"browser_screen_width":{"description":"browser screen width
optional field
you can set a custom browser screen width to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;
Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value, in pixels: 240
maximum value, in pixels: 9999","format":"int64","type":["integer","null"]},"calculate_keyword_density":{"description":"calculate keyword density for the target domain
optional field
set to true if you want to calculate keyword density for website pages
default value: false
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article
once the crawl is completed, you can obtain keyword density values with the Keyword Density endpoint","type":["boolean","null"]},"check_spell":{"description":"check spelling
optional field
set to true to check spelling on a website using Hunspell library
default value: false","type":["boolean","null"]},"check_spell_exceptions":{"description":"words excluded from spell check
optional field
specify the words that you want to exclude from spell check
maximum word length: 100 characters
maximum amount of words: 1000
example: \"SERP\", \"minifiers\", \"JavaScript\"","items":{"type":"string"},"type":["array","null"]},"check_spell_language":{"description":"language of the spell check
optional field
supported languages: 'hy', 'eu', 'bg', 'ca', 'hr', 'cs', 'da', 'nl', 'en', 'eo', 'et', 'fo', 'fa', 'fr', 'fy', 'gl', 'ka', 'de', 'el', 'he', 'hu', 'is', 'ia', 'ga', 'it', 'rw', 'la', 'lv', 'lt', 'mk', 'mn', 'ne', 'nb', 'nn', 'pl', 'pt', 'ro', 'gd', 'sr', 'sk', 'sl', 'es', 'sv', 'tr', 'tk', 'uk', 'vi'
Note: if no language is specified, it will be set automatically based on page content","type":["string","null"]},"checks_threshold":{"additionalProperties":{"format":"int64","type":["integer","null"]},"description":"custom threshold values for checks
optional field
you can specify custom threshold values for the parameters included in the checks object of OnPage API responses;
Note: only integer threshold values can be modified;
for example, the high_loading_time and large_page_size parameters are set to 3 seconds and 1 megabyte respectively by default;
if you want to change these thresholds to 1 second and 1000 kbytes, use the following snippet:
`\"checks_threshold\": {
\"high_loading_time\": 1,
\"large_page_size\": 1000
}`
available customizable parameters with default values:
`\"title_too_short\", default value: 30, type: \"int\"
\"title_too_long\", default value: 65, type: \"int\"
\"small_page_size\", default value: 1024, type: \"int\"
\"large_page_size\", default value: 1048576 (1024 * 1024), type: \"int\"
\"low_character_count\", default value: 1024, type: \"int\"
\"high_character_count\", default value: 256000 (250 * 1024), type: \"int\"
\"low_content_rate\", default value: 0.1, type: \"float\"
\"high_content_rate\", default value: 0.9, type: \"float\"
\"high_loading_time\", default value: 3000, type: \"int\"
\"high_waiting_time\", default value: 1500, type: \"int\"
\"low_readability_rate\", default value: 15.0, type: \"float\"
\"irrelevant_description\", default value: 0.2, type: \"float\"
\"irrelevant_title\", default value: 0.3, type: \"float\"
\"irrelevant_meta_keywords\", default value: 0.6, type: \"float\"`","type":["object","null"]},"crawl_delay":{"description":"delay between hits, ms
optional field
the custom delay between crawler hits to the server
default value: 2000","type":["integer","null"]},"crawl_sitemap_only":{"description":"crawl only pages indicated in the sitemap
optional field
set to true if you want to crawl only the pages indicated in the sitemap
if you set this parameter to true and do not specify custom_sitemap, we will crawl the default sitemap
default value: false
Note: if you want to use this parameter, respect_sitemap should be true","type":["boolean","null"]},"custom_js":{"description":"custom javascript
optional field
Note: that the execution time for the script you enter here should be 700 ms maximum, for example, you can use the following JS snippet to check if the website contains Google Tag Manager as a scr attribute:
let meta = { haveGoogleAnalytics: false, haveTagManager: false };rnfor (var i = 0; i < document.scripts.length; i++) {rn let src = document.scripts[i].getAttribute(\"src\");rn if (src != undefined) {rn if (src.indexOf(\"analytics.js\") >= 0)rn meta.haveGoogleAnalytics = true;rntif (src.indexOf(\"gtm.js\") >= 0)rn meta.haveTagManager = true;rn }rn}rnmeta;the returned value depends on what you specified in this field. For instance, if you specify the following script:
`meta = {}; meta.url = document.URL; meta.test = 'test'; meta;`
as a response you will receive the following data:
`\"custom_js_response\": {
\"url\": \"https://dataforseo.com/\",
\"test\": \"test\"
}`
Note #2: the length of the script you enter must be no more than 2000 characters
Note #3: the serialized script response must be no more than 100000 characters. If it exceeds this limit, both `custom_js_response` and `custom_js_client_exception` will contain the following message: `your response was truncated because greater than 100000 symbols`","type":["string","null"]},"custom_robots_txt":{"description":"custom robots.txt settings
optional field
example: Disallow: /directory1/","type":["string","null"]},"custom_sitemap":{"description":"custom sitemap url
optional field
the URL of the page where the alternative sitemap is located
Note: if you want to use this parameter, respect_sitemap should be true","type":["string","null"]},"custom_user_agent":{"description":"custom user agent
optional field
custom user agent for crawling a website
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36
default value: Mozilla/5.0 (compatible; RSiteAuditor)","type":["string","null"]},"disable_cookie_popup":{"description":"disable the cookie popup
optional field
set to true if you want to disable the popup requesting cookie consent from the user;
default value:
false","type":["boolean","null"]},"disable_page_checks":{"description":"prevent certain page checks from running
optional field
specify certain checks to prevent them from running and impacting the onpage_scoreexample:
\"disable_page_checks\": [\"is_5xx_code\", \"is_4xx_code\"]","items":{"type":"string"},"type":["array","null"]},"disable_sitewide_checks":{"description":"prevent certain sitewide checks from running
optional field
specify the following checks to prevent them from running on the target website:
\"test_page_not_found\"
\"test_canonicalization\"
\"test_https_redirect\"
\"test_directory_browsing\"example:
\"disable_sitewide_checks\": [\"test_directory_browsing\", \"test_page_not_found\"]learn more on our help center","items":{"type":"string"},"type":["array","null"]},"disallowed_subdomains":{"description":"subdomains not to crawl
optional field
specify subdomains that you don't want to crawl
example: [\"status.site.com\", \"docs.site.com\"]
Note: to use this parameter, the allow_subdomains parameter should be set to true","items":{"type":"string"},"type":["array","null"]},"enable_browser_rendering":{"description":"emulate browser rendering to measure Core Web Vitals
optional field
by using this parameter you will be able to emulate a browser when loading a web page;
enable_browser_rendering loads styles, images, fonts, animations, videos, and other resources on a page;
default value: false
set to true to obtain Core Web Vitals (FID, CLS, LCP) metrics in the response;
if you use this field, enable_javascript, and load_resources parameters must be set to true
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page","type":["boolean","null"]},"enable_content_parsing":{"description":"parse content on crawled pages
optional field
set to true to use the OnPage Content Parsing endpoint
default value: false
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page","type":["boolean","null"]},"enable_javascript":{"description":"load javascript on a page
optional field
set to true if you want to load the scripts available on a page
default value: false
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page","type":["boolean","null"]},"enable_www_redirect_check":{"description":"check if the domain implemented the www redirection
optional field
set to true if you want to check if the requested domain implemented the www to non-www or non-www to www redirect;
default value: false","type":["boolean","null"]},"enable_xhr":{"description":"enable XMLHttpRequest on a page
optional field
set to true if you want our crawler to request data from a web server using the XMLHttpRequest object
default value: false;if you use this field, enable_javascript must be set to true;","type":["boolean","null"]},"force_sitewide_checks":{"description":"enable sitewide checks when crawling a single page
optional field
set to true to get data on sitewide checks when crawling a single page;
default value: false","type":["boolean","null"]},"load_resources":{"description":"load resources
optional field
set to true if you want to load image, stylesheets, scripts, and broken resources
default value: false
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page","type":["boolean","null"]},"max_crawl_depth":{"description":"crawl depth
optional field
the linking depth of the pages to crawl;
for example, starting page of the crawl is level 0, pages that have links from that page are level 1, etc.","type":["integer","null"]},"max_crawl_pages":{"description":"crawled pages limit
required field
the number of pages to crawl on the specified domain
Note:
if you set max_crawl_pages to 1 and do not specify start_url or set a homepage in it, the following sitewide checks will be disabled:
test_canonicalization, enable_www_redirect_check, test_hidden_server_signature, test_page_not_found, test_directory_browsing, test_https_redirect
to enable them anyway, set force_sitewide_checks to trueif you set max_crawl_pages to 1 and specify start_url other than a homepage, all sitewide checks will be disabled;
to enable them anyway, set force_sitewide_checks to true","type":"integer"},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority_urls":{"description":"urls to be crawled bypassing the queue
optional field
URLs specified in this array will be crawled in the first instance, bypassing the crawling queue;
Note: you should specify the absolute URL;
you can specify up to 20 URLs;
all URLs in the array must belong to the target domain;
subdomains will be ignored unless the allow_subdomains parameter is set to trueexample:
`\"priority_urls\": [
\"https://dataforseo.com/apis/serp-api\",
\"https://dataforseo.com/contact\"
]`","items":{"type":"string"},"type":["array","null"]},"respect_sitemap":{"description":"respect sitemap when crawling
optional field
set to true if you want to follow the order of pages indicated in the primary sitemap when crawling;
default value: false
Note: if set to true, the click_depth value in the API response will equal 0;
the max_crawl_depth field of the request will be ignored, you can specify the number of pages to crawl using the max_crawl_pages parameter","type":["boolean","null"]},"return_despite_timeout":{"description":"return data on pages despite the timeout error
optional field
if true, the data will be provided on pages that failed to load within 120 seconds and responded with a timeout error;
default value: false","type":["boolean","null"]},"robots_txt_merge_mode":{"description":"merge with or override robots.txt settings
optional field
possible values: merge, override;
set to override if you want to ignore website crawling restrictions and other robots.txt settings
default value: merge;
Note: if set to override, specify the custom_robots_txt parameter","type":["string","null"]},"start_url":{"description":"the first url to crawl
optional field
Note: you should specify an absolute URL
if you want to crawl a single page, specify its URL in this field and additionally set the max_crawl_pages parameter to 1
you can also use the live Instant Pages endpoint to get page-specific data","type":["string","null"]},"store_raw_html":{"description":"store HTML of crawled pages
optional field
set to true if you want to get the HTML of the page using the OnPage Raw HTML endpoint
default value: false","type":["boolean","null"]},"support_cookies":{"description":"support cookies on crawled pages
optional field
set to true to support cookies when crawling the pages
default value: false","type":["boolean","null"]},"switch_pool":{"description":"switch proxy pool
optional field
if true, additional proxy pools will be used to obtain the requested data;
the parameter can be used if a multitude of tasks is set simultaneously, resulting in occasional rate-limit and/or site_unreachable errors","type":["boolean","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"target domain
required field
domain name should be specified without https:// and www.
if you specify the page URL, the results will be returned for the domain included in the URL","type":"string"},"validate_micromarkup":{"description":"enable microdata validation
optional field
set to true if you want to use the OnPage API Microdata endpoint
default value: false","type":["boolean","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page task post"},{"name":"on_page_uncrawlable_resources","description":"‌‌This endpoint returns a list of resources detected on the target website that could not be crawled due to a content type inconsistency. A resource is considered uncrawlable when the content type returned in the server response does not match the content type expected based on how the resource is referenced in the page HTML.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"filters":[["meta.content_type","=","image/jpeg"],"and",["url","like","%go%"]],"id":"07281559-0695-0216-0000-c269be8b7592","limit":10}]],"items":{"oneOf":[{"examples":[[{"filters":[["meta.content_type","=","image/jpeg"],"and",["url","like","%go%"]],"id":"07281559-0695-0216-0000-c269be8b7592","limit":10}]],"properties":{"filters":{"description":"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, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:
[[\"meta.content_type\",\"=\",\"image/jpeg\"], \"and\", [\"url\",\"not_like\",\"%/help-center/%\"]]
The full list of possible filters is available by this link.","items":{"type":["object","null"]},"type":["array","null"]},"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"limit":{"description":"the maximum number of returned uncrawlable resources
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"offset":{"description":"offset in the results array of returned uncrawlable resources
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten invalid resources in the results array will be omitted and the data will be provided for the successive invalid resources","type":["integer","null"]},"order_by":{"description":"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:
[\"meta.content_type,desc\"]
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:
[\"meta.content_type,asc\",\"fetch_time,desc\"]","items":{"type":"string"},"type":["array","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page uncrawlable resources"},{"name":"on_page_waterfall","description":"‌‌\nThis endpoint is designed to provide you with the page speed insights. Using this function you can get detailed information about the page loading time, time to secure connection, the time it takes to load page resources, and so on.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"id":"08101204-0696-0216-0000-644a7b21a48a","url":"https://dataforseo.com/tag/broken-links"}]],"items":{"oneOf":[{"examples":[[{"id":"08101204-0696-0216-0000-644a7b21a48a","url":"https://dataforseo.com/tag/broken-links"}]],"properties":{"id":{"description":"ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"","type":"string"},"tag":{"description":"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","type":["string","null"]},"url":{"description":"page URL
required field
specify the pages you want to receive timing for","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"On page waterfall"},{"name":"page_audit","description":"Using this function you will get page-specific data with detailed information on how well a particular page is optimized for organic search.\nfor more info please visit 'https://docs.dataforseo.com/v3/on_page/instant_pages/?bash'","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"custom_js":"meta = {}; meta.url = document.URL; meta;","enable_javascript":true,"url":"https://dataforseo.com/blog"}]],"items":{"oneOf":[{"examples":[[{"custom_js":"meta = {}; meta.url = document.URL; meta;","enable_javascript":true,"url":"https://dataforseo.com/blog"}]],"properties":{"accept_language":{"description":"language header for accessing the websiteoptional fieldall locale formats are supported (xx, xx-XX, xxx-XX, etc.)Note: if you do not specify this parameter, some websites may deny access; in this case, pages will be returned with the \"type\":\"broken in the response array","type":["string","null"]},"browser_preset":{"description":"preset for browser screen parametersoptional fieldif you use this field, you don't need to indicate browser_screen_width, browser_screen_height, browser_screen_scale_factorpossible values:desktop, mobile, tabletdesktop preset will apply the following values:browser_screen_width: 1920browser_screen_height: 1080browser_screen_scale_factor: 1mobile preset will apply the following values:browser_screen_width: 390browser_screen_height: 844browser_screen_scale_factor: 3tablet preset will apply the following values:browser_screen_width: 1024browser_screen_height: 1366browser_screen_scale_factor: 2Note: to use this parameter, set enable_javascript or enable_browser_rendering to true","type":["string","null"]},"browser_screen_height":{"description":"browser screen heightoptional fieldyou can set a custom browser screen height to perform audit for a particular device;if you use this field, you don't need to indicate browser_preset as it will be ignored;Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value, in pixels: 240maximum value, in pixels: 9999","type":["integer","null"]},"browser_screen_scale_factor":{"description":"browser screen scale factoroptional fieldyou can set a custom browser screen resolution ratio to perform audit for a particular device;if you use this field, you don't need to indicate browser_preset as it will be ignored;Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value: 0.5maximum value: 3","type":["number","null"]},"browser_screen_width":{"description":"browser screen widthoptional fieldyou can set a custom browser screen width to perform audit for a particular device;if you use this field, you don't need to indicate browser_preset as it will be ignored;Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value, in pixels: 240maximum value, in pixels: 9999","format":"int64","type":["integer","null"]},"check_spell":{"description":"check spellingoptional fieldset to true to check spelling on a website using Hunspell librarydefault value: false","type":["boolean","null"]},"checks_threshold":{"additionalProperties":{"format":"int64","type":["integer","null"]},"description":"custom threshold values for checksoptional fieldyou can specify custom threshold values for the parameters included in the checks array of OnPage API responses;Note: only integer threshold values can be modified;","type":["object","null"]},"custom_js":{"description":"custom javascriptoptional fieldNote that the execution time for the script you enter here should be 700 ms maximum;for example, you can use the following JS snippet to check if the website contains Google Tag Manager as a scr attribute:let meta = { haveGoogleAnalytics: false, haveTagManager: false };rnfor (var i = 0; i < document.scripts.length; i++) {rn let src = document.scripts[i].getAttribute(\"src\");rn if (src != undefined) {rn if (src.indexOf(\"analytics.js\") >= 0)rn meta.haveGoogleAnalytics = true;rntif (src.indexOf(\"gtm.js\") >= 0)rn meta.haveTagManager = true;rn }rn}rnmeta;the returned value depends on what you specified in this field. For instance, if you specify the following script:meta = {}; meta.url = document.URL; meta.test = 'test'; meta;as a response you will receive the following data:\"custom_js_response\": {\"url\": \"https://dataforseo.com/\",\"test\": \"test\"}","type":["string","null"]},"custom_user_agent":{"description":"custom user agentoptional fieldcustom user agent for crawling a websiteexample: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36default value: Mozilla/5.0 (compatible; RSiteAuditor)","type":["string","null"]},"disable_cookie_popup":{"description":"disable the cookie popup optional fieldset to true if you want to disable the popup requesting cookie consent from the user;default value:false","type":["boolean","null"]},"enable_browser_rendering":{"description":"emulate browser rendering to measure Core Web Vitalsoptional fieldby using this parameter you will be able to emulate a browser when loading a web page;enable_browser_rendering loads styles, images, fonts, animations, videos, and other resources on a page;default value: falseset to true to obtain Core Web Vitals (FID, CLS, LCP) metrics in the response;if you use this field, parameters enable_javascript, and load_resources are enabled automatically;Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page","type":["boolean","null"]},"enable_javascript":{"description":"load javascript on a pageoptional fieldset to true if you want to load the scripts available on a pagedefault value: falseNote: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page","type":["boolean","null"]},"enable_xhr":{"description":"enable XMLHttpRequest on a pageoptional fieldset to true if you want our crawler to request data from a web server using the XMLHttpRequest objectdefault value:falseif you use this field, enable_javascript must be set to true;","type":["boolean","null"]},"ip_pool_for_scan":{"description":"proxy pooloptional fieldyou can choose a location of the proxy pool that will be used to obtain the requested data;the parameter can be used if page content is inaccessible in one of the locations, resulting in occasional site_unreachable errorspossible values: us, de","type":["string","null"]},"load_resources":{"description":"load resourcesoptional fieldset to true if you want to load image, stylesheets, scripts, and broken resourcesdefault value: falseNote: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page","type":["boolean","null"]},"return_despite_timeout":{"description":"return data on pages despite the timeout erroroptional fieldif true, the data will be provided on pages that failed to load within 120 seconds and responded with a timeout error;default value: false","type":["boolean","null"]},"store_raw_html":{"description":"store HTML of a crawled pageoptional fieldset to true if you want get the HTML of the page using the OnPage Raw HTML endpointdefault value: false","type":["boolean","null"]},"switch_pool":{"description":"switch proxy pooloptional fieldif true, additional proxy pools will be used to obtain the requested data;the parameter can be used if a multitude of tasks is set simultaneously, resulting in occasional rate-limit and/or site_unreachable errors","type":["boolean","null"]},"url":{"description":"target page urlrequired fieldabsolute URL of the target page;Note #1: results will be returned for the specified URL only;Note #2: to prevent denial-of-service events, tasks that contain a duplicate crawl host will be returned with a 40501 error;to prevent this error from occurring, avoid setting tasks with the same domain if at least one of your previous tasks with this domain (including a page URL on the domain) is still in a crawling queue","type":"string"},"validate_micromarkup":{"description":"enable microdata validationoptional fieldif set to true, you can use the OnPage API Microdata endpoint with the id of the task;default value: false","type":["boolean","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Page audit","catalog":"web.page.audit"},{"name":"ranked_keywords","description":"‌\nThis 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.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"language_name":"English","limit":3,"load_rank_absolute":true,"location_name":"United States","target":"dataforseo.com"}]],"items":{"oneOf":[{"examples":[[{"language_name":"English","limit":3,"load_rank_absolute":true,"location_name":"United States","target":"dataforseo.com"}]],"properties":{"filters":{"description":"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","items":{"type":["object","null"]},"type":["array","null"]},"historical_serp_mode":{"description":"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","type":["string","null"]},"ignore_synonyms":{"description":"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","type":["boolean","null"]},"include_clickstream_data":{"description":"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","type":["boolean","null"]},"item_types":{"description":"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\"]","items":{"type":"string"},"type":["array","null"]},"language_code":{"description":"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","type":["string","null"]},"language_name":{"description":"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","type":["string","null"]},"limit":{"description":"the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000","type":["integer","null"]},"load_rank_absolute":{"description":"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","type":["boolean","null"]},"location_code":{"description":"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","type":["integer","null"]},"location_name":{"description":"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","type":["string","null"]},"offset":{"description":"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","type":["integer","null"]},"order_by":{"description":"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\"]","items":{"type":"string"},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"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","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Ranked keywords","catalog":"google.domain.ranked_keywords"},{"name":"serp_ai_summary","description":"‌‌\nThe purpose of the Live SERP API AI Summary endpoint is to provide a summary of the content found on any SERP and generate a response based on the user’s specified prompt.\nTo obtain results, you have to specify task_id, which you can find in the response to the POST request.\nLearn more in our Help Center.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"fetch_content":true,"include_links":true,"prompt":"explain what DataForSEO is","task_id":"07031739-1535-0139-0000-9d1e639a5b7d"}]],"items":{"oneOf":[{"examples":[[{"fetch_content":true,"include_links":true,"prompt":"explain what DataForSEO is","task_id":"07031739-1535-0139-0000-9d1e639a5b7d"}]],"properties":{"fetch_content":{"description":"fetch content from pages in SERPs
optional field
if set to true, the API will fetch the content from pages featured in SERP results, and the AI model will consider this content when generating the summary in the result;
default value: false","type":["boolean","null"]},"include_links":{"description":"include source links in the summary
optional field
if set to true, the summary field in the API response will contain links to sources of the generated summary;
default value: false","type":["boolean","null"]},"prompt":{"description":"AI prompt
optional field
additional task for AI summariser;
any form of text, question or information that communicates to AI what response you're looking for;
max number of symbols or characters you can specify: 2000;
note: your prompt has to be relevant to the keyword specified in the POST request to SERP API","type":["string","null"]},"support_extra":{"description":"support extra SERP features
optional field
if set to true, the AI model will consider the following extra SERP features, in addition to organic results: answer_box, knowledge_graph, featured_snippet;
default value: true","type":["boolean","null"]},"task_id":{"description":"task identifier
required field
unique identifier of the associated task in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp ai summary"},{"name":"serp_baidu_locations_country","description":"You will receive the list of locations by this API call. You can filter the list of locations by country when setting a task.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp baidu locations country"},{"name":"serp_baidu_organic_task_get_advanced_id","description":"Description of the fields for sending a request:","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp baidu organic task get advanced id"},{"name":"serp_baidu_organic_task_post","description":"Baidu SERP API provides top 10 search engine results. These results are specific to the selected location (see the List of Locations) and other settings.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"best iphone ever","location_code":2156,"priority":2,"tag":"some_string_123"}]],"items":{"oneOf":[{"examples":[[{"keyword":"best iphone ever","location_code":2156,"priority":2,"tag":"some_string_123"}]],"properties":{"depth":{"description":"parsing depth
optional field
number of results in SERP
default value: 10
max value: 700
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"device":{"description":"device type
optional field
return results for a specific device type
can take the values: desktop, mobile, tablet
default value: desktop","type":["string","null"]},"get_website_url":{"description":"include direct URL for each ranked result
optional field
if set to true, the returned results will contain direct URLs of the ranked websites
by default, the URLs in Baidu results are encoded by the search engine,
for example:
http://www.baidu.com/link?url=KQt6LSwU5OHnPtB8210R8flBP40grY6lTPxH_0UO7S2kgiZMTmw3ztV0hCo5c1kLdefault value: false
Note: if set to true, the charge per task will be multiplied by 10 as our system runs a separate request for each ranked website to return its direct URL","type":["boolean","null"]},"keyword":{"description":"keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesnote that the only language supported in Baidu search engine is Chinese (Simplified) with the zh_CN language code. However, Baidu may as well return results for queries in other languages, so specifying keyword in Chinese is not mandatory
example:
zh_CN","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesnote that the only language supported in Baidu search engine is Chinese (Simplified). However, Baidu may as well return results for queries in other languages, so specifying keyword in Chinese is not mandatory
example:
Chinese (Simplified)","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
2156","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)if you use this field, the returned results will be based on the closest city found for your coordinates. Thus, we don't recommend using this field as the results might not be relevant to the specified coordinates
example:
53.476225,-2.243572,200","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
New York,New York,United States","type":"string"},"max_crawl_pages":{"description":"page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center","type":["integer","null"]},"os":{"description":"device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android
if you specify tablet in the device field, choose from the following values: android, ios
default value: android","type":["string","null"]},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_data":{"description":"postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:
regular, html","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priority
You will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"stop_crawl_on_match":{"description":"array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets","items":{"oneOf":[{"properties":{"match_type":{"description":"target match type\nrequired field if stop_crawl_on_match is specified;\ntype of match for the match_value\npossible values: domain, with_subdomains, wildcard","type":["string","null"]},"match_value":{"description":"arget domain or wildcard value\nrequired field if stop_crawl_on_match is specified;\nspecify a target domain or wildcard value;\nNote: domain name must be specified without a request protocol;\nexample: dataforseo.com","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp baidu organic task post"},{"name":"serp_bing_locations_country","description":"You will receive the list of locations by this API call. You can filter the list of locations by country when setting a task.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp bing locations country"},{"name":"serp_bing_organic_live_advanced","description":"Live SERP provides real-time data on top 100 search engine results for the specified keyword, search engine, and location. This endpoint will supply a complete overview of featured snippets and other extra elements of SERPs.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"flight ticket new york san francisco","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"flight ticket new york san francisco","language_code":"en","location_code":2840}]],"properties":{"browser_screen_height":{"description":"
browser screen height
optional field
you can set a custom browser screen height to calculate pixel rankings for a particular device;
can be specified within the following range: 240-9999;
by default, the parameter is set to:
1080 for desktop;
640 for mobile on android;
812 for mobile on iOS;
Note: to use this parameter, set calculate_rectangles to true
","type":["integer","null"]},"browser_screen_resolution_ratio":{"description":"
browser screen resolution ratio
optional field
you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;
can be specified within the following range: 0.5-3;
by default, the parameter is set to:
1 for desktop;
3 for mobile on android;
3 for mobile on iOS;
Note: to use this parameter, set calculate_rectangles to true
","type":["integer","null"]},"browser_screen_width":{"description":"
browser screen width
optional field
you can set a custom browser screen width to calculate pixel rankings for a particular device;
can be specified within the following range: 240-9999;
by default, the parameter is set to:
1920 for desktop;
360 for mobile on android;
375 for mobile on iOS;
Note: to use this parameter, set calculate_rectangles to true
","format":"int64","type":["integer","null"]},"calculate_rectangles":{"description":"
calculate pixel rankings for SERP elements in advanced results
optional field
pixel ranking refers to the distance between the result snippet and top left corner of the screen;
Visit Help Center to learn more>>
by default, the parameter is set to false
Note: you will be charged extra $0.002 for using this parameter
","type":["boolean","null"]},"depth":{"description":"
parsing depth
optional field
number of results in SERP
default value: 10
max value: 200

Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"device":{"description":"
device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop
","type":["string","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”;

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
2840
","type":"integer"},"location_coordinate":{"description":"
GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
example:
53.476225,-2.243572
","type":"string"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
London,England,United Kingdom
","type":"string"},"match_type":{"description":"
target match type
required field if stop_crawl_on_match is specified
type of match for the match_value
possible values:
domain – specific domain or subdomain
with_subdomains – main domain and subdomains
wildcard – wildcard pattern
","type":"string"},"match_value":{"description":"
target domain, subdomain, or wildcard value
required field if stop_crawl_on_match is specified
specify a target domain, subdomain, or wildcard value;
Note: domain or subdomain must be specified without a request protocol;
example: \"match_value\": \"dataforseo.com\",
\"match_value\": \"/blog/post-*\"
","type":"string"},"max_crawl_pages":{"description":"
page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center
","type":["integer","null"]},"os":{"description":"
device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android
","type":["string","null"]},"search_param":{"description":"
additional parameters of the search query
optional field
get the list of available parameters and additional details here
","type":["string","null"]},"stop_crawl_on_match":{"description":"array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets","items":{"oneOf":[{"properties":{"match_type":{"description":"target match type\nrequired field if stop_crawl_on_match is specified;\ntype of match for the match_value\npossible values: domain, with_subdomains, wildcard","type":["string","null"]},"match_value":{"description":"arget domain or wildcard value\nrequired field if stop_crawl_on_match is specified;\nspecify a target domain or wildcard value;\nNote: domain name must be specified without a request protocol;\nexample: dataforseo.com","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"tag":{"description":"
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
","type":["string","null"]},"target":{"description":"
target domain, subdomain, or webpage to get results for
optional field
a domain or a subdomain should be specified without https:// and www.
note that the results of target-specific tasks will only include SERP elements that contain a url string;
you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results;
examples:
example.com - returns results for the website's home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;
example.com* - returns results for the domain, including all its pages;
*example.com* - returns results for the entire domain, including all its pages and subdomains;
*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com;
example.com/example-page - returns results for the exact URL;
example.com/example-page* - returns results for all domain's URLs that start with the specified string
","type":["string","null"]},"url":{"description":"
direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGE
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp bing organic live advanced","catalog":"bing.serp.organic"},{"name":"serp_bing_organic_live_regular","description":"Live SERP provides real-time data on search engine results for the specified keyword, search engine, and location.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"properties":{"depth":{"description":"
parsing depth
optional field
number of results in SERP
default value: 10
max value: 200

Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"device":{"description":"
device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop
","type":["string","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”;

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
2840
","type":"integer"},"location_coordinate":{"description":"
GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
example:
53.476225,-2.243572
","type":"string"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
London,England,United Kingdom
","type":"string"},"match_type":{"description":"
target match type
required field if stop_crawl_on_match is specified
type of match for the match_value
possible values:
domain – specific domain or subdomain
with_subdomains – main domain and subdomains
wildcard – wildcard pattern
","type":"string"},"match_value":{"description":"
target domain, subdomain, or wildcard value
required field if stop_crawl_on_match is specified
specify a target domain, subdomain, or wildcard value;
Note: domain or subdomain must be specified without a request protocol;
example: \"match_value\": \"dataforseo.com\",
\"match_value\": \"/blog/post-*\"
","type":"string"},"max_crawl_pages":{"description":"
page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center
","type":["integer","null"]},"os":{"description":"
device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android
","type":["string","null"]},"search_param":{"description":"
additional parameters of the search query
optional field
get the list of available parameters and additional details here
","type":["string","null"]},"stop_crawl_on_match":{"description":"array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets","items":{"oneOf":[{"properties":{"match_type":{"description":"target match type\nrequired field if stop_crawl_on_match is specified;\ntype of match for the match_value\npossible values: domain, with_subdomains, wildcard","type":["string","null"]},"match_value":{"description":"arget domain or wildcard value\nrequired field if stop_crawl_on_match is specified;\nspecify a target domain or wildcard value;\nNote: domain name must be specified without a request protocol;\nexample: dataforseo.com","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"tag":{"description":"
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
","type":["string","null"]},"target":{"description":"
target domain, subdomain, or webpage to get results for
optional field
a domain or a subdomain should be specified without https:// and www.
note that the results of target-specific tasks will only include SERP elements that contain a url string;
you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results;
examples:
example.com - returns results for the website's home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;
example.com* - returns results for the domain, including all its pages;
*example.com* - returns results for the entire domain, including all its pages and subdomains;
*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com;
example.com/example-page - returns results for the exact URL;
example.com/example-page* - returns results for all domain's URLs that start with the specified string
","type":["string","null"]},"url":{"description":"
direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGE
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp bing organic live regular","catalog":"bing.serp.organic"},{"name":"serp_google_ads_advertisers_task_get_advanced_id","description":"Description of the fields for sending a request:","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google ads advertisers task get advanced id"},{"name":"serp_google_ads_advertisers_task_post","description":"Google Ads Advertisers provides information on advertisers that run campaigns on Google Ads based on the Ads Transparency platform. ‌‌","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"apple","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"apple","location_code":2840}]],"properties":{"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"location_code":{"description":"
search engine location code
optional field
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/ads_advertisers/locations
example:
2840

Note: if you don't specify location_name, location_code, or location_coordinate, advertisers will be searched across all the available locations
","type":["integer","null"]},"location_coordinate":{"description":"
GPS coordinates of a location
optional field
if you use this field, you don't need to specify location_name or location_code
example:
52.6178549,-155.352142

Note: if you don't specify location_name, location_code, or location_coordinate, advertisers will be searched across all the available locations
","type":["string","null"]},"location_name":{"description":"
full name of search engine location
optional field
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/ads_advertisers/locations
example:
London,England,United Kingdom

Note: if you don't specify location_name, location_code, or location_coordinate, advertisers will be searched across all the available locations
","type":["string","null"]},"pingback_url":{"description":"
notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23

learn more on our Help Center
","type":["string","null"]},"postback_data":{"description":"
postback_url datatype
required field if you specify postback_url
corresponds to the function you used for setting a task
possible values:
advanced
","type":"string"},"postback_url":{"description":"
URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23

learn more on our Help Center
","type":["string","null"]},"priority":{"description":"
task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priority

You will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"
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
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google ads advertisers task post"},{"name":"serp_google_ads_search_task_get_advanced_id","description":"Description of the fields for sending a request:","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google ads search task get advanced id"},{"name":"serp_google_ads_search_task_post","description":"Google Ads Search provides information on ads that are run by advertisers on Google Ads. Information is based on the Ads Transparency platform and adapted for the convenience of DataForSEO users. ‌‌","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"advertiser_ids":["AR13752565271262920705","AR02439908557932462081"],"location_code":2840,"platform":"google_search"}]],"items":{"oneOf":[{"examples":[[{"advertiser_ids":["AR13752565271262920705","AR02439908557932462081"],"location_code":2840,"platform":"google_search"}]],"properties":{"advertiser_ids":{"description":"
advertiser identifiers
required field if target is not specified

you can specify the maximum of 25 values in this array;
advertiser_ids values for this parameter can be found in the Google Ads Advertisers endpoint;
","items":{"type":"string"},"type":"array"},"date_from":{"description":"
starting date of the time range
optional field
required field if date_to is specified;

date format: \"yyyy-mm-dd\"
minimum value: 2018-05-31
maximum value: today's date
example:
\"2020-01-01\"
","type":"string"},"date_to":{"description":"
ending date of the time range
optional field
required field if date_from is specified;

date format: \"yyyy-mm-dd\"
minimum value: 2018-05-31
maximum value: today's date
example:
\"2020-01-01\"
","type":"string"},"depth":{"description":"
parsing depth
optional field
number of results in SERP
default value: 40
max value: 700

Your account will be billed per each SERP containing up to 40 results;
Setting depth above 40 may result in additional charges if the search engine returns more than 40 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"format":{"description":"
ad format
optional field
possible values: all, text, image, video
","type":["string","null"]},"location_code":{"description":"
search engine location code
optional field
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/ads_search/locations
example:
2840

Note: if you don't specify location_name, location_code, or location_coordinate, the ads will be searched across all the available locations
","type":["integer","null"]},"location_coordinate":{"description":"
GPS coordinates of a location
optional field
if you use this field, you don't need to specify location_name or location_code
example:
52.6178549,-155.352142

Note: if you don't specify location_name, location_code, or location_coordinate, the ads will be searched across all the available locations
","type":["string","null"]},"location_name":{"description":"
full name of search engine location
optional field
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/ads_search/locations
example:
London,England,United Kingdom

Note: if you don't specify location_name, location_code, or location_coordinate, the ads will be searched across all the available locations
","type":["string","null"]},"pingback_url":{"description":"
notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23

learn more on our Help Center
","type":["string","null"]},"platform":{"description":"
advertising platform
optional field
possible values: all, google_play, google_maps, google_search, google_shopping, youtube
default value: all
","type":["string","null"]},"postback_data":{"description":"
postback_url datatype
required field if you specify postback_url
corresponds to the function you used for setting a task
possible values:
advanced
","type":"string"},"postback_url":{"description":"
URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23

learn more on our Help Center
","type":["string","null"]},"priority":{"description":"
task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priority

You will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"
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
","type":["string","null"]},"target":{"description":"
domain name
required field if advertiser_ids is not specified
domain name associated with an advertiser account
","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google ads search task post"},{"name":"serp_google_ai_mode_live_advanced","description":"‌‌\nGoogle AI Mode SERP API provides search results from the AI Mode feature of Google Search.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"what is google ai mode","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"what is google ai mode","language_code":"en","location_code":2840}]],"properties":{"browser_screen_height":{"description":"
browser screen height
optional field
you can set a custom browser screen height to calculate pixel rankings for a particular device;
can be specified within the following range: 240-9999;
by default, the parameter is set to:
1080 for desktop;
640 for mobile on android;
812 for mobile on iOS;
Note: to use this parameter, set calculate_rectangles to true
","type":["integer","null"]},"browser_screen_resolution_ratio":{"description":"
browser screen resolution ratio
optional field
you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;
can be specified within the following range: 0.5-3;
by default, the parameter is set to:
1 for desktop;
3 for mobile on android;
3 for mobile on iOS;
Note: to use this parameter, set calculate_rectangles to true
","type":["integer","null"]},"browser_screen_width":{"description":"
browser screen width
optional field
you can set a custom browser screen width to calculate pixel rankings for a particular device;
can be specified within the following range: 240-9999;
by default, the parameter is set to:
1920 for desktop;
360 for mobile on android;
375 for mobile on iOS;
Note: to use this parameter, set calculate_rectangles to true
","format":"int64","type":["integer","null"]},"calculate_rectangles":{"description":"
calculate pixel rankings for SERP elements in advanced results
optional field
pixel ranking refers to the distance between the result snippet and top left corner of the screen;
Visit Help Center to learn more>>
by default, the parameter is set to false
Note: if set to true, the charge per task will be multiplied by 2
","type":["boolean","null"]},"device":{"description":"
device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop
","type":["string","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name;
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/ai_mode/languages
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code;
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/ai_mode/languages
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations
Note: check Google Search Help for the list of countries where AI Mode is currently available
","type":"integer"},"location_coordinate":{"description":"
GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,zoom\" format
if \"zoom\" is not specified, 9z will be applied as a default value
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"zoom\": 4z
the maximum value for \"zoom\": 18z
example:
52.6178549,-155.352142,18z
","type":"string"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations
Note: check Google Search Help for the list of countries where AI Mode is currently available
","type":"string"},"os":{"description":"
device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android
","type":["string","null"]},"tag":{"description":"
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
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google ai mode live advanced"},{"name":"serp_google_autocomplete_live_advanced","description":"‌‌\nGoogle Autocomplete is a feature within Google Search that improves the search experience by allowing users to complete searches they started to type. DataForSEO SERP API will provide you with all the suggestions Google Autocomplete offers for a particular keyword, the position of the cursor pointer, and the search client.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"client":"gws-wiz-serp","keyword":"albert einstein","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"client":"gws-wiz-serp","keyword":"albert einstein","language_code":"en","location_code":2840}]],"properties":{"client":{"description":"
search client for autocomplete
optional field
autocomplete results may differ depending on the search client;
possible values:
chrome — used when google search is opened in google chrome;
chrome-omni — used in the address bar in chrome;
gws-wiz — used in google search home page;
gws-wiz-serp — used in google search engine results page;
safari — used when google search is opened in safari browser;
firefox — used when google search is opened in firefox browser;
psy-ab — may be used when google search is opened in google chrome browser;
toolbar — returns XML;
youtube — returns JSONP;
gws-wiz-local — used in google local;
img — used in google's image search;
products-cc — used in google shopping search
","type":["string","null"]},"cursor_pointer":{"description":"
search bar cursor pointer
optional field
the horizontal numerical position of the cursor pointer within the keyword in the search bar;
by modifying the position of the cursor pointer, you will obtain different autocomplete suggestions for the same seed keyword;
minimal value: 0
default value: the number of the last character of the specified keyword
example:
|which query are s - \"cursor_pointer\": 0
which query is s| - \"cursor_pointer\": 16
which que|ry is s - \"cursor_pointer\": 9
","type":["integer","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”;

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/serp/google/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations
example:
2840
","type":"integer"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code;
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/serp/google/autocomplete/locations
example:
London,England,United Kingdom
","type":"string"},"tag":{"description":"
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
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google autocomplete live advanced"},{"name":"serp_google_dataset_info_live_advanced","description":"‌\nLive Google Dataset Info provides real-time data on the dataset you specify in the request. You will get data from a page of the dataset displayed separately from the SERP. It contains information about dataset content, authors, licenses, and description on the SERP.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"dataset_id":"L2cvMTFqbl85ZHN6MQ=="}]],"items":{"oneOf":[{"examples":[[{"dataset_id":"L2cvMTFqbl85ZHN6MQ=="}]],"properties":{"dataset_id":{"description":"
ID of the dataset
required field
you can find dataset ID in the dataset URL or dataset item of Google Dataset Search result
example:
L2cvMTFqbl85ZHN6MQ==
","type":"string"},"device":{"description":"
device type
optional field
return results for a specific device type
possible value: desktop
","type":["string","null"]},"language_code":{"description":"
search engine language code
optional field
if you use this field, you don't need to specify language_name
possible value:
en
","type":["string","null"]},"language_name":{"description":"
full name of search engine language
optional field
if you use this field, you don't need to specify language_code
possible value:
English
","type":["string","null"]},"os":{"description":"
device operating system
optional field
possible values: windows, macos
default value: windows
","type":["string","null"]},"tag":{"description":"
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
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google dataset info live advanced"},{"name":"serp_google_dataset_search_live_advanced","description":"‌\nLive Google Dataset Search provides real-time data on the top 20 Google Dataset search engine results. These results are specific to the indicated keyword. You can specify other parameters optionally.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"file_formats":["archive","image"],"is_free":true,"keyword":"water quality","last_updated":"1m","topics":["natural_sciences","geo"],"usage_rights":"noncommercial"}]],"items":{"oneOf":[{"examples":[[{"file_formats":["archive","image"],"is_free":true,"keyword":"water quality","last_updated":"1m","topics":["natural_sciences","geo"],"usage_rights":"noncommercial"}]],"properties":{"depth":{"description":"
parsing depth
optional field
number of results in SERP
default value: 20
max value: 200

Your account will be billed per each SERP containing up to 20 results;
Setting depth above 20 may result in additional charges if the search engine returns more than 20 results;
If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically.","type":["integer","null"]},"device":{"description":"
device type
optional field
return results for a specific device type
possible value: desktop
","type":["string","null"]},"file_formats":{"description":"
file formats of the dataset
optional field
possible values: other, archive, text, image, document, tabular
","items":{"type":"string"},"type":["array","null"]},"is_free":{"description":"
indicates whether displayed datasets are free
optional field
possible values: true, false
","type":["boolean","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”;

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
optional field if you don't specify language_name
if you use this field, you don't need to specify language_name
possible value:
en
","type":["string","null"]},"language_name":{"description":"
full name of search engine language
optional field
if you use this field, you don't need to specify language_code
possible value:
English
","type":["string","null"]},"last_updated":{"description":"
last time the dataset was updated
optional field
possible values: 1m, 1y, 3y
","type":["string","null"]},"os":{"description":"
device operating system
optional field
choose from the following values: windows, macos
default value: windows
","type":["string","null"]},"tag":{"description":"
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
","type":["string","null"]},"topics":{"description":"
dataset topics
optional field
possible values: humanities, social_sciences, life_sciences, agriculture, natural_sciences, geo, computer, architecture_and_urban_planning, engineering
","items":{"type":"string"},"type":["array","null"]},"usage_rights":{"description":"
usage rights of the dataset
optional field
possible values: commercial, noncommercial
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google dataset search live advanced"},{"name":"serp_google_finance_explore_live_advanced","description":"‌\nLive Google Finance Explore provides real-time data from the ‘Explore’ tab of Google Finance. These results are specific to the parameters you specify in the request: location and language.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"language_name":"English","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"language_name":"English","location_code":2840}]],"properties":{"device":{"description":"
device type
optional field
return results for a specific device type
possible value: desktop
","type":["string","null"]},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations
example:
2840
","type":"integer"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locations
example:
London,England,United Kingdom
","type":"string"},"news_type":{"description":"
financial news filters
optional field
possible values: top_stories, local_market, world_markets
default value: top_stories
Note: if you specify local_market or world_markets, the charge per task will be multiplied by 2
","type":["string","null"]},"os":{"description":"
device operating system
optional field
possible values: windows
","type":["string","null"]},"tag":{"description":"
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
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google finance explore live advanced"},{"name":"serp_google_finance_markets_live_advanced","description":"‌\nLive Google Finance Markets provides real-time data from the ‘Markets’ tab of Google Finance. These results are specific to the parameters you specify in the request: location, language, and market_type.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"language_name":"English","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"language_name":"English","location_code":2840}]],"properties":{"device":{"description":"
device type
optional field
return results for a specific device type
possible value: desktop
","type":["string","null"]},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations
example:
2840
","type":"integer"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locations
example:
London,England,United Kingdom
","type":"string"},"market_type":{"description":"
type of google finance market
optional field
possible values: most-active, indexes, indexes/americas, indexes/europe-middle-east-africa, indexes/asia-pacific, gainers, losers, climate-leaders, cryptocurrencies, currencies
default value: most-active
","type":["string","null"]},"os":{"description":"
device operating system
optional field
possible values: windows
","type":["string","null"]},"tag":{"description":"
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
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google finance markets live advanced"},{"name":"serp_google_finance_quote_live_advanced","description":"‌\nLive Google Finance Quote provides real-time data from the ‘Quote’ tab of Google Finance. These results are specific to the parameters you specify in the request: ticker in the keyword field, location and language.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"CLW00:NYMEX","language_name":"English","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"CLW00:NYMEX","language_name":"English","location_code":2840}]],"properties":{"device":{"description":"
device type
optional field
return results for a specific device type
possible value: desktop
","type":["string","null"]},"keyword":{"description":"
ticker or stock symbol
required field
in this field you can pass the ticker symbol of publicly traded shares of a particular stock or security on a particular stock exchange;
you can specify up to 700 characters in the keyword field;
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”;

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations
example:
2840
","type":"integer"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locations
example:
London,England,United Kingdom
","type":"string"},"os":{"description":"
device operating system
optional field
possible values: windows
","type":["string","null"]},"tag":{"description":"
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
","type":["string","null"]},"window":{"description":"
time window for google_finance_quote graph
optional field
possible values: 1D, 5D, 1M, 6M, YTD, 1Y, 5Y, MAX
default value: 1D
Note: if you specify a value that is different from 1D, the charge per task will be multiplied by 2
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google finance quote live advanced"},{"name":"serp_google_finance_ticker_search_live_advanced","description":"‌\nLive Google Finance Ticker Search allows you to search for financial instruments available on Google Finance along with additional information. The result is specific to the parameters you specify in the request: keyword (name of a company or financial instrument) in the keyword field, location and language.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"category":"all","keyword":"DJ","language_name":"English","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"category":"all","keyword":"DJ","language_name":"English","location_code":2840}]],"properties":{"category":{"description":"
category of financial instruments to search for
optional field
possible values: all, stock, index, mutual_fund, currency, futures
default value: all
","type":["string","null"]},"keyword":{"description":"
company or financial instrument name
required field
in this field, you can enter the name of a company or financial instrument to search for relevant tickers;
you can specify up to 700 characters in the keyword field;
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”;

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations
example:
2840
","type":"integer"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locations
example:
London,England,United Kingdom
","type":"string"},"tag":{"description":"
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
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google finance ticker search live advanced"},{"name":"serp_google_images_live_advanced","description":"‌\nLive Google Images SERP provides real-time data on top 100 images results for the specified keyword, search engine, and location.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"properties":{"depth":{"description":"
parsing depth
optional field
number of results in SERP
default value: 100
max value: 200

Your account will be billed per each SERP containing up to 100 results;
Setting depth above 100 may result in additional charges if the search engine returns more than 100 results;
If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”;
if this field contains such parameters as 'allinanchor:', 'allintext:', 'allintitle:', 'allinurl:', 'define:', 'filetype:', 'id:', 'inanchor:', 'info:', 'intext:', 'intitle:', 'inurl:', 'link:', 'related:', 'site:', the charge per task will be multiplied by 5
Note: queries containing the ‘cache:’ parameter are not supported and will return a validation error

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations
example:
2840
","type":"integer"},"location_coordinate":{"description":"
GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:
53.476225,-2.243572,200
","type":"string"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations
example:
London,England,United Kingdom
","type":"string"},"max_crawl_pages":{"description":"
page crawl limit
optional field
number of search results pages to crawl
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center
","type":["integer","null"]},"os":{"description":"
device operating system
optional field
note that this API provides results for desktop only
choose from the following values: windows, macos
default value: windows
","type":["string","null"]},"se_domain":{"description":"
search engine domain
optional field
We choose the relevant search engine domain automatically according to the location and language you specify. However, you can set a custom search engine domain in this field
example:
google.co.uk, google.com.au, google.de, etc.
","type":["string","null"]},"search_param":{"description":"
additional parameters of the search query
optional field
Get the list of available parameters and additional details here.
","type":["string","null"]},"tag":{"description":"
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
","type":["string","null"]},"url":{"description":"
direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google images live advanced","catalog":"google.serp.images"},{"name":"serp_google_jobs_task_get_advanced_id","description":"Description of the fields for sending a request:","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google jobs task get advanced id"},{"name":"serp_google_jobs_task_post","description":"‌‌\nThis endpoint will provide you with SERP data from the Google Jobs search engine. The returned results are specific to the keyword as well as the language and location parameters of the POST request.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":".net developer","language_code":"en","location_code":2840},{"keyword":".net developer","language_name":"English","location_name":"United States","pingback_url":"https://your-server.com/pingscript?id=$id&tag=$tag","tag":"some_string_123"}]],"items":{"oneOf":[{"examples":[[{"keyword":".net developer","language_code":"en","location_code":2840},{"keyword":".net developer","language_name":"English","location_name":"United States","pingback_url":"https://your-server.com/pingscript?id=$id&tag=$tag","tag":"some_string_123"}]],"properties":{"depth":{"description":"
parsing depth
optional field
number of results in SERP;
default value: 10
max value: 200

Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"employment_type":{"description":"
employment contract type
optional field
type of employment contract for which the search results will be returned;
possible values:
fulltime, partime, contractor, intern
","items":{"type":"string"},"type":["array","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”;
Note: the keyword you specify must indicate the job title;
example: .net developer

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/serp/google/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/jobs/locations
example:
2840
","type":"integer"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code;
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/serp/google/jobs/locations
example:
London,England,United Kingdom
","type":"string"},"location_radius":{"description":"
location search radius
optional field
location search radius in kilometers;
Note: for countries that use the imperial system of units, you will need to convert miles to kilometers by multiplying the value in miles by 1.609;
if value is not specified, search is executed anywhere within the specified location;
maximal value: 300
minimal value: > 0
","type":["string","null"]},"pingback_url":{"description":"
notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23

learn more on our Help Center
","type":["string","null"]},"postback_data":{"description":"
postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:
regular, advanced, html
","type":"string"},"postback_url":{"description":"
URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23

learn more on our Help Center
","type":["string","null"]},"priority":{"description":"
task priority
optional field
can take the following values:
1 – normal execution priority (set by default);
2 – high execution priority

You will be additionally charged for the tasks with high execution priority;
The cost can be calculated on the Pricing page","type":["integer","null"]},"tag":{"description":"
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
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google jobs task post"},{"name":"serp_google_local_finder_live_advanced","description":"‌‌\nLive Google Local_finder SERP provides real-time search engine results for the specified keyword and location.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"local nail services","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"local nail services","language_code":"en","location_code":2840}]],"properties":{"depth":{"description":"
parsing depth
optional field
number of results in SERP
default value: 10
max value: 100

Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results respectively;
If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically
The cost can be calculated on the Pricing page.","type":["integer","null"]},"device":{"description":"
device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop
","type":["string","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
2840
","type":"integer"},"location_coordinate":{"description":"
GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,zoom\" format
if \"zoom\" is not specified, 9z will be applied as a default value
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"zoom\": 4z
the maximum value for \"zoom\": 18z
example:
52.6178549,-155.352142,20z
","type":"string"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
London,England,United Kingdom
","type":"string"},"os":{"description":"
device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android
","type":["string","null"]},"priority":{"description":"
task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priority

You will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"tag":{"description":"
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
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google local finder live advanced"},{"name":"serp_google_locations_country","description":"You will receive the list of locations by this API call. You can filter the list of locations by country when setting a task.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google locations country"},{"name":"serp_google_maps_live_advanced","description":"‌‌\nLive Google Maps SERP provides real-time data on top 100 search engine results for the specified keyword, search engine, and location.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"properties":{"depth":{"description":"
parsing depth
optional field
number of results in SERP
default value: 100
max value: 700

Your account will be billed per each SERP containing up to 100 results;
Setting depth above 100 may result in additional charges if the search engine returns more than 100 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"device":{"description":"
device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop","type":["string","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”;
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations
example:
2840
","type":"integer"},"location_coordinate":{"description":"
GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,zoom\" format
if \"zoom\" is not specified, 17z will be applied as a default value
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"zoom\": 3z
the maximum value for \"zoom\": 21z
example:
52.6178549,-155.352142,20z
","type":"string"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations
example:
London,England,United Kingdom
","type":"string"},"max_crawl_pages":{"description":"
page crawl limit
optional field
number of search results pages to crawl
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center
","type":["integer","null"]},"os":{"description":"
device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android
","type":["string","null"]},"se_domain":{"description":"
search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
google.co.uk, google.com.au, google.de, etc.
","type":["string","null"]},"search_places":{"description":"
search places mode
optional field
the search places mode allows to obtain Google Maps results on a certain place (e.g., Apple Store in New York)
however, due to the pecularities of our data mining algorithm, this mode might interfere with some local-intent queries - and display results for a location that is different from that specified in the request;
to prevent this interference and obtain correct results for keywords with local intent you may set this parameter to false;

default value: true
Note: if the search_places mode is turned off and no results were found in the search area, the results array will be empty
","type":["boolean","null"]},"search_this_area":{"description":"
show results from the displayed area
optional field
can take the values:true, false
default value: true

if set to false, the search_this_area mode will be turned off

Note: if the search_this_area mode is turned off, Google Maps listings might contain results beyond the displayed area
","type":["boolean","null"]},"tag":{"description":"
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
","type":["string","null"]},"url":{"description":"
direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://google.com/maps/search/pizza/@37.09024,-95.712891,4z

Note: the following search engine parameters are not supported and will be automatically unset if specified in the URL: allinanchor:, allintext:, allintitle:, allinurl:, cache:, define:, definition:, filetype:, id:, inanchor:, info:, intext:, intitle:, inurl:, link:, site:.","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google maps live advanced","catalog":"google.serp.maps"},{"name":"serp_google_news_live_advanced","description":"‌‌\nLive Google News SERP provides real-time data on top search engine results for the specified keyword, search engine, and location.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"android","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"android","language_code":"en","location_code":2840}]],"properties":{"browser_screen_height":{"description":"
browser screen height
optional field
you can set a custom browser screen height to calculate pixel rankings for a particular device;
by default, the parameter is set to 1080;
Note: to use this parameter, set calculate_rectangles to true
","type":["integer","null"]},"browser_screen_resolution_ratio":{"description":"
browser screen resolution ratio
optional field
you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;
by default, the parameter is set to 1;
Note: to use this parameter, set calculate_rectangles to true
","type":["integer","null"]},"browser_screen_width":{"description":"
browser screen width
optional field
you can set a custom browser screen width to calculate pixel rankings for a particular device;
by default, the parameter is set to 1920;
Note: to use this parameter, set calculate_rectangles to true
","format":"int64","type":["integer","null"]},"calculate_rectangles":{"description":"
calculate pixel rankings for SERP elements in advanced results
optional field
pixel ranking refers to the distance between the result snippet and top left corner of the screen;
Visit Help Center to learn more>>
by default, the parameter is set to false
Note: if set to true, the charge per task will be multiplied by 2
","type":["boolean","null"]},"depth":{"description":"
parsing depth
optional field
number of results in SERP
default value: 10
max value: 200

Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically
The cost can be calculated on the Pricing page.","type":["integer","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”;
if this field contains such parameters as 'allinanchor:', 'allintext:', 'allintitle:', 'allinurl:', 'define:', 'filetype:', 'id:', 'inanchor:', 'info:', 'intext:', 'intitle:', 'inurl:', 'link:', 'related:', 'site:', the charge per task will be multiplied by 5
Note: queries containing the ‘cache:’ parameter are not supported and will return a validation error

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
2840
","type":"integer"},"location_coordinate":{"description":"
GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:
53.476225,-2.243572,200
","type":"string"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
London,England,United Kingdom
","type":"string"},"max_crawl_pages":{"description":"
page crawl limit
optional field
number of search results pages to crawl
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center
","type":["integer","null"]},"os":{"description":"
device operating system
optional field
note that this API provides results for desktop only
choose from the following values: windows, macos
default value: windows
","type":["string","null"]},"se_domain":{"description":"
search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
google.co.uk, google.com.au, google.de, etc.
","type":["string","null"]},"search_param":{"description":"
additional parameters of the search query
optional field
Get the list of available parameters and additional details here.
","type":["string","null"]},"url":{"description":"
direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google news live advanced","catalog":"google.serp.news"},{"name":"serp_google_organic_live_advanced","description":"‌\nLive SERP provides real-time data on top search engine results for the specified keyword, search engine, and location. This endpoint will supply a complete overview of featured snippets and other extra elements of SERPs.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"calculate_rectangles":true,"keyword":"albert einstein","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"calculate_rectangles":true,"keyword":"albert einstein","language_code":"en","location_code":2840}]],"properties":{"browser_screen_height":{"description":"
browser screen height
optional field
you can set a custom browser screen height to calculate pixel rankings for a particular device;
can be specified within the following range: 240-9999;
by default, the parameter is set to:
1080 for desktop;
640 for mobile on android;
812 for mobile on iOS;
Note: to use this parameter, set calculate_rectangles to true
","type":["integer","null"]},"browser_screen_resolution_ratio":{"description":"
browser screen resolution ratio
optional field
you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;
can be specified within the following range: 0.5-3;
by default, the parameter is set to:
1 for desktop;
3 for mobile on android;
3 for mobile on iOS;
Note: to use this parameter, set calculate_rectangles to true
","type":["integer","null"]},"browser_screen_width":{"description":"
browser screen width
optional field
you can set a custom browser screen width to calculate pixel rankings for a particular device;
can be specified within the following range: 240-9999;
by default, the parameter is set to:
1920 for desktop;
360 for mobile on android;
375 for mobile on iOS;
Note: to use this parameter, set calculate_rectangles to true
","format":"int64","type":["integer","null"]},"calculate_rectangles":{"description":"
calcualte pixel rankings for SERP elements in advanced results
optional field
pixel ranking refers to the distance between the result snippet and top left corner of the screen;
Visit Help Center to learn more>>
by default, the parameter is set to false;
Note: you will be charged extra $0.002 for using this parameter
","type":["boolean","null"]},"depth":{"description":"
parsing depth
optional field
number of results in SERP
default value: 10
max value: 200

Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"device":{"description":"
device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop
","type":["string","null"]},"find_targets_in":{"description":"
SERP element types to check for targets
optional field
to enable this parameter, stop_crawl_on_match must also be enabled
specifies which SERP element types should be checked for target matches
if not specified, all first-level elements with url and domain fields are checked for targets
possible values: organic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitter
Note: cannot contain the same element types as ignore_targets_in
example:
\"find_targets_in\": [\"organic\", \"featured_snippet\"]
learn more about this parameter on our Help Center
","items":{"type":"string"},"type":["array","null"]},"group_organic_results":{"description":"
display related results
optional field
if set to true, the related_result element in the response will be provided as a snippet of its parent organic result;
if set to false, the related_result element will be provided as a separate organic result;
default value: true
","type":["boolean","null"]},"ignore_targets_in":{"description":"
SERP element types to exclude from target search
optional field
to enable this parameter, stop_crawl_on_match must also be enabled
specifies which SERP element types should be excluded when searching for target matches
possible values: organic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitter
Note: cannot contain the same element types as find_targets_in
example:
\"ignore_targets_in\": [\"paid\", \"images\"]
learn more about this parameter on our Help Center
","items":{"type":"string"},"type":["array","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”;
if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘cache:’, ‘define:’, ‘definition:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘site:’, the charge per task will be multiplied by 5
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
optional field if you specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
en
","type":["string","null"]},"language_name":{"description":"
full name of search engine language
optional field if you specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languages
example:
English
","type":["string","null"]},"load_async_ai_overview":{"description":"
load asynchronous ai overview
optional field
set to true to obtain ai_overview items is SERPs even if they are loaded asynchronously;
if set to false, you will only obtain ai_overview items from cache;
default value: false
Note: you will be charged extra $0.002 for using this parameter;
if the element is absent or contains \"asynchronous_ai_overview\": false, all extra charges will be returned to your account balance
","type":["boolean","null"]},"location_code":{"description":"
search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations
example:
2840
","type":"integer"},"location_coordinate":{"description":"
GPS coordinates of a location
optional field if you specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199 (mm)
the maximum value for \"radius\": 199999 (mm)
example:
53.476225,-2.243572,200
","type":["string","null"]},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations
example:
London,England,United Kingdom
","type":"string"},"match_type":{"description":"
target match type
required field if stop_crawl_on_match is specified
type of match for the match_value
possible values:
domain – specific domain or subdomain
with_subdomains – main domain and subdomains
wildcard – wildcard pattern
","type":"string"},"match_value":{"description":"
target domain, subdomain, or wildcard value
required field if stop_crawl_on_match is specified
specify a target domain, subdomain, or wildcard value;
Note: domain or subdomain must be specified without a request protocol;
example: \"match_value\": \"dataforseo.com\",
\"match_value\": \"/blog/post-*\"
","type":"string"},"max_crawl_pages":{"description":"
page crawl limit
optional field
number of search results pages to crawl
max value: 100
Note: you will be charged for each page crawled (10 organic results per page);
learn more about pricing on our Pricing page;
Note#2: the max_crawl_pages and depth parameters complement each other;
learn more at our help center
","type":["integer","null"]},"os":{"description":"
device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android
","type":["string","null"]},"people_also_ask_click_depth":{"description":"
clicks on the corresponding element
optional field
specify the click depth on the people_also_ask element to get additional people_also_ask_element items;
Note your account will be billed $0.00015 extra for each click;
if the element is absent or we perform fewer clicks than you specified, all extra charges will be returned to your account balance
possible values: from 1 to 4
","type":["integer","null"]},"remove_from_url":{"description":"
remove specific parameters from URLs
optional field
using this field, you can specify up to 10 parameters to remove from URLs in the result
example:
\"remove_from_url\": [\"srsltid\"]
Note: if the target field is specified, the specified URL parameters will be removed before the search
","items":{"type":"string"},"type":["array","null"]},"se_domain":{"description":"
search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
google.co.uk, google.com.au, google.de, etc.
","type":["string","null"]},"search_param":{"description":"
additional parameters of the search query
optional field
get the list of available parameters and additional details here

Note: the following search engine parameters are not supported and will be automatically unset if specified: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype.","type":["string","null"]},"stop_crawl_on_match":{"description":"array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets","items":{"oneOf":[{"properties":{"match_type":{"description":"target match type\nrequired field if stop_crawl_on_match is specified;\ntype of match for the match_value\npossible values: domain, with_subdomains, wildcard","type":["string","null"]},"match_value":{"description":"arget domain or wildcard value\nrequired field if stop_crawl_on_match is specified;\nspecify a target domain or wildcard value;\nNote: domain name must be specified without a request protocol;\nexample: dataforseo.com","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"tag":{"description":"
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
","type":["string","null"]},"target":{"description":"
target domain, subdomain, or webpage to get results for
optional field
a domain or a subdomain should be specified without https:// and www.
note that the results of target-specific tasks will only include SERP elements that contain a url string;
you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results;
examples:
example.com - returns results for the website's home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;
example.com* - returns results for the domain, including all its pages;
*example.com* - returns results for the entire domain, including all its pages and subdomains;
*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com;
example.com/example-page - returns results for the exact URL;
example.com/example-page* - returns results for all domain's URLs that start with the specified string
","type":["string","null"]},"target_search_mode":{"description":"
target matching mode
optional field
to enable this parameter, stop_crawl_on_match must also be enabled
defines how the crawl should stop when multiple targets are specified in stop_crawl_on_match
possible values: all, any
all – the crawl stops only when all specified targets are found
any – the crawl stops when any single target is found
default value: any
learn more about this parameter on our Help Center
","type":["string","null"]},"url":{"description":"
direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS

Note: the following search engine parameters are not supported and will be automatically unset if specified in the URL: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype.","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google organic live advanced","catalog":"google.serp.organic"},{"name":"serp_google_search_by_image_task_get_advanced_id","description":"Description of the fields for sending a request:","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google search by image task get advanced id"},{"name":"serp_google_search_by_image_task_post","description":"‌‌\nGoogle Search By Image SERP API provides up to top 100 search engine results based on the image you specified. These results are specific to the selected location (see the List of Locations) and language (see the List of Languages) settings.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"image_url":"https://dataforseo.com/wp-content/uploads/2016/11/data_for_seo_light_429.png","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"image_url":"https://dataforseo.com/wp-content/uploads/2016/11/data_for_seo_light_429.png","language_code":"en","location_code":2840}]],"properties":{"browser_screen_height":{"description":"
browser screen height
optional field
you can set a custom browser screen height to calculate pixel rankings for a particular device;
by default, the parameter is set to 1080;
Note: to use this parameter, set calculate_rectangles to true
","type":["integer","null"]},"browser_screen_resolution_ratio":{"description":"
browser screen resolution ratio
optional field
you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;
by default, the parameter is set to 1;
Note: to use this parameter, set calculate_rectangles to true
","type":["integer","null"]},"browser_screen_width":{"description":"
browser screen width
optional field
you can set a custom browser screen width to calculate pixel rankings for a particular device;
by default, the parameter is set to 1920;
Note: to use this parameter, set calculate_rectangles to true
","format":"int64","type":["integer","null"]},"calculate_rectangles":{"description":"
calculate pixel rankings for SERP elements in advanced results
optional field
pixel ranking refers to the distance between the result snippet and top left corner of the screen;
Visit Help Center to learn more>>
by default, the parameter is set to false
Note: if set to true, the charge per task will be multiplied by 2
","type":["boolean","null"]},"image_url":{"description":"
URL of the image
required field
the results will be based on the image you specified in this field
example:
https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
2840
","type":"integer"},"location_coordinate":{"description":"
GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:
53.476225,-2.243572,200
","type":"string"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
London,England,United Kingdom
","type":"string"},"max_crawl_pages":{"description":"
page crawl limit
optional field
number of search results pages to crawl
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center
","type":["integer","null"]},"pingback_url":{"description":"
notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23

learn more on our Help Center
","type":["string","null"]},"postback_data":{"description":"
postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:
advanced, html
","type":"string"},"postback_url":{"description":"
URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23

learn more on our Help Center
","type":["string","null"]},"priority":{"description":"
task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priority

You will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"se_domain":{"description":"
search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
google.co.uk, google.com.au, google.de, etc.
","type":["string","null"]},"search_param":{"description":"
additional parameters of the search query
optional field
get the list of available parameters and additional details here
","type":["string","null"]},"tag":{"description":"
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
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp google search by image task post"},{"name":"serp_naver_organic_task_get_advanced_id","description":"Description of the fields for sending a request:","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp naver organic task get advanced id"},{"name":"serp_naver_organic_task_post","description":"‌‌\nNaver SERP API provides top 15 search engine results. Naver search results do not vary by location and language, and the search parameters for this search engine do not contain language and location variables. However, you can specify a keyword in any language, and the search engine results may vary depending on the language you used for specifying the search query.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"device":"desktop","keyword":"albert einstein","postback_data":"regular","postback_url":"https://your-server.com/postbackscript.php","tag":"some_string_123"}]],"items":{"oneOf":[{"examples":[[{"device":"desktop","keyword":"albert einstein","postback_data":"regular","postback_url":"https://your-server.com/postbackscript.php","tag":"some_string_123"}]],"properties":{"depth":{"description":"parsing depth
optional field
number of results in SERP
default value: 15
max value: 700
Your account will be billed per each SERP containing up to 15 results;
Setting depth above 15 may result in additional charges if the search engine returns more than 15 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"device":{"description":"device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop","type":["string","null"]},"keyword":{"description":"keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"max_crawl_pages":{"description":"page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center","type":["integer","null"]},"os":{"description":"device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android","type":["string","null"]},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_data":{"description":"postback_url datatype
required field if you specify postback_url
corresponds to the function you used for setting a task
possible values:
regular, advanced, html","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"se_domain":{"description":"search engine domain
optional field
we choose the relevant search engine domain automatically
however, you can set a custom search engine domain in this field
example:
search.naver.com","type":["string","null"]},"search_param":{"description":"additional parameters of the search query
optional field
get the list of available parameters and additional details here","type":["string","null"]},"stop_crawl_on_match":{"description":"array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets","items":{"oneOf":[{"properties":{"match_type":{"description":"target match type\nrequired field if stop_crawl_on_match is specified;\ntype of match for the match_value\npossible values: domain, with_subdomains, wildcard","type":["string","null"]},"match_value":{"description":"arget domain or wildcard value\nrequired field if stop_crawl_on_match is specified;\nspecify a target domain or wildcard value;\nNote: domain name must be specified without a request protocol;\nexample: dataforseo.com","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"url":{"description":"direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields
in most cases, we wouldn’t recommend using this method;
example:
https://search.naver.com/search.naver?where=nexearch&sm=top_hty&fbm=1&ie=utf8&query=iphone","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp naver organic task post"},{"name":"serp_screenshot","description":"‌‌\nUsing the Live Page Screenshot endpoint, you can capture a screenshot of any SERP page.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"browser_screen_scale_factor":0.5,"task_id":"06211235-0696-0139-1000-36727fbd3c90"}]],"items":{"oneOf":[{"examples":[[{"browser_screen_scale_factor":0.5,"task_id":"06211235-0696-0139-1000-36727fbd3c90"}]],"properties":{"browser_preset":{"description":"browser resolution preset
optional field
browser preset associated with a certain device type
can take the following values: desktop, tablet, mobile
Note: by default, browser preset corresponds to the device type specified in the POST request","type":["string","null"]},"browser_screen_height":{"description":"height of the browser resolution
optional field
can be specified in the following range: 240-9999
default value for desktop: 1080
default value for mobile: 844
default value for table: 1366","type":["integer","null"]},"browser_screen_scale_factor":{"description":"browser scale factor
optional field
can be specified in the following range: 0.5-3
default value for desktop: 1
default value for mobile: 3
default value for table: 2","type":["number","null"]},"browser_screen_width":{"description":"width of the browser resolution
optional field
can be specified in the following range: 240-9999
default value for desktop: 1920
default value for mobile: 390
default value for table: 1024","format":"int64","type":["integer","null"]},"page":{"description":"number of SERP pages
optional field
if depth in the corresponding Task POST request exceeds 10 results (or 1 SERP page), specify the number of SERP pages to screenshot;
default value: 1","type":["integer","null"]},"task_id":{"description":"task identifier
required field
unique identifier of the associated task in the UUID format
you will be able to use it within 7 days to request the results of the task at any time","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp screenshot"},{"name":"serp_seznam_locations_country","description":"You will receive the list of locations by this API call. You can filter the list of locations by country when setting a task.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp seznam locations country"},{"name":"serp_seznam_organic_task_get_advanced_id","description":"Description of the fields for sending a request:","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"id":{"description":"task identifier
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time","type":"string"}},"required":["id"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp seznam organic task get advanced id"},{"name":"serp_seznam_organic_task_post","description":"‌‌\nSeznam SERP API provides top 10 search engine results from one of the most popular search engines in the Czech Republic. Seznam is focused on the local search market, and thus supports the Czech language only.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"albert einstein","language_code":"cs","location_code":2203}]],"items":{"oneOf":[{"examples":[[{"keyword":"albert einstein","language_code":"cs","location_code":2203}]],"properties":{"calculate_rectangles":{"description":"calculate pixel rankings for SERP elements in advanced results
optional field
pixel ranking refers to the distance between the result snippet and top left corner of the screen;
Visit Help Center to learn more>>
by default, the parameter is set to false
Note: if set to true, the charge per task will be multiplied by 2","type":["boolean","null"]},"depth":{"description":"parsing depth
optional field
number of results in SERP
default value: 10;
maximum value: 500;
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"device":{"description":"device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop","type":["string","null"]},"keyword":{"description":"keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
csn","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
Czech","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
2840","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
London,England,United Kingdom","type":"string"},"max_crawl_pages":{"description":"page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 10
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center","type":["integer","null"]},"os":{"description":"device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android","type":["string","null"]},"pingback_url":{"description":"notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/pingscript?id=$id
http://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"postback_data":{"description":"postback_url datatype
required field if you specify postback_url
corresponds to the function you used for setting a task
possible values:
regular, advanced, html","type":"string"},"postback_url":{"description":"URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
http://your-server.com/postbackscript?id=$id
http://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center","type":["string","null"]},"priority":{"description":"task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priority
You will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page.","type":["integer","null"]},"se_domain":{"description":"search engine domain
optional field
we choose the relevant search engine domain automatically
however, you can set a custom search engine domain in this field
example:
search.seznam.cz","type":["string","null"]},"search_param":{"description":"additional parameters of the search query
optional field","type":["string","null"]},"stop_crawl_on_match":{"description":"array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets","items":{"oneOf":[{"properties":{"match_type":{"description":"target match type\nrequired field if stop_crawl_on_match is specified;\ntype of match for the match_value\npossible values: domain, with_subdomains, wildcard","type":["string","null"]},"match_value":{"description":"arget domain or wildcard value\nrequired field if stop_crawl_on_match is specified;\nspecify a target domain or wildcard value;\nNote: domain name must be specified without a request protocol;\nexample: dataforseo.com","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"url":{"description":"direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields;
note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL;
in most cases, we wouldn’t recommend using this method.","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp seznam organic task post"},{"name":"serp_yahoo_locations_country","description":"You will receive the list of locations by this API call. You can filter the list of locations by country when setting a task.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp yahoo locations country"},{"name":"serp_yahoo_organic_live_advanced","description":"Live SERP provides real-time data on top search engine results. These results are specific to the selected location (see the List of Locations) and language (see the List of Languages) settings.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"properties":{"depth":{"description":"parsing depth
optional field
number of results in SERP
default value: 6
max value: 200
Your account will be billed per each SERP;
Each Yahoo SERP can contain fewer than 10 results, so setting depth above the default value may result in additional charges ;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"device":{"description":"device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop","type":["string","null"]},"keyword":{"description":"keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
enn","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
2840n","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:
53.476225,-2.243572,200n","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
London,England,United Kingdom","type":"string"},"max_crawl_pages":{"description":"page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center","type":["integer","null"]},"os":{"description":"device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android","type":["string","null"]},"se_domain":{"description":"search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
au.search.yahoo.com, uk.search.yahoo.com, ca.search.yahoo.com, etc.","type":["string","null"]},"search_param":{"description":"additional parameters of the search query
optional field
get the list of available parameters and additional details here","type":["string","null"]},"stop_crawl_on_match":{"description":"array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets","items":{"oneOf":[{"properties":{"match_type":{"description":"target match type\nrequired field if stop_crawl_on_match is specified;\ntype of match for the match_value\npossible values: domain, with_subdomains, wildcard","type":["string","null"]},"match_value":{"description":"arget domain or wildcard value\nrequired field if stop_crawl_on_match is specified;\nspecify a target domain or wildcard value;\nNote: domain name must be specified without a request protocol;\nexample: dataforseo.com","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"target domain, subdomain, or webpage to get results for
optional field
a domain or a subdomain should be specified without https:// and www.
note that the results of target-specific tasks will only include SERP elements that contain a url string;
you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results;
examples:
example.com - returns results for the website's home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;
example.com* - returns results for the domain, including all its pages;
*example.com* - returns results for the entire domain, including all its pages and subdomains;
*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com;
example.com/example-page - returns results for the exact URL;
example.com/example-page* - returns results for all domain's URLs that start with the specified string","type":["string","null"]},"url":{"description":"direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp yahoo organic live advanced","catalog":"yahoo.serp.organic"},{"name":"serp_yahoo_organic_live_regular","description":"Live Yahoo SERP provides real-time data on search engine results for the specified keyword, search engine, and location.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"albert einstein","language_code":"en","location_code":2840}]],"properties":{"depth":{"description":"parsing depth
optional field
number of results in SERP
default value: 6
max value: 200
Your account will be billed per each SERP;
Each Yahoo SERP can contain fewer than 10 results, so setting depth above the default value may result in additional charges ;
The cost can be calculated on the Pricing page.","type":["integer","null"]},"device":{"description":"device type
optional field
can take the values:desktop, mobile
default value: desktop","type":["string","null"]},"keyword":{"description":"keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”
learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article","type":"string"},"language_code":{"description":"search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
enn","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
2840n","type":"integer"},"location_coordinate":{"description":"GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_code
location_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:
53.476225,-2.243572,200n","type":"string"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:
London,England,United Kingdom","type":"string"},"max_crawl_pages":{"description":"page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center","type":["integer","null"]},"os":{"description":"device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android","type":["string","null"]},"se_domain":{"description":"search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:
au.search.yahoo.com, uk.search.yahoo.com, ca.search.yahoo.com, etc.","type":["string","null"]},"search_param":{"description":"additional parameters of the search query
optional field
get the list of available parameters and additional details here","type":["string","null"]},"stop_crawl_on_match":{"description":"array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets","items":{"oneOf":[{"properties":{"match_type":{"description":"target match type\nrequired field if stop_crawl_on_match is specified;\ntype of match for the match_value\npossible values: domain, with_subdomains, wildcard","type":["string","null"]},"match_value":{"description":"arget domain or wildcard value\nrequired field if stop_crawl_on_match is specified;\nspecify a target domain or wildcard value;\nNote: domain name must be specified without a request protocol;\nexample: dataforseo.com","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":["array","null"]},"tag":{"description":"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","type":["string","null"]},"target":{"description":"target domain, subdomain, or webpage to get results for
optional field
a domain or a subdomain should be specified without https:// and www.
note that the results of target-specific tasks will only include SERP elements that contain a url string;
you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results;
examples:
example.com - returns results for the website's home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;
example.com* - returns results for the domain, including all its pages;
*example.com* - returns results for the entire domain, including all its pages and subdomains;
*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com;
example.com/example-page - returns results for the exact URL;
example.com/example-page* - returns results for all domain's URLs that start with the specified string","type":["string","null"]},"url":{"description":"direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:
https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp yahoo organic live regular","catalog":"yahoo.serp.organic"},{"name":"serp_youtube_locations_country","description":"You will receive the list of locations by this API call. You can filter the list of locations by country when setting a task.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"path":{"additionalProperties":false,"properties":{"country":{"description":"country ISO code
optional field
specify the ISO code if you want to filter the list of locations by country
example:
us","type":"string"}},"required":["country"],"type":"object"}},"required":["path"],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp youtube locations country"},{"name":"serp_youtube_organic_live_advanced","description":"‌\nLive SERP provides real-time data on the top 20 blocks of YouTube search engine results. These results are specific to the selected location (see the List of Locations) and language (see the List of Languages) settings.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"keyword":"audi","language_code":"en","location_code":2840}]],"items":{"oneOf":[{"examples":[[{"keyword":"audi","language_code":"en","location_code":2840}]],"properties":{"block_depth":{"description":"
parsing depth
optional field
number of blocks of results in SERP
default value: 20
max value: 200
Note: your account will be billed per each SERP containing up to 20 results;
thus, setting a block depth above 20 may result in additional charges if the search engine returns more than 20 results;
if the specified block depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance
","type":["integer","null"]},"device":{"description":"
device type
optional field
return results for a specific device type
available values: desktop, mobile
","type":["string","null"]},"keyword":{"description":"
keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”;

learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
","type":"string"},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations
example:
2840
","type":"integer"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations
example:
United States
","type":"string"},"os":{"description":"
device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android
","type":["string","null"]},"search_param":{"description":"
additional parameters of the search query
optional field
example:
sp=EgIQAg%253D%253D
","type":["string","null"]},"tag":{"description":"
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
","type":["string","null"]}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp youtube organic live advanced","catalog":"youtube.serp.organic"},{"name":"serp_youtube_video_comments_live_advanced","description":"‌\nLive YouTube Comments provides real-time data on comments on the video you specify in the request. You will get the top 20 comments on the video as well as information about the author, and key comment metrics.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"language_code":"en","location_code":2840,"video_id":"vQXvyV0zIP4"}]],"items":{"oneOf":[{"examples":[[{"language_code":"en","location_code":2840,"video_id":"vQXvyV0zIP4"}]],"properties":{"depth":{"description":"parsing depth
optional field
number of results in SERP
default value: 20
max value: 200
Note: your account will be billed per each SERP containing up to 20 results;
thus, setting a depth above 20 may result in additional charges if the search engine returns more than 20 results;
if the specified depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance","type":["integer","null"]},"device":{"description":"device type
optional field
only value: desktop","type":["string","null"]},"language_code":{"description":"search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages
example:
enn","type":"string"},"language_name":{"description":"full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages
example:
English","type":"string"},"location_code":{"description":"search engine location code
required field if you don't specify location_name_
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations
example:
2840n","type":"integer"},"location_name":{"description":"full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations
example:
United States","type":"string"},"os":{"type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"video_id":{"description":"ID of the video
required field
you can find video ID in the URL or 'youtube_video' item of YouTube Organic result
example:
vQXvyV0zIP4","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp youtube video comments live advanced"},{"name":"serp_youtube_video_info_live_advanced","description":"‌\nLive YouTube Video Info provides real-time data on the video you specify in the request. You will get data from the watching page containing key video and content metrics as well as the channel where the video is published.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"language_code":"en","location_code":2840,"video_id":"vQXvyV0zIP4"}]],"items":{"oneOf":[{"examples":[[{"language_code":"en","location_code":2840,"video_id":"vQXvyV0zIP4"}]],"properties":{"device":{"description":"
device type
optional field
only value: desktop
","type":["string","null"]},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations
example:
2840
","type":"integer"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations
example:
United States
","type":"string"},"os":{"description":"
device operating system
optional field
choose from the following values: windows, macos
default value: windows
","type":["string","null"]},"tag":{"description":"
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
","type":["string","null"]},"video_id":{"description":"
ID of the video
required field
you can find video ID in the URL or 'youtube_video' item of YouTube Organic result
example:
vQXvyV0zIP4
","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp youtube video info live advanced"},{"name":"serp_youtube_video_subtitles_live_advanced","description":"‌\nLive YouTube Subtitles provides real-time data on subtitles in the video you specify in the request. You will get data from the watching page containing subtitled text, its language, and duration in the video.","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"language_code":"en","location_code":2840,"video_id":"Y8Wu4rSNJms"}]],"items":{"oneOf":[{"examples":[[{"language_code":"en","location_code":2840,"video_id":"Y8Wu4rSNJms"}]],"properties":{"device":{"description":"
device type
optional field
only value: desktop
","type":["string","null"]},"language_code":{"description":"
search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages
example:
en
","type":"string"},"language_name":{"description":"
full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages
example:
English
","type":"string"},"location_code":{"description":"
search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations
example:
2840
","type":"integer"},"location_name":{"description":"
full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations
example:
United States
","type":"string"},"os":{"description":"
device operating system
optional field
choose from the following values: windows, macos
default value: windows
","type":["string","null"]},"subtitles_language":{"description":"
language code of original text
you can get the language code from YouTube Video Info result
","type":["string","null"]},"subtitles_translate_language":{"description":"
language code of translated text
possible values:
\"az\", \"ay\", \"ak\", \"sq\", \"am\", \"en\", \"ar\", \"hy\", \"as\", \"af\", \"eu\", \"be\", \"bn\", \"my\", \"bg\", \"bs\", \"bho\", \"cy\", \"hu\", \"vi\", \"haw\", \"ht\", \"gl\", \"lg\", \"el\", \"ka\", \"gn\", \"gu\", \"gd\", \"da\", \"fy\", \"zu\", \"iw\", \"ig\", \"yi\", \"id\", \"ga\", \"is\", \"es\", \"it\", \"yo\", \"kk\", \"kn\", \"ca\", \"qu\", \"rw\", \"ky\", \"zh-Hant\", \"zh-Hans\", \"ko\", \"co\", \"xh\", \"ku\", \"km\", \"lo\", \"la\", \"lv\", \"ln\", \"lt\", \"lb\", \"mk\", \"mg\", \"ms\", \"ml\", \"dv\", \"mt\", \"mi\", \"mr\", \"mn\", \"und\", \"de\", \"ne\", \"nl\", \"no\", \"ny\", \"or\", \"om\", \"pa\", \"fa\", \"pl\", \"pt\", \"ps\", \"ro\", \"ru\", \"sm\", \"sa\", \"ceb\", \"nso\", \"sr\", \"si\", \"sd\", \"sk\", \"sl\", \"so\", \"sw\", \"su\", \"tg\", \"th\", \"ta\", \"tt\", \"te\", \"ti\", \"ts\", \"tr\", \"tk\", \"uz\", \"ug\", \"uk\", \"ur\", \"fil\", \"fi\", \"fr\", \"ha\", \"hi\", \"hmn\", \"hr\", \"cs\", \"sv\", \"sn\", \"ee\", \"eo\", \"et\", \"st\", \"jv\", \"ja\", \"kri\"
","type":["string","null"]},"tag":{"description":"
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
","type":["string","null"]},"video_id":{"description":"
ID of the video
required field
you can find video ID in the URL or 'youtube_video' item of YouTube Organic result
example:
Y8Wu4rSNJms
","type":"string"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Serp youtube video subtitles live advanced"},{"name":"url_metrics","description":"‌\nThis endpoint will provide you with rank scores of the domains, subdomains, and pages specified in the targets array. The score is based on the number of referring domains pointing to the specified domains, subdomains, or pages. The rank values represent real-time data for the date of the request and range from 0 (no backlinks detected) to 1,000 (highest rank). A similar scoring system is used in Google’s Page Rank algorithm. You can learn more about rank scores in this help center article","parameters":{"properties":{"input":{"additionalProperties":false,"properties":{"body":{"examples":[[{"targets":["forbes.com","cnn.com","bbc.com","yelp.com","https://www.apple.com/iphone/","https://ahrefs.com/blog/","ibm.com","https://variety.com/","https://stackoverflow.com/","www.trustpilot.com"]}]],"items":{"oneOf":[{"examples":[[{"targets":["forbes.com","cnn.com","bbc.com","yelp.com","https://www.apple.com/iphone/","https://ahrefs.com/blog/","ibm.com","https://variety.com/","https://stackoverflow.com/","www.trustpilot.com"]}]],"properties":{"rank_scale":{"description":"defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional field
you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
possible values:
one_hundred — rank values are displayed on a 0–100 scale
one_thousand — rank values are displayed on a 0–1000 scale
default value: one_thousand
learn more about how this parameter works and how ranking metrics are calculated in this Help Center article","type":["string","null"]},"tag":{"description":"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","type":["string","null"]},"targets":{"description":"domains, subdomains or webpages to get rank for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`","items":{"type":"string"},"type":"array"}},"type":"object"}],"type":["object","null"]},"type":"array"}},"required":[],"type":"object"}},"required":["input"],"type":"object"},"returns":{},"public":true,"title":"Url metrics","catalog":"web.url.metrics"}],"crons":{},"buffer":8388608,"deps":{"http":{"fetch":["api.dataforseo.com"],"proxy":[]},"secrets":["DATAFORSEO_AUTH_TOKEN"],"credentials":{"dataforseo":{"title":"DataForSEO API credentials","guide":"Use the Base64-encoded API login:API password from https://app.dataforseo.com/api-access as the Basic authentication token. Requests consume your DataForSEO balance.","hosts":["api.dataforseo.com"],"secrets":[{"name":"DATAFORSEO_AUTH_TOKEN","label":"Base64 API login:API password","masked":true}]}}},"events":[],"database_size":1073741824,"kits":[]},"yanked":false,"deployments":0},"managed":false,"private":null}