{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "DataForSEO Labs API Schemas", "definitions": { "DataforseoLabsGoogleCategoriesForKeywordsLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleCategoriesForKeywordsLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "BaseResponseInfo": { "properties": { "version": { "type": "string", "description": "the current version of the API", "nullable": true }, "status_code": { "type": "integer", "description": "general status code\nyou can find the full list of the response codes here", "nullable": true }, "status_message": { "type": "string", "description": "general informational message\nyou can find the full list of general informational messages here", "nullable": true }, "time": { "type": "string", "description": "total execution time, seconds", "nullable": true }, "cost": { "type": "number", "description": "total tasks cost, USD", "format": "double", "nullable": true }, "tasks_count": { "type": "integer", "description": "the number of tasks in the tasks array", "format": "int64", "nullable": true }, "tasks_error": { "type": "integer", "description": "the number of tasks in the tasks array returned with an error", "format": "int64", "nullable": true } } }, "DataforseoLabsGoogleCategoriesForKeywordsLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleCategoriesForKeywordsLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "BaseResponseTaskInfo": { "properties": { "id": { "type": "string", "description": "task identifier\nunique task identifier in our system in the UUID format", "nullable": true }, "status_code": { "type": "integer", "description": "status code of the task\ngenerated by DataForSEO, can be within the following range: 10000-60000\nyou can find the full list of the response codes here", "nullable": true }, "status_message": { "type": "string", "description": "informational message of the task\nyou can find the full list of general informational messages here", "nullable": true }, "time": { "type": "string", "description": "execution time, seconds", "nullable": true }, "cost": { "type": "number", "description": "total tasks cost, USD", "format": "double", "nullable": true }, "result_count": { "type": "integer", "description": "number of elements in the result array", "format": "int64", "nullable": true }, "path": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "URL path", "nullable": true }, "data": { "type": "object", "additionalProperties": { "type": "object", "nullable": true }, "description": "contains the same parameters that you specified in the POST request", "nullable": true } } }, "DataforseoLabsGoogleCategoriesForKeywordsLanguagesResultInfo": { "type": "object", "properties": { "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true } } }, "DataforseoLabsGoogleDomainIntersectionLiveRequestInfo": { "type": "object", "properties": { "target1": { "type": "string", "description": "domain\nrequired field\nthe domain name of the first target website\nthe domain should be specified without https:// and www." }, "target2": { "type": "string", "description": "domain\nrequired field\nthe domain name of the second target website\nthe domain should be specified without https:// and www." }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "intersections": { "type": "boolean", "description": "domain intersections in SERP\noptional field\nif 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\nNote: this endpoint will not provide results if the number of intersecting keywords exceeds 10 million\nif 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\u2019t;\nthus, the corresponding SERP elements and other data will be provided for the domain specified as target1only\ndefault value: true", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string" }, "description": "search results type\nindicates type of search results included in the response\noptional field\npossible values:\n[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]\ndefault value:\n[\"organic\", \"paid\"]", "nullable": true }, "include_serp_info": { "type": "boolean", "description": "include data from SERP for each keyword\noptional field\nif 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\ndefault value: false", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_keyword_info, clickstream_etv, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned keywords\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the items array of returned keywords\noptional field\ndefault value: 0\nif 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", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, match, not_match, ilike, not_ilike, like, not_like\nyou 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\nexample:\n[\"keyword_data.keyword_info.search_volume\",\"in\",[100,1000]]\n[[\"first_domain_serp_element.etv\",\">\",0],\"and\",[\"first_domain_serp_element.description\",\"like\",\"%goat%\"]]\n[[\"keyword_data.keyword_info.search_volume\",\">\",100],\n\"and\",\n[[\"first_domain_serp_element.description\",\"like\",\"%goat%\"],\n\"or\",\n[\"second_domain_serp_element.type\",\"=\",\"organic\"]]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to set up a sorting parameter\nexample:\n[\"keyword_data.keyword_info.competition,desc\"]\ndefault rule:\n[\"keyword_data.keyword_info.search_volume,desc\"]\nnote that you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"keyword_data.keyword_info.search_volume,desc\",\"keyword_data.keyword_info.cpc,desc\"]", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "target1": "mom.com", "target2": "quora.com", "language_code": "en", "location_code": 2840, "include_serp_info": true, "limit": 3 } ] }, "DataforseoLabsAmazonBulkSearchVolumeLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonBulkSearchVolumeLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsAmazonBulkSearchVolumeLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonBulkSearchVolumeLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsAmazonBulkSearchVolumeLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonBulkSearchVolumeLiveItem" } ], "nullable": true }, "description": "contains keyword search volume data data", "nullable": true } } }, "DataforseoLabsAmazonBulkSearchVolumeLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword": { "type": "string", "description": "keyword in a POST array", "nullable": true }, "search_volume": { "type": "integer", "description": "average monthly search volume rate\nrepresents the (approximate) number of searches for the returned keyword on Amazon", "format": "int64", "nullable": true } } }, "DataforseoLabsGoogleKeywordIdeasLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordIdeasLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleKeywordIdeasLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordIdeasLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleKeywordIdeasLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "seed_keywords": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "keywords in a POST array\nkeywords are returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total number of results relevant to your request in our database", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "number of results returned in the items array", "format": "int64", "nullable": true }, "offset": { "type": "integer", "description": "current offset value", "nullable": true }, "offset_token": { "type": "string", "description": "offset token for subsequent requests\nyou can use the string provided in this field to get the subsequent results of the initial task;\nnote: offset_token values are unique for each subsequent task", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "nullable": true }, "description": "contains keyword ideas and related data", "nullable": true } } }, "KeywordDataInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword": { "type": "string", "description": "returned keyword idea", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "keyword_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordInfo" } ], "description": "keyword data for the returned keyword idea", "nullable": true }, "keyword_info_normalized_with_bing": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordInfoNormalizedWithInfo" } ], "description": "contains keyword search volume normalized with Bing search volume", "nullable": true }, "keyword_info_normalized_with_clickstream": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordInfoNormalizedWithInfo" } ], "description": "contains keyword search volume normalized with clickstream data", "nullable": true }, "clickstream_keyword_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/ClickstreamKeywordInfo" } ], "description": "clickstream data for the returned keyword\nto retrieve results for this field, the parameter include_clickstream_data must be set to true", "nullable": true }, "keyword_properties": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordProperties" } ], "description": "additional information about the keyword", "nullable": true }, "serp_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpInfo" } ], "description": "SERP data\nthe value will be null if you didn\u2019t set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database", "nullable": true }, "avg_backlinks_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AvgBacklinksInfo" } ], "description": "backlink data for the returned keyword\nthis object provides the average number of backlinks, referring pages and domains, as well as the average rank values among the top-10 webpages ranking organically for the keyword", "nullable": true }, "search_intent_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SearchIntentInfo" } ], "description": "search intent info for the returned keyword\nlearn about search intent in this help center article", "nullable": true } } }, "KeywordInfoNormalizedWithInfo": { "type": "object", "properties": { "last_updated_time": { "type": "string", "description": "date and time when the dataset was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "search_volume": { "type": "integer", "description": "current search volume rate of a keyword", "nullable": true }, "is_normalized": { "type": "boolean", "description": "keyword info is normalized\nif true, values are normalized with Bing data", "nullable": true }, "monthly_searches": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/MonthlySearchesInfo" } ], "nullable": true }, "description": "monthly search volume rates\narray of objects with search volume rates in a certain month of a year", "nullable": true } } }, "MonthlySearchesInfo": { "type": "object", "properties": { "year": { "type": "integer", "description": "year", "nullable": true }, "month": { "type": "integer", "description": "month", "nullable": true }, "search_volume": { "type": "integer", "description": "monthly average search volume rate", "nullable": true } } }, "SearchIntentInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type\npossible values: google", "nullable": true }, "main_intent": { "type": "string", "description": "main search intent\npossible values: informational, navigational, commercial, transactional", "nullable": true }, "foreign_intent": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "supplementary search intents\npossible values: informational, navigational, commercial, transactional", "nullable": true }, "last_updated_time": { "type": "string", "description": "date and time when the dataset was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true } } }, "SerpInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "serp_item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP\npossible item types:\nanswer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, google_posts, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, visual_stories, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, found_on_web, short_videos, refine_products, explore_brands, perspectives, discussions_and_forums, compare_sites, courses, ai_overview;\nnote that the actual results will be returned only for organic, paid, featured_snippet, and local_pack elements", "nullable": true }, "se_results_count": { "type": "integer", "description": "number of search results for the returned keyword", "format": "int64", "nullable": true }, "last_updated_time": { "type": "string", "description": "date and time when search intent data was last updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "previous_updated_time": { "type": "string", "description": "previous to the most recent date and time when SERP data was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-10-15 12:57:46 +00:00", "nullable": true } } }, "KeywordInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "last_updated_time": { "type": "string", "description": "date and time when keyword data was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "competition": { "type": "number", "description": "competition\nrepresents the relative amount of competition associated with the given keyword. This value is based on Google Ads data and can be between 0 and 1 (inclusive)", "nullable": true }, "competition_level": { "type": "string", "description": "competition level\nrepresents the relative level of competition associated with the given keyword in paid SERP only;\npossible values: LOW, MEDIUM, HIGH\nif competition level is unknown, the value is null;\nlearn more about the metric in this help center article", "nullable": true }, "cpc": { "type": "number", "description": "cost-per-click\nrepresents the average cost per click (USD) historically paid for the keyword", "nullable": true }, "search_volume": { "type": "integer", "description": "average monthly search volume rate\nrepresents the (approximate) number of searches for the given keyword idea on google.com", "format": "int64", "nullable": true }, "low_top_of_page_bid": { "type": "number", "description": "minimum bid for the ad to be displayed at the top of the first page\nindicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers)\nthe value may differ depending on the location specified in a POST request", "nullable": true }, "high_top_of_page_bid": { "type": "number", "description": "maximum bid for the ad to be displayed at the top of the first page\nindicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers)\nthe value may differ depending on the location specified in a POST request", "nullable": true }, "categories": { "type": "array", "items": { "type": "integer" }, "description": "product and service categories\nyou can download the\u00a0full list of possible categories", "nullable": true }, "monthly_searches": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/MonthlySearchesInfo" } ], "nullable": true }, "description": "monthly searches\nrepresents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations", "nullable": true }, "search_volume_trend": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SearchVolumeTrend" } ], "description": "search volume trend changes\nrepresents search volume change in percent compared to the previous period", "nullable": true } } }, "SearchVolumeTrend": { "type": "object", "properties": { "monthly": { "type": "integer", "description": "search volume change in percent compared to the previous month", "nullable": true }, "quarterly": { "type": "integer", "description": "search volume change in percent compared to the previous quarter", "nullable": true }, "yearly": { "type": "integer", "description": "search volume change in percent compared to the previous year", "nullable": true } } }, "AvgBacklinksInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "backlinks": { "type": "number", "description": "average number of backlinks", "nullable": true }, "dofollow": { "type": "number", "description": "average number of dofollow links", "nullable": true }, "referring_pages": { "type": "number", "description": "average number of referring pages", "nullable": true }, "referring_domains": { "type": "number", "description": "average number of referring domains", "nullable": true }, "referring_main_domains": { "type": "number", "description": "average number of referring main domains", "nullable": true }, "rank": { "type": "number", "description": "average rank\nlearn more about the metric and its calculation formula in this help center article", "nullable": true }, "main_domain_rank": { "type": "number", "description": "average main domain rank\nlearn more about the metric and its calculation formula in this help center article", "nullable": true }, "last_updated_time": { "type": "string", "description": "date and time when the dataset was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true } } }, "KeywordProperties": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "core_keyword": { "type": "string", "description": "main keyword in a group\ncontains the main keyword in a group determined by the synonym clustering algorithm\nif the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword", "nullable": true }, "synonym_clustering_algorithm": { "type": "string", "description": "the algorithm used to identify synonyms\npossible values:\nkeyword_metrics \u2013 indicates the algorithm based on keyword_info parameters\ntext_processing \u2013 indicates the text-based algorithm\nif the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword", "nullable": true }, "keyword_difficulty": { "type": "integer", "description": "difficulty of ranking in the first top-10 organic results for a keyword\nindicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100;\ncalculated by analysing, among other parameters, link profiles of the first 10 pages in SERP;\nlearn more about the metric in this help center guide", "nullable": true }, "detected_language": { "type": "string", "description": "detected language of the keyword\nindicates the language of the keyword as identified by our system", "nullable": true }, "is_another_language": { "type": "boolean", "description": "detected language of the keyword is different from the set language\nif true, the language set in the request does not match the language determined by our system for a given keyword", "nullable": true }, "words_count": { "type": "integer", "description": "number of words in the keyword\nindicates how many words the keyword consists of", "format": "int64", "nullable": true } } }, "ClickstreamKeywordInfo": { "type": "object", "properties": { "search_volume": { "type": "integer", "description": "current search volume rate of a keyword", "format": "int64", "nullable": true }, "last_updated_time": { "type": "string", "description": "date and time when backlink data was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "gender_distribution": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64", "nullable": true }, "description": "distribution of estimated clickstream-based metrics by gender\nlearn more about how the metric is calculated in this help center article", "nullable": true }, "age_distribution": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64", "nullable": true }, "description": "distribution of clickstream-based metrics by age\nlearn more about how the metric is calculated in this help center article", "nullable": true }, "monthly_searches": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/MonthlySearchesInfo" } ], "nullable": true }, "description": "monthly searches\nrepresents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations", "nullable": true } } }, "DataforseoLabsGoogleDomainMetricsByCategoriesLiveRequestInfo": { "type": "object", "properties": { "category_codes": { "type": "array", "items": { "type": "string" }, "description": "product and service categories\nrequired field\nThe maximum number of categories you can specify: 5\nyou can download the full list of possible categories" }, "first_date": { "type": "string", "description": "first date of comparison period\nrequired field\nfirst date for which domain metrics will be provided;\ndate format: \"yyyy-mm-dd\";\nexample: \"2021-06-01\";\nthe list available dates is available through the available history endpoint;\nNote: first_date cannot be greater than today\u2019s date;\nAlso note: the dates specified in first_date and second_date cannot point to the same month of the same year;\nyou can specify the dates in any order: first_date can be greater than second_date and vice versa;\nminimum date: \"2020-10-01\"" }, "second_date": { "type": "string", "description": "second date of comparison period\nrequired field\nsecond date for which domain metrics will be provided;\ndate format: \"yyyy-mm-dd\";\nexample: \"2021-10-01\";\nthe list available dates is available through the available history endpoint;\nNote: second_date cannot be greater than today\u2019s date;\nAlso note: the dates specified in first_date and second_date cannot point to the same month of the same year;\nyou can specify the dates in any order: second_date can be greater than first_date and vice versa;\nminimum date: \"2020-10-01\"" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code;\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "unique location identifier\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code;\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code;\nyou can receive the list of available languages with their language_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "unique language identifier\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code;\nyou 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;\nexample:\nen", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string" }, "description": "display results by item type\noptional field\nindicates the type of search results included in the response;\nNote: 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;\npossible values:\n[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"];\ndefault value:\n[\"organic\", \"paid\"]", "nullable": true }, "top_categories_count": { "type": "integer", "description": "number of additional domain categories\noptional field\nby using this parameter, you can receive domains relevant to additional categories that are not specified in category_codes above;\nto learn more about the parameter, please refer to this help center article;\nby default, top_categories_count is equal to the number of categories specified in the category_codes array;\nNote: top_categories_count cannot be less than the number of categories in the category_codes array;\nmaximum value: 5", "format": "int64", "nullable": true }, "include_subdomains": { "type": "boolean", "description": "return subdomains in the API response\noptional field\nif false, the API response will contain main_domain only;\nif true, the API will return main_domain plus its subdomains (if available);\ndefault value: true", "nullable": true }, "etv_min": { "type": "integer", "description": "minimum current organic ETV of the domain\noptional field\nif specified, the API will return only domains with organic_etv greater than the specified value", "nullable": true }, "etv_max": { "type": "integer", "description": "maximum current organic ETV of the domain\noptional field\nif specified, the API will return only domains with organic_etv lesser than the specified value", "nullable": true }, "correlate": { "type": "boolean", "description": "correlate data with previously obtained datasets\noptional field\ndefault value: true;\nif you use this parameter, our system will correlate data you obtain now with previously obtained datasets;\nthis parameter is intended to mitigate any inconsistencies that may result from changes to our database;\nNote: we do not recommend setting correlate to false", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of domains in the results array\noptional field\ndefault value: 100;\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned domains\noptional field\ndefault value: 0;\nif 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", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, match, not_match, ilike, not_ilike, like, not_like;\nyou 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;\nexample:\n[\"metrics_history.202110.organic.pos_1\", \">\", 15];\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results;\ndefault rule: [\"organic_etv,desc\"];\npossible sorting types:\nasc \u2013 results will be sorted in ascending order\ndesc \u2013 results will be sorted in descending order;\nyou should use a comma to set up a sorting type;\nexample:\n[\"organic_count,desc\"];\nnote that you can set no more than three sorting rules in a single request;\nyou should use a comma to separate several sorting rules;\nexample:\n[\"organic_etv,desc\",\"organic_count,asc\"]", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "location_code": 2840, "language_code": "en", "category_codes": [ 13418, 11494 ], "first_date": "2026-01-15", "second_date": "2026-03-15", "limit": 3 } ] }, "DataforseoLabsGoogleBulkKeywordDifficultyLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleBulkKeywordDifficultyLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleBulkKeywordDifficultyLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleBulkKeywordDifficultyLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleBulkKeywordDifficultyLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleBulkKeywordDifficultyLiveItem" } ], "nullable": true }, "description": "contains keywords and related keyword difficulty scores", "nullable": true } } }, "DataforseoLabsGoogleBulkKeywordDifficultyLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword": { "type": "string", "description": "keyword in a POST array", "nullable": true }, "keyword_difficulty": { "type": "integer", "description": "difficulty of ranking in the first top-10 organic results for a keyword\nindicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100;\ncalculated by analysing, among other parameters, link profiles of the first 10 pages in SERP;\nlearn more about the metric in this help center guide", "nullable": true } } }, "DataforseoLabsAvailableFiltersResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAvailableFiltersTaskInfo" } ], "nullable": true }, "nullable": true } } } ] }, "DataforseoLabsAvailableFiltersTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAvailableFiltersResultInfo" } ], "nullable": true }, "nullable": true } } } ] }, "DataforseoLabsAvailableFiltersResultInfo": { "type": "object", "properties": { "related_keywords": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "keyword_suggestions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "ranked_keywords": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "keyword_ideas": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "serp_competitors": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "relevant_pages": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "subdomains": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "competitors_domain": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "categories_for_domain": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "keywords_for_categories": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "domain_intersection": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "page_intersection": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "top_searches": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "domain_metrics_by_categories": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "keywords_for_site": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "product_competitors": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "product_keyword_intersections": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "app_intersection": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "app_competitors": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "keywords_for_app": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true }, "nullable": true }, "database_rows_count": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true } } }, "DataforseoLabsGooglePageIntersectionLiveRequestInfo": { "type": "object", "properties": { "pages": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "target URLs of pages\nrequired field\nyou can set up to 20 pages in this object\nthe pages should be specified with absolute URLs (including http:// or https://)\nexample:\n\"pages\": {\n\"1\":\"https://www.apple.com/mac/*\",\n\"2\":\"https://dataforseo.com/*\",\n\"3\":\"https://support.microsoft.com/\"\n}if you specify a single page here, we will return results only for this page;\nyou can also use a wildcard (\u2018*\u2019) character to specify the search pattern\nexample:\n\"example.com\"\nsearch for the exact URL\n\"example.com/eng/*\"\nsearch for the example.com page and all its related URLs which start with \u2018/eng/\u2019, such as \u201cexample.com/eng/index.html\u201d and \u201cexample.com/eng/help/\u201d, etc.\nnote: a wilcard should be placed after the slash (\u2018/\u2019) character in the end of the URL, it is not possible to place it after the domain in the following way:\nhttps://dataforseo.com*\nuse https://dataforseo.com/* instead\nNote: this endpoint will not provide results if the number of intersecting keywords exceeds 10 million", "nullable": true }, "exclude_pages": { "type": "array", "items": { "type": "string" }, "description": "URLs of pages you want to exclude\noptional field\nyou can set up to 10 pages in this array\nif 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;\nnote 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.\nuse a wildcard (\u2018*\u2019) character to specify the search pattern\nexample:\n\"exclude_pages\": [\n\"https://www.apple.com/iphone/*\",\n\"https://dataforseo.com/apis/*\",\n\"https://www.microsoft.com/en-us/industry/services/\"\n]", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string" }, "description": "search results type\nindicates type of search results included in the response\noptional field\npossible values:\n[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]\ndefault value:\n[\"organic\", \"paid\"]", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned keywords\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the items array of returned keywords\noptional field\ndefault value: 0\nif 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", "nullable": true }, "include_subdomains": { "type": "boolean", "description": "indicates if the subdomains will be included in the search\noptional field\nif set to false, the subdomains will be ignored\ndefault value: true", "nullable": true }, "intersection_mode": { "type": "string", "description": "indicates whether to intersect keywords\noptional field\nuse this field to intersect or merge results for the specified URLs\npossible values: union, intersect\nunion \u2013 results are based on all keywords any URL from pages rank for;\nintersect \u2013 results are based on the keywords all URLs from pages rank for in the same SERP:\nby 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", "nullable": true }, "include_serp_info": { "type": "boolean", "description": "include data from SERP for each keyword\noptional field\nif 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\ndefault value: false", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_keyword_info, clickstream_etv, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, ilike, not_ilike, like, not_like, match, not_match\nyou 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\nnote that if you want to filter by any field in the intersection_result array you need to specify the number of corresponding page\nfor instance, if you want to filter results by the ranking of the first specified URL, you should set the following filter:\n[intersection_result.1.rank_absolute,\"=\",1]\nif you want to filter results and receive only organic listings for the third specified URL, you should set the following filter:\n[intersection_result.3.type,\"=\",\"organic\"] , etc.example:\n[\"keyword_data.keyword_info.search_volume\",\"in\",[100,1000]]\n[[\"intersection_result.1.etv\",\">\",0],\"and\",[\"intersection_result.1.description\",\"like\",\"%goat%\"]][[\"keyword_data.keyword_info.search_volume\",\">\",100],\n\"and\",\n[[\"intersection_result.2.description\",\"like\",\"%goat%\"],\n\"or\",\n[\"intersection_result.2.type\",\"=\",\"organic\"]]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to set up a sorting parameter\nexample:\n[\"keyword_data.keyword_info.competition,desc\"]\ndefault rule:\n[\"keyword_data.keyword_info.search_volume,desc\"]\nnote that you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"intersection_result.1.rank_group,asc\",\"intersection_result.2.rank_absolute,asc\"]", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "pages": { "1": "https://forbes.com", "2": "https://cnn.com/*" }, "language_name": "English", "location_code": 2840, "include_serp_info": true, "limit": 3 } ] }, "DataforseoLabsAmazonBulkSearchVolumeLiveRequestInfo": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" }, "description": "target keywords\nrequired field\nUTF-8 encoding\nmaximum number of keywords you can specify in this array: 1000;\nthe keywords will be converted to lowercase format\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if don\u2019t specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\n\nNote: this endpoint currently supports the following locations and languages only:\nAustralia \u2013 2036, en\nAustria \u2013 2040, de\nCanada \u2013 2124, en\nEgypt \u2013 2818, ar\nFrance \u2013 2250, fr\nGermany \u2013 2276, de\nIndia \u2013 2356, en\nItaly \u2013 2380, it\nMexico \u2013 2484, es\nNetherlands \u2013 2528, nl\nSaudi Arabia \u2013 2682, ar\nSingapore \u2013 2702, en\nSpain \u2013 2724, es\nUnited Arab Emirates \u2013 2784, ar\nUnited Kingdom \u2013 2826, en\nUnited States \u2013 2840, en\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if don\u2019t specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports these locations and languages only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if don\u2019t specify language_code\nyou 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\nNote: this endpoint currently supports these locations and languages only;\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if don\u2019t specify language_name\nyou 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\nNote: this endpoint currently supports these locations and languages only;\nexample:\nen", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "keywords": [ "buy laptop", "cheap laptops for sale", "purchase laptop" ], "location_code": 2840, "language_code": "en" } ] }, "DataforseoLabsGoogleRelatedKeywordsLiveRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword\nrequired field\nUTF-8 encoding\nthe keywords will be converted to lowercase format\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available locations with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available locations with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "depth": { "type": "integer", "description": "keyword search depth\noptional field\ndefault value: 1\nnumber of the returned results depends on the value you set in this field\nyou can specify a level from 0 to 4\nestimated number of keywords for each level (maximum):\n0 \u2013 the keyword set in the keyword field\n1 \u2013 8 keywords\n2 \u2013 72 keywords\n3 \u2013 584 keywords\n4 \u2013 4680 keywords", "nullable": true }, "include_seed_keyword": { "type": "boolean", "description": "include data for the seed keyword\noptional field\nif 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\ndefault value: false", "nullable": true }, "include_serp_info": { "type": "boolean", "description": "include data from SERP for each keyword\noptional field\nif 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\ndefault value: false", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "replace_with_core_keyword": { "type": "boolean", "description": "return data for core keyword\noptional field\nif true, serp_info and related_keywords will be returned for the main keyword in the group that the specified keyword belongs to;\nif false, serp_info and related_keywords will be returned for the specified keyword (if available);\nrefer to this help center article for more details;\ndefault value: false", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, match, not_match, ilike, not_ilike, like,not_like\nyou 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\nexample:\n[\"keyword_data.keyword_info.search_volume\",\">\",0]\n[[\"keyword_info.search_volume\",\"in\",[0,1000]],\n\"and\",\n[\"keyword_data.keyword_info.competition_level\",\"=\",\"LOW\"]]\n[[\"keyword_data.keyword_info.search_volume\",\">\",100],\n\"and\",\n[[\"keyword_data.keyword_info.cpc\",\"<\",0.5],\n\"or\",\n[\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to set up a sorting type\nexample:\n[\"keyword_data.keyword_info.competition,desc\"]\ndefault rule:\n[\"keyword_data.keyword_info.search_volume,desc\"]\nnote that you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"keyword_data.keyword_info.search_volume,desc\",\"keyword_data.keyword_info.cpc,desc\"]", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned keywords\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "keyword": "phone", "language_name": "English", "location_code": 2840, "limit": 3 } ] }, "DataforseoLabsAppleKeywordsForAppLiveRequestInfo": { "type": "object", "properties": { "app_id": { "type": "string", "description": "id of the app\nrequired field\nID of the mobile application on App Store;\nyou can find the ID in the URL of every app listed on App Store;\nexample:\nin the URL https://apps.apple.com/us/app/id835599320\nthe id is 835599320" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only;\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only\nexample:\nen", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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:\n<, <=, >, >=, =, <>, in, not_in\nexample:\n[\"keyword_data.keyword_info.search_volume\",\">\",500]\n[[\"keyword_data.keyword_info.search_volume\",\"<>\",500],\"and\",[\"ranked_serp_element.serp_item.rank_group\",\">=\",\"10\"]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results;\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order;\ndesc \u2013 results will be sorted in the descending order;\nyou should use a comma to specify a sorting type;\nexample:\n[\"ranked_serp_element.serp_item.rank_group,asc\"]\nNote: you can set no more than three sorting rules in a single request;\nyou should use a comma to separate several sorting rules;\nexample:\n[\"ranked_serp_element.serp_item.rank_group,desc\",\"keyword_data.keyword_info.search_volume,asc\"]\ndefault rule:\n[\"keyword_data.keyword_info.search_volume,desc\"]\nNote: 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", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned keywords\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "app_id": "686449807", "language_name": "English", "location_code": 2840, "limit": 10 } ] }, "DataforseoLabsGoogleSerpCompetitorsLiveRequestInfo": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" }, "description": "keywords array\nrequired field\nthe results will be based on the keywords you specify in this array\nUTF-8 encoding;\nthe keywords will be converted to lowercase format;\nyou can specify the maximum of 200 keywords\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with location_name parameters by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "unique location identifier\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code parameters by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name parameters by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "unique language identifier\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code parameters by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "include_subdomains": { "type": "boolean", "description": "indicates if the subdomains will be included in the search\noptional field\nif set to false, the subdomains will be ignored\ndefault value: true", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string" }, "description": "search results type\nindicates type of search results included in the response\noptional field\npossible values:\n[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]\ndefault value:\n[\"organic\", \"paid\"]", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned domains\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned domains\noptional field\ndefault value: 0\nif 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", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, match, not_match, ilike, not_ilike, like, not_like\nyou 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\nexample:\n[\"median_position\",\"in\",[1,10]]\n[[\"median_position\",\"in\",[1,10]],\"and\",[\"domain\",\"not_like\",\"%wikipedia.org%\"]]\n[[\"domain\",\"not_like\",\"%wikipedia.org%\"],\n\"and\",\n[[\"relevant_serp_items\",\">\",0],\"or\",[\"median_position\",\"in\",[1,10]]]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nthe comma is used as a separator\nexample:\n[\"avg_position,asc\"]\ndefault rule:\n[\"rating,desc\"]\nnote that you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"avg_position,asc\",\"etv,desc\"]", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "keywords": [ "phone" ], "language_name": "English", "location_code": 2840, "item_types": [ "organic" ], "limit": 5 } ] }, "DataforseoLabsCategoriesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsCategoriesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsCategoriesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsCategoriesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsCategoriesResultInfo": { "type": "object", "properties": { "category_code": { "type": "integer", "description": "category code", "nullable": true }, "category_name": { "type": "string", "description": "full name of the category", "nullable": true }, "category_code_parent": { "type": "integer", "description": "the code of the superordinate category\nexample:\n\"category_code\": 10178,\n\"category_name\": \"Apparel Accessories\",\n\"category_code_parent\": 10021\nwhere category_code_parent\ncorresponds to:\n\"category_code\": 10021,\n\"category_name\": \"Apparel\"\n\"category_code_parent\": null", "nullable": true } } }, "DataforseoLabsGoogleKeywordSuggestionsLiveRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword\nrequired field\nUTF-8 encoding\nthe keywords will be converted to lowercase format;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of the location\noptional field\nif you use this field, you don\u2019t need to specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\noptional field\nif you use this field, you don\u2019t need to specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\noptional field\nif you use this field, you don\u2019t need to specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish\nNote: if omitted, results default to the language with the most keyword records in the specified location;\nrefer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language", "nullable": true }, "language_code": { "type": "string", "description": "language code\noptional field\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen\nNote: if omitted, results default to the language with the most keyword records in the specified location;\nrefer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language", "nullable": true }, "include_seed_keyword": { "type": "boolean", "description": "include data for the seed keyword\noptional field\nif 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\ndefault value: false", "nullable": true }, "include_serp_info": { "type": "boolean", "description": "include data from SERP for each keyword\noptional field\nif 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\ndefault value: false", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "exact_match": { "type": "boolean", "description": "search for the exact phrase\noptional field\nif set to true, the returned keywords will include the exact keyword phrase you specified, with potentially other words before or after that phrase\ndefault value: false", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, match, not_match, ilike, not_ilike, like, not_like\nyou 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\nexample:\n[\"keyword_info.search_volume\",\">\",0]\n[[\"keyword_info.search_volume\",\"in\",[0,1000]],\n\"and\",\n[\"keyword_info.competition_level\",\"=\",\"LOW\"]][[\"keyword_info.search_volume\",\">\",100],\n\"and\",\n[[\"keyword_info.cpc\",\"<\",0.5],\n\"or\",\n[\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\na comma is used as a separator\nexample:\n[\"keyword_info.competition,desc\"]\ndefault rule:\n[\"keyword_info.search_volume,desc\"]\nnote that you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"keyword_info.search_volume,desc\",\"keyword_info.cpc,desc\"]", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned keywords\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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\nNote: we recommend using this parameter only when retrieving up to 10,000 results\nfor retrieving over 10,000 results, use the offset_token instead.", "nullable": true }, "offset_token": { "type": "string", "description": "offset token for subsequent requests\noptional field\nprovided in the identical filed of the response to each request;\nuse this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;\nby specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;\noffset_token values are unique for each subsequent task\nNote: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.\nlearn more about this parameter on our Help Center", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "keyword": "phone", "location_code": 2840, "language_code": "en", "include_serp_info": true, "include_seed_keyword": true, "limit": 1 } ] }, "DataforseoLabsIdListRequestInfo": { "type": "object", "properties": { "datetime_from": { "type": "string", "description": "start time for filtering results\nrequired field\nif include_metadata is set to true, maximum value: a month from current datetime;\nif include_metadata is set to false, maximum value: six months from current datetime;\nmust be specified in the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2023-01-15 12:57:46 +00:00" }, "datetime_to": { "type": "string", "description": "finish time for filtering results\nrequired field\nmaximum value: current datetime;\nmust be specified in the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2023-01-31 13:57:46 +00:00" }, "limit": { "type": "integer", "description": "the maximum number of returned task IDs\noptional field\ndefault value: 1000\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned task IDs\noptional field\ndefault value: 0\nif you specify the 10 value, the first ten tasks in the results array will be omitted", "nullable": true }, "sort": { "type": "string", "description": "sorting by task execution time\noptional field\npossible values: \"asc\", \"desc\"\ndefault value: \"asc\"", "nullable": true }, "include_metadata": { "type": "boolean", "description": "include task metadata in the respond\noptional field\ndefault value: false", "nullable": true } }, "example": [ { "datetime_from": "2026-04-12 04:39:39 +00:00", "datetime_to": "2026-04-14 04:39:39 +00:00", "limit": 100, "offset": 0, "sort": "desc", "include_metadata": true } ] }, "DataforseoLabsGoogleHistoricalSerpsLiveRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field;\nall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character);\nif you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;\nif you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d" }, "date_from": { "type": "string", "description": "starting date of the time range\noptional field\nif you don\u2019t specify this field, the API will return all SERPs collected for 365 days starting from the current datetime value;\nminimal possible value: 365 days from the current datetime value;\ndate format: \"yyyy-mm-dd\"", "nullable": true }, "date_to": { "type": "string", "description": "ending date of the time range\noptional field\nif you don\u2019t specify this field, the today\u2019s date will be used by default;\ndate format: \"yyyy-mm-dd\";\nexample:\n\"2021-09-01\"", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou 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\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "unique location identifier\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou 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\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name parameters by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "unique language identifier\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code parameters by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "keyword": "albert einstein", "location_code": 2840, "language_code": "en", "date_from": "2026-01-15", "date_to": "2026-03-15" } ] }, "DataforseoLabsGoogleDomainRankOverviewLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleDomainRankOverviewLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleDomainRankOverviewLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleDomainRankOverviewLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleDomainRankOverviewLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "target": { "type": "string", "description": "target domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleDomainRankOverviewLiveItem" } ], "nullable": true }, "description": "contains ranking and traffic data", "nullable": true } } }, "DataforseoLabsGoogleDomainRankOverviewLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataforseoLabsMetricsInfo" }, "description": "ranking data relevant to the specified domain", "nullable": true } } }, "DataforseoLabsMetricsInfo": { "type": "object", "properties": { "pos_1": { "type": "integer", "description": "number of organic SERPs where the domain or subdomain ranks #1", "nullable": true }, "pos_2_3": { "type": "integer", "description": "number of organic SERPs where the domain or subdomain ranks #2-3", "nullable": true }, "pos_4_10": { "type": "integer", "description": "number of organic SERPs where the domain or subdomain ranks #4-10", "nullable": true }, "pos_11_20": { "type": "integer", "description": "number of organic SERPs where the domain or subdomain ranks #11-20", "nullable": true }, "pos_21_30": { "type": "integer", "description": "number of organic SERPs where the domain or subdomain ranks #21-30", "nullable": true }, "pos_31_40": { "type": "integer", "description": "number of organic SERPs where the domain or subdomain ranks #31-40", "nullable": true }, "pos_41_50": { "type": "integer", "description": "number of organic SERPs where the domain or subdomain ranks #41-50", "nullable": true }, "pos_51_60": { "type": "integer", "description": "number of organic SERPs where the domain or subdomain ranks #51-60", "nullable": true }, "pos_61_70": { "type": "integer", "description": "number of organic SERPs where the domain or subdomain ranks #61-70", "nullable": true }, "pos_71_80": { "type": "integer", "description": "number of organic SERPs where the domain or subdomain ranks #71-80", "nullable": true }, "pos_81_90": { "type": "integer", "description": "number of organic SERPs where the domain or subdomain ranks #81-90", "nullable": true }, "pos_91_100": { "type": "integer", "description": "number of organic SERPs where the domain or subdomain ranks #91-100", "nullable": true }, "etv": { "type": "number", "description": "estimated traffic volume\nestimated organic monthly traffic to the domain or subdomain\ncalculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain or subdomain ranks for\nlearn more about how the metric is calculated in this help center article", "nullable": true }, "count": { "type": "integer", "description": "total count of organic SERPs that contain the domain or subdomain", "format": "int64", "nullable": true }, "estimated_paid_traffic_cost": { "type": "number", "description": "estimated cost of converting organic search traffic into paid\nrepresents the estimated monthly cost (USD) of running ads for all keywords in the category that the domain or subdomain ranks for\nthe metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search\nlearn more about how the metric is calculated in this help center article", "nullable": true }, "is_new": { "type": "integer", "description": "number of new ranked elements\nindicates how many new ranked elements were found for the indicated target", "nullable": true }, "is_up": { "type": "integer", "description": "rank went up\nindicates how many ranked elements of the indicated target went up", "nullable": true }, "is_down": { "type": "integer", "description": "rank went down\nindicates how many ranked elements of the indicated target went down", "nullable": true }, "is_lost": { "type": "integer", "description": "lost ranked elements\nindicates how many ranked elements of the indicated target were previously presented in SERPs, but weren\u2019t found during the last check", "nullable": true }, "clickstream_etv": { "type": "number", "description": "estimated traffic volume based on clickstream data\ncalculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for\nto retrieve results for this field, the parameter include_clickstream_data must be set to true\nlearn more about how the metric is calculated in this help center article", "format": "double", "nullable": true }, "clickstream_gender_distribution": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64", "nullable": true }, "description": "distribution of estimated clickstream-based metrics by gender\nto retrieve results for this field, the parameter include_clickstream_data must be set to true\nlearn more about how the metric is calculated in this help center article", "nullable": true }, "clickstream_age_distribution": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64", "nullable": true }, "description": "distribution of clickstream-based metrics by age\nto retrieve results for this field, the parameter include_clickstream_data must be set to true\nlearn more about how the metric is calculated in this help center article", "nullable": true } } }, "DataforseoLabsAmazonRelatedKeywordsLiveRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword\nrequired field\nUTF-8 encoding\nthe keywords should be specified in the lowercase format\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou 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\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou 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\nexample:\nen", "nullable": true }, "depth": { "type": "integer", "description": "keyword search depth\noptional field\ndefault value: 1;\nnumber of the returned results depends on the value you set in this field;\nyou can specify a level from 0 to 4;\nestimated number of keywords for each level (maximum):\n0 \u2013 the keyword set in the keyword field\n1 \u2013 6 keywords\n2 \u2013 42 keywords\n3 \u2013 258 keywords\n4 \u2013 1554 keywords", "nullable": true }, "include_seed_keyword": { "type": "boolean", "description": "include data for the seed keyword\noptional field\nif 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\ndefault value: false", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned keywords\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "keyword": "computer mouse", "language_name": "English", "location_code": 2840, "limit": 5, "include_seed_keyword": true } ] }, "DataforseoLabsGoogleKeywordsForCategoriesLiveRequestInfo": { "type": "object", "properties": { "category_codes": { "type": "array", "items": { "type": "string" }, "description": "product and service categories\nrequired field\nThe maximum number of categories you can specify: 20\nyou can download the full list of possible categories" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "unique location identifier\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "unique language identifier\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "category_intersection": { "type": "boolean", "description": "category intersections\noptional field\nif\u00a0set to true, you will get keywords featured in all specified categories;\nif set to false, you will keywords that are specified in any of the specified categories;\ndefault value: true", "nullable": true }, "include_serp_info": { "type": "boolean", "description": "include data from SERP for each keyword\noptional field\nif 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\ndefault value: false", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of keywords in the results array\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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\nNote: we recommend using this parameter only when retrieving up to 10,000 results\nfor retrieving over 10,000 results, use the offset_token instead.", "nullable": true }, "offset_token": { "type": "string", "description": "offset token for subsequent requests\noptional field\nprovided in the identical filed of the response to each request;\nuse this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;\nby specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;\noffset_token values are unique for each subsequent task\nNote: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.\nlearn more about this parameter on our Help Center", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, match, not_match, ilike, not_ilike, like, not_like\nyou can use the % operator with like and not_like,as well as ilike, not_ilike to match any string of zero or more characters\nexample:\n[\"keyword_info.search_volume\",\">\",0]\n[[\"keyword_info.search_volume\",\"in\",[0,1000]],\n\"and\",\n[\"keyword_info.competition_level\",\"=\",\"LOW\"]]\n[[\"keyword_info.search_volume\",\">\",100],\n\"and\",\n[[\"keyword_info.cpc\",\"<\",0.5],\n\"or\",\n[\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to set up a sorting type\nexample:\n[\"keyword_info.competition,desc\"]\ndefault rule:\n[\"keyword_info.search_volume,desc\"]\nnote that you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"keyword_info.search_volume,desc\",\"keyword_info.competition,asc\"]", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "category_codes": [ 12191, 12193 ], "language_name": "English", "location_code": 2840, "include_serp_info": true, "limit": 3 } ] }, "DataforseoLabsLocationsAndLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsLocationsAndLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsLocationsAndLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsLocationsAndLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsLocationsAndLanguagesResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code" }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nthe value will be null as Country is the only supported location_type for this API", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type\npossible values:\nCountry", "nullable": true }, "available_languages": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AvailableLanguages" } ], "nullable": true }, "description": "supported languages\ncontains the languages which are supported for a specific location", "nullable": true } } }, "AvailableLanguages": { "type": "object", "properties": { "available_sources": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "supported sources\ncontains the sources of data supported for a specific location and language combination\nonly google and bing are currently available", "nullable": true }, "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true }, "keywords": { "type": "integer", "description": "the number of keywords available for the given location and language", "nullable": true }, "serps": { "type": "integer", "description": "the number of SERP pages available for the given location and language", "nullable": true } } }, "DataforseoLabsGoogleHistoricalRankOverviewLiveRequestInfo": { "type": "object", "properties": { "target": { "type": "string", "description": "domain\nrequired field\nthe domain name of the target website\nthe domain should be specified without https:// and www." }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available locations with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available locations with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "date_from": { "type": "string", "description": "starting date of the time range\noptional field\nif you don\u2019t specify this field, the data will be provided for the previous 6 months\nminimal possible value: 2020-10-01\ndate format: \"yyyy-mm-dd\"", "nullable": true }, "date_to": { "type": "string", "description": "ending date of the time range\noptional field\nif you don\u2019t specify this field, the today\u2019s date will be used by default\ndate format: \"yyyy-mm-dd\"\nexample:\n\"2021-04-01\"", "nullable": true }, "correlate": { "type": "boolean", "description": "correlate data with previously obtained datasets\noptional field\ndefault value: true\nif you use this parameter, our system will correlate data you obtain now with previously obtained datasets\nthis parameter is intended to mitigate any inconsistencies that may result from changes to our database\nwe recommend always setting correlate to true", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true, only data based on core keywords will be returned, data for all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_etv, clickstream_gender_distribution, and\u00a0clickstream_age_distribution\u00a0fields with clickstream data in the response;\ndefault value: false;\nNote: historical clickstream data is available from 2024/05 (May, 2024);\nwith this parameter enabled, you will be charged double the price for the request;\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "target": "dataforseo.com", "location_code": 2840, "language_code": "en", "date_from": "2026-01-15", "date_to": "2026-03-15" } ] }, "DataforseoLabsGoogleRankedKeywordsLiveRequestInfo": { "type": "object", "properties": { "target": { "type": "string", "description": "domain name or page url\nrequired field\nthe domain name of the target website or URL of the target webpage;\nthe domain name must be specified without https:// or www.;\nthe webpage URL must be specified with https:// or www.\nNote: if you specify the webpage URL without https:// or www., the result will be returned for the entire domain rather than the specific page" }, "location_name": { "type": "string", "description": "full name of the location\noptional field\nif you use this field, you don\u2019t need to specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\noptional field\nif you use this field, you don\u2019t need to specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\noptional field\nif you use this field, you don\u2019t need to specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\noptional field\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available languages\nexample:\nen", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string" }, "description": "display results by item type\noptional field\nindicates the type of search results included in the response\nNote: 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;\npossible values:\n[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\", \"ai_overview_reference\"]\ndefault value:\n[\"organic\", \"paid\"]", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, 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\u00a0fields in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned keywords\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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", "nullable": true }, "load_rank_absolute": { "type": "boolean", "description": "return rankings distribution by rank_absolute\noptional field\ndefault value: false\nif set to true, we will return the field metrics_absolute containing rankings distribution by the rank_absolute parameter that indicates the result\u2019s position among all SERP elements", "nullable": true }, "historical_serp_mode": { "type": "string", "description": "data collection mode\noptional field\nyou can use this field to filter the results;\npossible types of filtering:\nlive \u2014 return keywords for which the specified target currently has ranking results in SERP;\nlost \u2014 return keywords for which the specified target had previously had ranking results in SERP, but didn\u2019t have them during the last check;\nall \u2014 return both types of keywords.\ndefault value: live", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, match, not_match, ilike, not_ilike, like, not_like\nyou 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\nexample:\n[\"ranked_serp_element.serp_item.rank_group\",\"<=\",10]\n[[\"ranked_serp_element.serp_item.rank_group\",\"<=\",10],\n\"and\",\n[\"ranked_serp_element.serp_item.type\",\"<>\",\"paid\"]]\n[[\"keyword_data.keyword_info.search_volume\",\"<>\",0],\n\"and\",\n[[\"ranked_serp_element.serp_item.type\",\"<>\",\"paid\"],\"or\",[\"ranked_serp_element.serp_item.is_malicious\",\"=\",false]]]\nif 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\nexample:\n[\"ranked_serp_element.serp_item.relative_url\", \"=\", \"/apis/rank-tracker-api\"]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to set up a sorting type\nexample:\n[\"keyword_data.keyword_info.competition,desc\"]\ndefault rule:\n[\"ranked_serp_element.serp_item.rank_group,asc\"]\nnote that you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"keyword_data.keyword_info.search_volume,desc\",\"keyword_data.keyword_info.cpc,desc\"]", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "target": "dataforseo.com", "language_name": "English", "location_name": "United States", "load_rank_absolute": true, "limit": 3 } ] }, "DataforseoLabsAppleBulkAppMetricsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAppleBulkAppMetricsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsAppleBulkAppMetricsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAppleBulkAppMetricsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsAppleBulkAppMetricsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsleBulkAppMetricsLiveItem" } ], "nullable": true }, "description": "contains data related to the ranking app metrics of the specified application", "nullable": true } } }, "DataforseoLabsleBulkAppMetricsLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "app_id": { "type": "string", "description": "id of the app in a POST array", "nullable": true }, "metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AppMetricsInfo" }, "description": "metrics for the ranking keywords of the app\nranking data relevant to the keywords that the provided application ranks for on Google Play", "nullable": true } } }, "AppMetricsInfo": { "type": "object", "properties": { "pos_1": { "type": "integer", "description": "number of organic SERPs where the product ranks #1", "nullable": true }, "pos_2_3": { "type": "integer", "description": "number of organic SERPs where the product ranks #2-3", "nullable": true }, "pos_4_10": { "type": "integer", "description": "number of organic SERPs where the product ranks #4-10", "nullable": true }, "pos_11_100": { "type": "integer", "description": "number of organic SERPs where the product ranks #11-100", "nullable": true }, "count": { "type": "integer", "description": "total count of Amazon organic SERPs that contain the product", "format": "int64", "nullable": true }, "search_volume": { "type": "integer", "description": "total search volume of the product\u2019s ranking keywords in organic SERP", "format": "int64", "nullable": true } } }, "DataforseoLabsGoogleHistoricalKeywordDataLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleHistoricalKeywordDataLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleHistoricalKeywordDataLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleHistoricalKeywordDataLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleHistoricalKeywordDataLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleHistoricalKeywordDataLiveItem" } ], "nullable": true }, "description": "contains keywords and related data", "nullable": true } } }, "DataforseoLabsGoogleHistoricalKeywordDataLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword": { "type": "string", "description": "keyword\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "history": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/History" } ], "nullable": true }, "description": "array of objects with historical data for the keyword", "nullable": true } } }, "History": { "type": "object", "properties": { "year": { "type": "integer", "description": "year", "nullable": true }, "month": { "type": "integer", "description": "month", "nullable": true }, "keyword_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordInfo" } ], "description": "historical data for the keyword", "nullable": true } } }, "DataforseoLabsGoogleTopSearchesLiveRequestInfo": { "type": "object", "properties": { "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available locations with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available locations with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "include_serp_info": { "type": "boolean", "description": "include data from SERP for each keyword\noptional field\nif 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\ndefault value: false", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, match, not_match, ilike, not_ilike, like,not_like\nyou 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\nexample:\n[\"keyword_info.search_volume\",\">\",0]\n[[\"keyword_info.search_volume\",\"in\",[0,1000]],\n\"and\",\n[\"keyword_info.competition_level\",\"=\",\"LOW\"]]\n[[\"keyword_info.search_volume\",\">\",100],\n\"and\",\n[[\"keyword_info.cpc\",\"<\",0.5],\n\"or\",\n[\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to set up a sorting type\nexample:\n[\"keyword_info.competition,desc\"]\ndefault rule:\n[\"keyword_info.search_volume,desc\"]\nnote that you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"keyword_info.search_volume,desc\",\"keyword_info.cpc,desc\"]", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned keywords\noptional field\nnote: you can get more than 1000 results by using the offset_token provided in the response to each subsequent request\ndefault value: 1000\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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\nNote: we recommend using this parameter only when retrieving up to 10,000 results\nfor retrieving over 10,000 results, use the offset_token instead.", "nullable": true }, "offset_token": { "type": "string", "description": "offset token for subsequent requests\noptional field\nprovided in the identical filed of the response to each request;\nuse this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;\nby specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;\noffset_token values are unique for each subsequent task\nNote: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.\nlearn more about this parameter on our Help Center", "nullable": true } }, "example": [ { "language_name": "English", "location_code": 2840, "limit": 3 } ] }, "DataforseoLabsGoogleAppCompetitorsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleAppCompetitorsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleAppCompetitorsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleAppCompetitorsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleAppCompetitorsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "app_id": { "type": "string", "description": "id of the app in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsleAppCompetitorsLiveItem" } ], "nullable": true }, "description": "contains data related to the app_id and competitor applications", "nullable": true } } }, "DataforseoLabsleAppCompetitorsLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "app_id": { "type": "string", "description": "id of the competitor app", "nullable": true }, "avg_position": { "type": "number", "description": "average position of the app in Google Play SERP\nNote: average position is calculated for intersected keywords only;\nthe value for a given application may differ when combined with different target applications", "format": "float", "nullable": true }, "sum_position": { "type": "integer", "description": "sum of all app positions in Google Play SERP\nNote: sum position is calculated for intersected keywords only;\nthe value for a given application may differ when combined with different target applications", "nullable": true }, "intersections": { "type": "integer", "description": "number of intersecting keywords", "nullable": true }, "competitor_metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AppMetricsInfo" }, "description": "metrics for intersecting keywords\nranking data relevant to the keywords that the provided competitor application shares with the app in a POST request;\nnote: in this array ranking data is provided for the returned competitor\u2019s app_id", "nullable": true }, "full_metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AppMetricsInfo" }, "description": "metrics for all keywords of the application\nfull overview of ranking data relevant to all keywords that the provided app_id is ranking for", "nullable": true } } }, "DataforseoLabsGoogleDomainMetricsByCategoriesLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleDomainMetricsByCategoriesLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleDomainMetricsByCategoriesLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleDomainMetricsByCategoriesLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleDomainMetricsByCategoriesLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "categories": { "type": "array", "items": { "type": "integer" }, "description": "categories in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleDomainMetricsByCategoriesLiveItem" } ], "nullable": true }, "description": "contains historical ranking and traffic data", "nullable": true } } }, "DataforseoLabsGoogleDomainMetricsByCategoriesLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "top_categories": { "type": "array", "items": { "type": "integer", "nullable": true }, "description": "categories for which domains are collected", "nullable": true }, "organic_etv": { "type": "number", "description": "current organic ETV of the domain", "nullable": true }, "organic_count": { "type": "integer", "description": "current total count of organic SERPs that contain the domain", "format": "int64", "nullable": true }, "organic_is_lost": { "type": "integer", "description": "current number of lost ranked elements\nindicates how many ranked elements of the domain were previously presented in SERPs, but weren\u2019t found during the last check", "nullable": true }, "organic_is_new": { "type": "integer", "description": "current number of new ranked elements\nindicates how many new ranked elements were found for the domain", "nullable": true }, "domain": { "type": "string", "description": "domain found for the specified category", "nullable": true }, "main_domain": { "type": "string", "description": "primary domain", "nullable": true }, "metrics_history": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsMetricsInfo" } ], "nullable": true } }, "description": "historical ranking and traffic data of the domain", "nullable": true }, "metrics_difference": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataforseoLabsMetricsInfo" }, "description": "metrics difference between first_date and second_date\ncalculated by subtracting domain metrics as of the greater date from domain metrics as of the smaller date", "nullable": true } } }, "DataforseoLabsGoogleRelevantPagesLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleRelevantPagesLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleRelevantPagesLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleRelevantPagesLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleRelevantPagesLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "target": { "type": "string", "description": "target domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleRelevantPagesLiveItem" } ], "nullable": true }, "description": "relevant pages and related data", "nullable": true } } }, "DataforseoLabsGoogleRelevantPagesLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "page_address": { "type": "string", "description": "absolute URL of the relevant page", "nullable": true }, "metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataforseoLabsMetricsInfo" }, "description": "rankings and traffic metrics for the relevant page", "nullable": true } } }, "DataforseoLabsGoogleBulkTrafficEstimationLiveRequestInfo": { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "string" }, "description": "target domains, subdomains, and webpages\nrequired field\nyou can specify domains, subdomains, and webpages in this field;\ndomains and subdomains should be specified without https:// and www.;\npages should be specified with absolute URL, including https:// and www.;\nyou can set up to 1000 domains, subdomains or webpages" }, "location_name": { "type": "string", "description": "full name of the location\nif you use this field, you don\u2019t have to specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nif you use this field, you don\u2019t have to specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nif you use this field, you don\u2019t need to specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available languages\nexample:\nen", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string" }, "description": "display results by item type\noptional field\nindicates the type of search results included in the response\nNote: 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\npossible values:\n[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]\ndefault value:\n[\"organic\", \"paid\"]", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true, only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "targets": [ "dataforseo.com", "cnn.com", "forbes.com" ], "location_code": 2840, "language_code": "en", "item_types": [ "organic", "paid" ] } ] }, "DataforseoLabsGoogleKeywordOverviewLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordOverviewLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleKeywordOverviewLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordOverviewLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleKeywordOverviewLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordOverviewLiveItem" } ], "nullable": true }, "description": "contains keywords and related data", "nullable": true } } }, "DataforseoLabsGoogleKeywordOverviewLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword": { "type": "string", "description": "keyword\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "search_partners": { "type": "boolean", "description": "indicates data for Google and partner sites\nif true, the results are returned for owned, operated, and syndicated networks across Google and partner sites that host Google search;\nif false, the results are returned for Google search sites only", "nullable": true }, "keyword_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordInfo" } ], "description": "keyword data for the returned keyword", "nullable": true }, "keyword_info_normalized_with_bing": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordInfoNormalizedWithInfo" } ], "description": "contains keyword search volume normalized with Bing search volume", "nullable": true }, "keyword_info_normalized_with_clickstream": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordInfoNormalizedWithInfo" } ], "description": "contains keyword search volume normalized with clickstream data", "nullable": true }, "clickstream_keyword_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/ClickstreamKeywordInfo" } ], "description": "clickstream data for the returned keyword\nto retrieve results for this field, the parameter include_clickstream_data must be set to true", "nullable": true }, "keyword_properties": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordProperties" } ], "description": "additional information about the keyword", "nullable": true }, "serp_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpInfo" } ], "description": "SERP data\nthe value will be null if you didn\u2019t set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database", "nullable": true }, "avg_backlinks_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AvgBacklinksInfo" } ], "description": "backlink data for the returned keyword\nthis object provides the average number of backlinks, referring pages and domains, as well as the average rank values among the top-10 websites ranking organically for the keyword", "nullable": true }, "search_intent_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SearchIntentInfo" } ], "description": "search intent info for the returned keyword\nlearn about search intent in this help center article", "nullable": true } } }, "DataforseoLabsIdListResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsIdListTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsIdListTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsIdListResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsIdListResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "id of the task", "nullable": true }, "url": { "type": "string", "description": "URL of the task\nURL you used for making an API call", "nullable": true }, "datetime_posted": { "type": "string", "description": "date and time when the task was made\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2023-01-15 12:57:46 +00:00", "nullable": true }, "datetime_done": { "type": "string", "description": "date and time when the task was completed\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2023-01-15 12:57:46 +00:00", "nullable": true }, "status": { "type": "string", "description": "informational message of the task\nyou can find the full list of general informational messages here", "nullable": true }, "cost": { "type": "number", "description": "cost of the task, USD", "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "type": "object", "nullable": true }, "description": "contains parameters you specified in the POST request", "nullable": true } } }, "DataforseoLabsAppleAppCompetitorsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAppleAppCompetitorsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsAppleAppCompetitorsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAppleAppCompetitorsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsAppleAppCompetitorsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "app_id": { "type": "string", "description": "id of the app in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsleAppCompetitorsLiveItem" } ], "nullable": true }, "description": "contains data related to the app_id and competitor applications", "nullable": true } } }, "DataforseoLabsGooglePageIntersectionLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGooglePageIntersectionLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGooglePageIntersectionLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGooglePageIntersectionLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGooglePageIntersectionLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "pages": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "URLs you specified a POST array", "nullable": true }, "exclude_pages": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "URLs you specified in a POST array that will be excluded from the results", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGooglePageIntersectionLiveItem" } ], "nullable": true }, "description": "contains keywords, relevant SERP elements and related data", "nullable": true } } }, "DataforseoLabsGooglePageIntersectionLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "description": "keyword data for the returned keyword", "nullable": true }, "intersection_result": { "type": "object", "additionalProperties": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseDataforseoLabsApiElementItem" } ], "nullable": true }, "description": "contains data on the SERP elements found for the returned keyword\ndata will be provided in separate arrays for each URL you specified in the pages object when setting a task;\ndepending on the number of specified URLs, it can contain from 1 to 20 arrays named respectively", "nullable": true } } }, "BaseDataforseoLabsApiElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "rank_group": { "type": "integer", "description": "position within a group of elements with identical type values\npositions of elements with different type values are omitted from rank_group", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in SERP\ncan take the following values:\nleft, right", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "featured_snippet": "#/components/schemas/DataLabsFeaturedSnippetSerpElementItem", "local_pack": "#/components/schemas/DataLabsLocalPackSerpElementItem", "paid": "#/components/schemas/DataLabsPaidSerpElementItem", "organic": "#/components/schemas/DataLabsOrganicSerpElementItem", "answer_box": "#/components/schemas/DataLabsAnswerBoxSerpElementItem", "carousel": "#/components/schemas/DataLabsCarouselSerpElementItem", "multi_carousel": "#/components/schemas/DataLabsMultiCarouselSerpElementItem", "google_flights": "#/components/schemas/DataLabsGoogleFlightsSerpElementItem", "google_reviews": "#/components/schemas/DataLabsGoogleReviewsSerpElementItem", "google_posts": "#/components/schemas/DataLabsGooglePostsSerpElementItem", "images": "#/components/schemas/DataLabsImagesSerpElementItem", "jobs": "#/components/schemas/DataLabsJobsSerpElementItem", "knowledge_graph": "#/components/schemas/DataLabsKnowledgeGraphSerpElementItem", "hotels_pack": "#/components/schemas/DataLabsHotelsPackSerpElementItem", "map": "#/components/schemas/DataLabsMapSerpElementItem", "people_also_ask": "#/components/schemas/DataLabsPeopleAlsoAskSerpElementItem", "related_searches": "#/components/schemas/DataLabsRelatedSearchesSerpElementItem", "people_also_search": "#/components/schemas/DataLabsPeopleAlsoSearchSerpElementItem", "shopping": "#/components/schemas/DataLabsShoppingSerpElementItem", "top_stories": "#/components/schemas/DataLabsTopStoriesSerpElementItem", "twitter": "#/components/schemas/DataLabsTwitterSerpElementItem", "video": "#/components/schemas/DataLabsVideoSerpElementItem", "events": "#/components/schemas/DataLabsEventsSerpElementItem", "mention_carousel": "#/components/schemas/DataLabsMentionCarouselSerpElementItem", "recipes": "#/components/schemas/DataLabsRecipesSerpElementItem", "top_sights": "#/components/schemas/DataLabsTopSightsSerpElementItem", "scholarly_articles": "#/components/schemas/DataLabsScholarlyArticlesSerpElementItem", "popular_products": "#/components/schemas/DataLabsPopularProductsSerpElementItem", "podcasts": "#/components/schemas/DataLabsPodcastsSerpElementItem", "questions_and_answers": "#/components/schemas/DataLabsQuestionsAndAnswersSerpElementItem", "find_results_on": "#/components/schemas/DataLabsFindResultsOnSerpElementItem", "stocks_box": "#/components/schemas/DataLabsStocksBoxSerpElementItem", "commercial_units": "#/components/schemas/DataLabsCommercialUnitsSerpElementItem", "local_services": "#/components/schemas/DataLabsLocalServicesSerpElementItem", "google_hotels": "#/components/schemas/DataLabsGoogleHotelsSerpElementItem", "math_solver": "#/components/schemas/DataLabsMathSolverSerpElementItem" } } }, "DataforseoLabsGoogleCategoriesForKeywordsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleCategoriesForKeywordsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleCategoriesForKeywordsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleCategoriesForKeywordsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleCategoriesForKeywordsLiveResultInfo": { "type": "object", "properties": { "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleCategoriesForKeywordsLiveItem" } ], "nullable": true }, "description": "contains keywords and related keyword difficulty scores", "nullable": true } } }, "DataforseoLabsGoogleCategoriesForKeywordsLiveItem": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword in a POST array", "nullable": true }, "categories": { "type": "array", "items": { "type": "integer" }, "description": "product and service categories\nyou can download the full list of possible categories", "nullable": true } } }, "DataforseoLabsGoogleHistoricalRankOverviewLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleHistoricalRankOverviewLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleHistoricalRankOverviewLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleHistoricalRankOverviewLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleHistoricalRankOverviewLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "target": { "type": "string", "description": "target domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleHistoricalRankOverviewLiveItem" } ], "nullable": true }, "description": "contains historical ranking and traffic data", "nullable": true } } }, "DataforseoLabsGoogleHistoricalRankOverviewLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "year": { "type": "integer", "description": "year for which the data is provided", "nullable": true }, "month": { "type": "integer", "description": "month for which the data is provided", "nullable": true }, "metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataforseoLabsMetricsInfo" }, "description": "ranking data relevant to the specified domain", "nullable": true } } }, "DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveItem" } ], "nullable": true }, "description": "array of items with relevant traffic estimation data", "nullable": true } } }, "DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "target": { "type": "string", "description": "target domain in a POST array", "nullable": true }, "metrics": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HistoricalMetricsBundleInfo" } ], "description": "traffic data relevant to the specified domain", "nullable": true } } }, "HistoricalMetricsBundleInfo": { "type": "object", "properties": { "organic": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HistoricalMetricsInfo" } ], "nullable": true }, "description": "traffic data from organic search", "nullable": true }, "paid": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HistoricalMetricsInfo" } ], "nullable": true }, "description": "traffic data from paid search", "nullable": true }, "local_pack": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HistoricalMetricsInfo" } ], "nullable": true }, "description": "traffic data from the local pack results in SERP", "nullable": true }, "featured_snippet": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HistoricalMetricsInfo" } ], "nullable": true }, "description": "traffic data from the featured snippet results in Google SERP", "nullable": true } } }, "HistoricalMetricsInfo": { "type": "object", "properties": { "year": { "type": "integer", "description": "year for which the data is provided", "nullable": true }, "month": { "type": "integer", "description": "month for which the data is provided", "nullable": true }, "etv": { "type": "number", "description": "estimated traffic volume\nestimated organic monthly traffic to the domain\ncalculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for\nlearn more about how the metric is calculated in this help center article", "nullable": true }, "count": { "type": "integer", "description": "total count of organic SERPs that contain the domain", "format": "int64", "nullable": true } } }, "DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveRequestInfo": { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "string" }, "description": "target domains and subdomains\nrequired field\nyou can specify domains and subdomains in this field;\ndomains and subdomains should be specified without https:// and www.;\nyou can set up to 1000 domains or subdomains" }, "location_name": { "type": "string", "description": "full name of the location\nif you use this field, you don\u2019t have to specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nif you use this field, you don\u2019t have to specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nif you use this field, you don\u2019t need to specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available languages\nexample:\nen", "nullable": true }, "date_from": { "type": "string", "description": "starting date of the time range\noptional field\nif you don\u2019t specify this field, the data will be provided for the previous 12 months\nminimal possible value: 2020-10-01\ndate format: \"yyyy-mm-dd\"", "nullable": true }, "date_to": { "type": "string", "description": "ending date of the time range\noptional field\nif you don\u2019t specify this field, the today\u2019s date will be used by default;\ndate format: \"yyyy-mm-dd\"\nexample:\n\"2021-04-01\"", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true, only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string" }, "description": "display results by item type\noptional field\nindicates the type of search results included in the response;\nNote: 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;\npossible values:\n[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]\ndefault value:\n[\"organic\", \"paid\"]", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "targets": [ "dataforseo.com", "cnn.com", "forbes.com" ], "location_code": 2840, "language_code": "en", "date_from": "2026-01-15", "date_to": "2026-03-15", "item_types": [ "organic", "paid" ] } ] }, "DataforseoLabsGoogleCompetitorsDomainLiveRequestInfo": { "type": "object", "properties": { "target": { "type": "string", "description": "domain\nrequired field\nthe domain name of the target website\nthe domain should be specified without https:// and www.\nyou can specify page URL, but the results will be specific to the domain in the specified URL" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string" }, "description": "display results by item type\noptional field\nindicates the type of search results included in the response\nNote: 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;\npossible values:\n[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]\ndefault value:\n[\"organic\", \"paid\"]", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_etv, clickstream_gender_distribution, and\u00a0clickstream_age_distribution\u00a0fields with clickstream data in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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\nexample:\n[\"metrics.organic.count\",\">\",50]\n[[[\"metrics.organic.count\",\">=\",50],\"and\",[\"metrics.organic.pos_1\",\"in\",[1,5]]],\n\"or\",\n[\"metrics.organic.etv\",\">=\",\"100\"]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to specify a sorting type\nexample:\n[\"metrics.paid.etv,asc\"]\nNote: you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"metrics.organic.etv,desc\",\"metrics.paid.count,asc\"]\ndefault rule:\n[\"metrics.organic.count,desc\"]\nNote: 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", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned domains\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned domains\noptional field\ndefault value: 0\nif 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", "nullable": true }, "max_rank_group": { "type": "integer", "description": "maximum rank up to which competitors will be considered\noptional field\ndefault value: 100\nif you specify 10 here, we will extract competitors from the top 10 Google search results only", "nullable": true }, "exclude_top_domains": { "type": "boolean", "description": "indicates whether to exclude world\u2019s largest websites\noptional field\ndefault value: false\nset to true if you want to get highly-relevant competitors excluding the websites listed below:\nwikipedia.org\npinterest.com\namazon.com\ngoogle.com\nfacebook.com\nwordpress.com\nmedium.com\nquora.com\nreddit.com\nyoutube.com\nebay.com\nuol.com.br\ninstagram.com\nolx.com\ntwitter.com\nlinkedin.com\nslideshare.net", "nullable": true }, "exclude_domains": { "type": "array", "items": { "type": "string" }, "description": "exclude domains from the results\noptional field\nuse this parameter to exclude specific domains from the results\nNote: you can specify up to 1000 domains in this array\nexample:\n\"exclude_domains\": [\n\"reddit.com\",\n\"youtube.com\"\n]", "nullable": true }, "intersecting_domains": { "type": "array", "items": { "type": "string" }, "description": "additional domains for improving results accuracy\noptional field\nto improve the accuracy of the result, you can specify domains that are known to intersect with the target in SERPs;\nif you use this array, metrics in the result will be based on SERPs where both target website and intersecting_domains appear;\nNote: you can specify up to 20 domains in this array", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true, only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "target": "newmouth.com", "intersecting_domains": [ "dentaly.org", "health.com", "trysnow.com" ], "language_name": "English", "location_code": 2840, "limit": 3 } ] }, "DataforseoLabsGoogleKeywordsForSiteLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordsForSiteLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleKeywordsForSiteLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordsForSiteLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleKeywordsForSiteLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "target": { "type": "string", "description": "target domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total number of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "offset": { "type": "integer", "description": "current offset value", "nullable": true }, "offset_token": { "type": "string", "description": "offset token for subsequent requests\nyou can use the string provided in this field to get the subsequent results of the initial task;\nnote: offset_token values are unique for each subsequent task", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "nullable": true }, "description": "contains keyword ideas and related data", "nullable": true } } }, "DataforseoLabsGoogleKeywordOverviewLiveRequestInfo": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" }, "description": "keywords\nrequired field\nThe maximum number of keywords you can specify: 700\nThe maximum number of characters for each keyword: 80\nThe maximum number of words for each keyword phrase: 10\nthe specified keywords will be converted to lowercase format, data will be provided in a separate array\nnote that if some of the keywords specified in this array are omitted in the results you receive, then our database doesn\u2019t contain such keywords and cannot return data on them\nyou will not be charged for the keywords omitted in the results\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available locations with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available locations with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "include_serp_info": { "type": "boolean", "description": "include data from SERP for each keyword\noptional field\nif 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\ndefault value: false", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "include_clickstream_data": true, "include_serp_info": true, "keywords": [ "iphone" ] } ] }, "DataforseoLabsGoogleSearchIntentLiveRequestInfo": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" }, "description": "target keywords\nrequired field\nUTF-8 encoding\nmaximum number of keywords you can specify in this array: 1000;\nthe keywords will be converted to lowercase format\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if don\u2019t specify language_code\nyou 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\n\nNote: this endpoint currently supports the following languages only:\nArabic, ar,\nChinese(Traditional), zh-TW,\nCzech, cs,\nDanish, da,\nDutch, nl,\nEnglish, en,\nFinnish, fi,\nFrench, fr,\nGerman, de,\nHebrew, he,\nHindi, hi,\nItalian, it,\nJapanese, ja,\nKorean, ko,\nMalay, ms,\nNorwegian(Bokm\u00e5l), nb,\nPolish, pl,\nPortuguese, pt,\nRomanian, ro,\nRussian, ru,\nSpanish, es,\nSwedish, sv,\nThai, th,\nUkrainian, uk,\nVietnamese, vi,\nBulgarian, bg,\nCroatian, hr,\nSerbian, sr,\nSlovenian, sl,\nBosnian, bs,\nGreek, el,\nHungarian, hu,\nSlovak, sk,\nTurkish, tr\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if don\u2019t specify language_name\nyou 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\nNote: this endpoint currently supports these languages only;\nexample:\nen", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "keywords": [ "login page", "audi a7", "elon musk", "milk store new york" ] } ] }, "DataforseoLabsAmazonRelatedKeywordsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonRelatedKeywordsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsAmazonRelatedKeywordsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonRelatedKeywordsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsAmazonRelatedKeywordsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "seed_keyword": { "type": "string", "description": "keyword in a POST array", "nullable": true }, "seed_keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonKeywordData" } ], "description": "keyword data for the seed keyword\nfields in the object are identical to that of keyword_data", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonRelatedKeywordsLiveItem" } ], "nullable": true }, "description": "contains objects with keywords and related data", "nullable": true } } }, "AmazonKeywordData": { "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword": { "type": "string", "description": "related keyword", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "format": "int64", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "keyword_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonKeywordInfo" } ], "description": "keyword info for the returned keyword", "nullable": true } } }, "AmazonKeywordInfo": { "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "last_updated_time": { "type": "string", "description": "date and time when keyword data was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample: '2019-11-15 12:57:46 +00:00'", "nullable": true }, "search_volume": { "type": "integer", "description": "average monthly search volume rate\nrepresents the (approximate) number of searches for the provided keyword idea on Amazon", "format": "int64", "nullable": true } } }, "DataforseoLabsAmazonRelatedKeywordsLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonKeywordData" } ], "description": "keyword data for the returned keyword", "nullable": true }, "depth": { "type": "integer", "description": "keyword search depth", "nullable": true }, "related_keywords": { "type": "array", "items": { "type": "string" }, "description": "list of related keywords\nrepresents the list of search queries which are related to the keyword returned in the array above", "nullable": true } } }, "DataforseoLabsAmazonProductKeywordIntersectionsLiveRequestInfo": { "type": "object", "properties": { "asins": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "asins of target products\nrequired field\nproduct IDs of the products for which you need to find keyword intersections;\nspecify the ASINs as in the following example:\n\"asins\": {\n\"1\": \"019005476X\",\n\"2\": \"0190074442\"\n}\nthe maximum number of ASINs you can specify in this object is 20;\nlearn more about the parameter on this help center page", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if don\u2019t specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if don\u2019t specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if don\u2019t specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if don\u2019t specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of products in the results array\noptional field\ndefault value: 100;\nmaximum value: 1000", "nullable": true }, "intersection_mode": { "type": "string", "description": "mode for finding asin intersections\noptional field\npossible values: union, intersect;\ndefault value: intersect;\nlearn more about the parameter in this help center guide", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, ilike, not_ilike, like, not_like, match, not_match\nyou 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\nexample:\n[\"avg_position\",\"<\", 10]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to set up a sorting parameter\nexample:\n[\"sum_position,desc\"]\nnote that you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"intersections,desc\",\"avg_position,asc\"]\ndefault rule:\n[\"intersections,desc\"]", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "asins": { "1": "B09172433Z", "2": "B07GBZ4Q68", "3": "B07GCKQD77" }, "language_name": "English", "location_code": 2840 } ] }, "DataforseoLabsGoogleSubdomainsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleSubdomainsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleSubdomainsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleSubdomainsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleSubdomainsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "target": { "type": "string", "description": "domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleSubdomainsLiveItem" } ], "nullable": true }, "description": "contains subdomains and related data", "nullable": true } } }, "DataforseoLabsGoogleSubdomainsLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "subdomain": { "type": "string", "description": "returned subdomain", "nullable": true }, "metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataforseoLabsMetricsInfo" }, "description": "ranking data relevant to subdomain", "nullable": true } } }, "DataforseoLabsGoogleBulkAppMetricsLiveRequestInfo": { "type": "object", "properties": { "app_ids": { "type": "array", "items": { "type": "string" }, "description": "ids of the app\nrequired field\nIDs of the mobile applications on Google Play;\nyou can find the ID in the URL of every app listed on Google Play;\nexample:\nin the URL https://play.google.com/store/apps/details?id=org.telegram.messenger\nthe id is org.telegram.messenger;\nthe maximum number of IDs you can specify in this field is 1000" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only;\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only\nexample:\nen", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "app_ids": [ "org.telegram.messenger", "com.zhiliaoapp.musically" ], "language_name": "English", "location_code": 2840 } ] }, "DataforseoLabsGoogleHistoricalSerpsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleHistoricalSerpsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleHistoricalSerpsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleHistoricalSerpsLiveResultInfo" } ], "nullable": true }, "description": "array of results\nthe array includes objects with SERPs for each month within the specified time frame", "nullable": true } } } ] }, "DataforseoLabsGoogleHistoricalSerpsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type in a POST array", "nullable": true }, "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "the total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleHistoricalSerpsLiveItem" } ], "nullable": true }, "description": "additional items present in the element\nif there are none, equals null", "nullable": true } } }, "DataforseoLabsGoogleHistoricalSerpsLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type in a POST array", "nullable": true }, "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SpellInfo" } ], "description": "autocorrection of the search engine\nif the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nanswer_box, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, google_posts, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, visual_stories, commercial_units, local_services, google_hotels, math_solver, ai_overview", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseDataforseoLabsApiElementItem" } ], "nullable": true }, "description": "contains results featured in the \u2018hotels_pack\u2019 element of SERP", "nullable": true } } }, "SpellInfo": { "properties": { "keyword": { "type": "string", "description": "keyword obtained as a result of search engine autocorrection\n the results will be provided for the corrected keyword", "nullable": true }, "type": { "type": "string", "description": "type of autocorrection\n possible values:\n did_you_mean, showing_results_for, no_results_found_for, including_results_for\n note: Yahoo and Yandex support only the following autocorrection type:\n including_results_for", "nullable": true } } }, "DataforseoLabsGoogleAvailableHistoryResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleAvailableHistoryTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleAvailableHistoryTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleAvailableHistoryResultInfo" } ], "nullable": true }, "description": "array of objects containing results", "nullable": true } } } ] }, "DataforseoLabsGoogleAvailableHistoryResultInfo": { "type": "object", "properties": { "date": { "type": "string", "description": "available date\nindicates the date of the range available for setting in the Domain Metrics by Categories endpoint\nexample:\n2022-05-16", "nullable": true } } }, "DataforseoLabsGoogleCategoriesForKeywordsLiveRequestInfo": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" }, "description": "target keywords\nrequired field\nUTF-8 encoding\nmaximum number of keywords you can specify in this array: 1000\nthe keywords will be converted to lowercase format\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if don\u2019t specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/google/categories_for_keywords/languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if don\u2019t specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/google/categories_for_keywords/languages\nexample:\nen", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "keywords": [ "dentist new york", "pizza brooklyn", "car dealer los angeles" ] } ] }, "DataforseoLabsAmazonRankedKeywordsLiveRequestInfo": { "type": "object", "properties": { "asin": { "type": "string", "description": "product ID\nrequired field\nunique product identifier (ASIN) on Amazon;\nyou can receive the asin parameter by making a separate request to the Amazon Products endpoint" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if don\u2019t specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if don\u2019t specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if don\u2019t specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if don\u2019t specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of products in the results array\noptional field\ndefault value: 100;\nmaximum value: 1000", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, match, not_match\nyou can use the % operator with like and not_like to match any string of zero or more characters\nexample:\n[\"keyword_data.keyword_info.search_volume\",\"in\",[100,1000]];\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to set up a sorting parameter\nexample:\n[\"keyword_data.keyword_info.competition,desc\"]\ndefault rule:\n[\"ranked_serp_element.serp_item.rank_group,asc\"]\nnote that you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"keyword_data.keyword_info.search_volume,desc\",\"keyword_data.keyword_info.cpc,desc\"]", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "asin": "B00R92CL5E", "location_code": 2840, "language_code": "en" } ] }, "DataforseoLabsGoogleSearchIntentLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleSearchIntentLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleSearchIntentLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleSearchIntentLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleSearchIntentLiveResultInfo": { "type": "object", "properties": { "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleSearchIntentLiveItem" } ], "nullable": true }, "description": "array of items with relevant traffic estimation data", "nullable": true } } }, "DataforseoLabsGoogleSearchIntentLiveItem": { "type": "object", "properties": { "keyword": { "type": "string", "description": "target keyword in a POST array", "nullable": true }, "keyword_intent": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordIntentInfo" } ], "description": "search intent data relevant for the specified keyword", "nullable": true }, "secondary_keyword_intents": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordIntentInfo" } ], "nullable": true }, "description": "contains objects with other possible search intents for the specified keyword", "nullable": true } } }, "KeywordIntentInfo": { "type": "object", "properties": { "label": { "type": "string", "description": "search intent name\npossible values: informational, navigational, commercial, transactional", "nullable": true }, "probability": { "type": "number", "description": "search intent probability\n1 indicates the highest probability", "nullable": true } } }, "DataforseoLabsGoogleDomainIntersectionLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleDomainIntersectionLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleDomainIntersectionLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleDomainIntersectionLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleDomainIntersectionLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "target1": { "type": "string", "description": "the first target domain in a POST array", "nullable": true }, "target2": { "type": "string", "description": "the second target domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleDomainIntersectionLiveItem" } ], "nullable": true }, "description": "contains keywords, relevant SERP elements and related data", "nullable": true } } }, "DataforseoLabsGoogleDomainIntersectionLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "description": "keyword data for the returned keyword", "nullable": true }, "first_domain_serp_element": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseDataforseoLabsApiElementItem" } ], "description": "contains data on the first domain\u2019s SERP element found for the returned keyword\nthe list of supported SERP elements can be found below", "nullable": true }, "second_domain_serp_element": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseDataforseoLabsApiElementItem" } ], "description": "contains data on the second domain\u2019s SERP element found for the returned keyword\nthe list of supported SERP elements can be found below", "nullable": true } } }, "DataforseoLabsGoogleKeywordsForAppLiveRequestInfo": { "type": "object", "properties": { "app_id": { "type": "string", "description": "id of the apps\nrequired field\nID of the mobile application on Google Play;\nyou can find the ID in the URL of every app listed on Google Play;\nexample:\nin the URL https://play.google.com/store/apps/details?id=org.telegram.messenger\nthe id is org.telegram.messenger" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only;\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only\nexample:\nen", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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:\n<, <=, >, >=, =, <>, in, not_in\nexample:\n[\"keyword_data.keyword_info.search_volume\",\">\",500]\n[[\"keyword_data.keyword_info.search_volume\",\"<>\",500],\"and\",[\"ranked_serp_element.serp_item.rank_group\",\">=\",\"10\"]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results;\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order;\ndesc \u2013 results will be sorted in the descending order;\nyou should use a comma to specify a sorting type;\nexample:\n[\"ranked_serp_element.serp_item.rank_group,asc\"]\nNote: you can set no more than three sorting rules in a single request;\nyou should use a comma to separate several sorting rules;\nexample:\n[\"ranked_serp_element.serp_item.rank_group,desc\",\"keyword_data.keyword_info.search_volume,asc\"]\ndefault rule:\n[\"keyword_data.keyword_info.search_volume,desc\"]\nNote: 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", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned keywords\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "app_id": "org.telegram.messenger", "language_name": "English", "location_code": 2840, "limit": 10 } ] }, "DataforseoLabsAmazonProductCompetitorsLiveRequestInfo": { "type": "object", "properties": { "asin": { "type": "string", "description": "product ID\nrequired field\nunique product identifier (ASIN) on Amazon;\nyou can receive the asin parameter by making a separate request to the Amazon Products endpoint" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if don\u2019t specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if don\u2019t specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if don\u2019t specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if don\u2019t specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of products in the results array\noptional field\ndefault value: 100;\nmaximum value: 1000", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, ilike, not_ilike, like, not_like, match, not_match\nyou 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\nexample:\n[\"full_metrics.amazon_serp.pos_1\",\">\", 20]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to set up a sorting parameter\nexample:\n[\"full_metrics.amazon_serp.pos_1,desc\"]\nnote that you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"full_metrics.amazon_serp.pos_1,desc\",\"avg_position,desc\"]\ndefault rule:\n[\"ranked_serp_element.serp_item.rank_group,asc\"]", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned product competitors\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "asin": "019005476X", "location_code": 2840, "language_code": "en" } ] }, "DataforseoLabsGoogleBulkAppMetricsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleBulkAppMetricsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleBulkAppMetricsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleBulkAppMetricsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleBulkAppMetricsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsleBulkAppMetricsLiveItem" } ], "nullable": true }, "description": "contains data related to the ranking app metrics of the specified application", "nullable": true } } }, "DataforseoLabsGoogleKeywordsForCategoriesLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordsForCategoriesLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleKeywordsForCategoriesLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordsForCategoriesLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleKeywordsForCategoriesLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "seed_categories": { "type": "array", "items": { "type": "integer", "nullable": true }, "description": "categories in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "the total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "offset": { "type": "integer", "description": "current offset value", "nullable": true }, "offset_token": { "type": "string", "description": "offset token for subsequent requests\nyou can use the string provided in this field to get the subsequent results of the initial task;\nnote: offset_token values are unique for each subsequent task", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "nullable": true }, "description": "contains keyword ideas and related data", "nullable": true } } }, "DataforseoLabsGoogleKeywordsForSiteLiveRequestInfo": { "type": "object", "properties": { "target": { "type": "string", "description": "target domain\nrequired field\nthe domain name of the target website\nthe domain should be specified without https://" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "unique location identifier\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\noptional field\nif you use this field, you don\u2019t need to specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish\nNote: if omitted, results default to the language with the most keyword records in the specified location;\nrefer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language", "nullable": true }, "language_code": { "type": "string", "description": "language code\noptional field\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen\nNote: if omitted, results default to the language with the most keyword records in the specified location;\nrefer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language", "nullable": true }, "include_serp_info": { "type": "boolean", "description": "include data from SERP for each keyword\noptional field\nif 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\ndefault value: false", "nullable": true }, "include_subdomains": { "type": "boolean", "description": "indicates if the subdomains will be included in the search\noptional field\nif set to false, the subdomains will be ignored\ndefault value: true", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of keywords in the results array\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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\nNote: we recommend using this parameter only when retrieving up to 10,000 results\nfor retrieving over 10,000 results, use the offset_token instead.", "nullable": true }, "offset_token": { "type": "string", "description": "offset token for subsequent requests\noptional field\nprovided in the identical filed of the response to each request;\nuse this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;\nby specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;\noffset_token values are unique for each subsequent task\nNote: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.\nlearn more about this parameter on our Help Center", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, match, not_match, ilike, not_ilike, like, not_like\nyou 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\nnote that you can not filter the results by relevance\nexample:\n[\"keyword_info.search_volume\",\">\",0]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to set up a sorting parameter\ndefault rule:\n[\"relevance,desc\"]\nrelevance 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\nyou should use a comma to separate several sorting rules\nexample:\n[\"relevance,desc\",\"keyword_info.search_volume,desc\"]", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "target": "apple.com", "language_code": "en", "location_code": 2840, "include_serp_info": true, "include_subdomains": true, "filters": [ "serp_info.se_results_count", ">", 0 ], "limit": 3 } ] }, "DataforseoLabsGoogleKeywordSuggestionsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordSuggestionsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleKeywordSuggestionsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordSuggestionsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleKeywordSuggestionsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "seed_keyword": { "type": "string", "description": "keyword in a POST array", "nullable": true }, "seed_keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "description": "keyword data for the seed keyword\nfields in this object are identical to those of the items array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "offset": { "type": "integer", "description": "current offset value", "nullable": true }, "offset_token": { "type": "string", "description": "offset token for subsequent requests\nyou can use the string provided in this field to get the subsequent results of the initial task;\nnote: offset_token values are unique for each subsequent task", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "nullable": true }, "description": "contains keywords and related data", "nullable": true } } }, "DataforseoLabsGoogleAppIntersectionLiveRequestInfo": { "type": "object", "properties": { "app_ids": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "ids of the target apps\nrequired field\nIDs of the target mobile applications on Google Play;\nyou can find the ID in the URL of every app listed on Google Play;\nexample:\nin the URL https://play.google.com/store/apps/details?id=org.telegram.messenger\nthe id is org.telegram.messenger;;\nthe ids should be specified the following way:\n\"app_ids\": {\n\"1\": \"org.telegram.messenger\",\n\"2\": \"com.zhiliaoapp.musically\"\n}\nif you specify a single ID here, the API will return results only for one application;\nthe maximum number of app IDs you can specify in this object is 20", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only;\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only\nexample:\nen", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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:\n<, <=, >, >=, =, <>, in, not_in\nexample:\n[\"keyword_data.keyword_info.search_volume\",\">\",500]\n[[\"keyword_data.keyword_info.search_volume\",\"<>\",500],\"and\",[intersection_result.382617920.rank_group\",\">=\",\"10\"]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results;\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order;\ndesc \u2013 results will be sorted in the descending order;\nyou should use a comma to specify a sorting type;\nexample:\n[\"intersection_result.382617920.rank_absolute,asc\"]\nNote: you can set no more than three sorting rules in a single request;\nyou should use a comma to separate several sorting rules;\nexample:\n[\"intersection_result.382617920.rank_absolute,desc\",\"keyword_data.keyword_info.search_volume,asc\"]\ndefault rule:\n[\"keyword_data.keyword_info.search_volume,desc\"]\nNote: 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", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned keywords\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "app_ids": { "1": "org.telegram.messenger", "2": "com.zhiliaoapp.musically" }, "language_name": "English", "location_code": 2840, "limit": 10 } ] }, "DataforseoLabsAppleKeywordsForAppLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAppleKeywordsForAppLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsAppleKeywordsForAppLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAppleKeywordsForAppLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsAppleKeywordsForAppLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "app_id": { "type": "string", "description": "id of the app in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAppleKeywordsForAppLiveItem" } ], "nullable": true }, "description": "contains data related to the ranking keywords for the app specified in the app_id field", "nullable": true } } }, "DataforseoLabsAppleKeywordsForAppLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "description": "keyword data for the returned keyword", "nullable": true }, "ranked_serp_element": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AppleRankedSerpElementInfo" } ], "description": "contains data on the domain\u2019s SERP element found for the returned keyword", "nullable": true } } }, "AppleRankedSerpElementInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "serp_item": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AppStoreSearchOrganic" } ], "description": "contains data on the SERP element\nthe list of supported SERP elements can be found below", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "se_results_count": { "type": "integer", "description": "number of search results for the returned keyword", "nullable": true }, "last_updated_time": { "type": "string", "description": "date and time when SERP data was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "previous_updated_time": { "type": "string", "description": "previous to the most recent date and time when SERP data was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-10-15 12:57:46 +00:00;\nin this case, will equal null", "nullable": true } } }, "AppStoreSearchOrganic": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "description": "position within a group of elements with identical type values\npositions of elements with different type values are omitted from rank_group", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in SERP\ncan take the following values:\nleft, right", "nullable": true }, "app_id": { "type": "string", "description": "id of the app", "nullable": true }, "title": { "type": "string", "description": "title of the app", "nullable": true }, "url": { "type": "string", "description": "URL to the app page on App Store", "nullable": true }, "icon": { "type": "string", "description": "URL to the app icon", "nullable": true }, "reviews_count": { "type": "integer", "description": "the total number of reviews of the app", "format": "int64", "nullable": true }, "rating": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RatingInfo" } ], "description": "average rating of the app", "nullable": true }, "is_free": { "type": "boolean", "description": "indicates whether the app is free", "nullable": true }, "price": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/PriceInfo" } ], "description": "price of the app", "nullable": true } } }, "RatingInfo": { "properties": { "rating_type": { "type": "string", "description": "the type of rating\nhere you can find the following elements: Max5, Percents, CustomMax", "nullable": true }, "value": { "type": "number", "description": "the value of the rating", "format": "double", "nullable": true }, "votes_count": { "type": "integer", "description": "the amount of feedback", "format": "int64", "nullable": true }, "rating_max": { "type": "integer", "description": "the maximum value for a rating_type", "nullable": true } } }, "PriceInfo": { "type": "object", "properties": { "current": { "type": "number", "description": "current price\nindicates the current price of the product or service featured in the result", "format": "double", "nullable": true }, "regular": { "type": "number", "description": "regular price\nindicates the regular price of the product or service with no discounts applied", "format": "double", "nullable": true }, "max_value": { "type": "number", "description": "the maximum price\nthe maximum price of the product or service as indicated in the result", "format": "double", "nullable": true }, "currency": { "type": "string", "description": "currency of the listed price\nISO code of the currency applied to the price", "nullable": true }, "is_price_range": { "type": "boolean", "description": "price is provided as a range\nindicates whether a price is provided in a range", "nullable": true }, "displayed_price": { "type": "string", "description": "price string in the result\nraw price string as provided in the result", "nullable": true } } }, "DataforseoLabsGoogleBulkTrafficEstimationLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleBulkTrafficEstimationLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleBulkTrafficEstimationLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleBulkTrafficEstimationLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleBulkTrafficEstimationLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleBulkTrafficEstimationLiveItem" } ], "nullable": true }, "description": "array of items with relevant traffic estimation data", "nullable": true } } }, "DataforseoLabsGoogleBulkTrafficEstimationLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "target": { "type": "string", "description": "target domain in a POST array", "nullable": true }, "metrics": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BulkMetricsBundleInfo" } ], "description": "traffic data relevant to the specified domain", "nullable": true } } }, "BulkMetricsBundleInfo": { "type": "object", "properties": { "organic": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BulkMetricsInfo" } ], "description": "traffic data from organic search", "nullable": true }, "paid": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BulkMetricsInfo" } ], "description": "traffic data from paid search", "nullable": true }, "local_pack": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BulkMetricsInfo" } ], "description": "traffic data from the local pack results in SERP", "nullable": true }, "featured_snippet": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BulkMetricsInfo" } ], "description": "traffic data from the featured snippet results in Google SERP", "nullable": true } } }, "BulkMetricsInfo": { "type": "object", "properties": { "etv": { "type": "number", "description": "estimated traffic volume\nestimated organic monthly traffic to the domain\ncalculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for\nlearn more about how the metric is calculated in this help center article", "nullable": true }, "count": { "type": "integer", "description": "total count of organic SERPs that contain the domain", "format": "int64", "nullable": true } } }, "DataforseoLabsGoogleSerpCompetitorsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleSerpCompetitorsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleSerpCompetitorsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleSerpCompetitorsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleSerpCompetitorsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "seed_keywords": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "keywords specified in the request\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "total_count": { "type": "integer", "description": "the total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleSerpCompetitorsLiveItem" } ], "nullable": true }, "description": "contains detected SERP competitors and related data", "nullable": true } } }, "DataforseoLabsGoogleSerpCompetitorsLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "domain": { "type": "string", "description": "domain name of the detected SERP competitor", "nullable": true }, "avg_position": { "type": "number", "description": "the average position of the domain for the specified keywords\nthe arithmetic mean of values in the keywords_positions array", "format": "float", "nullable": true }, "median_position": { "type": "number", "description": "the median position of the domain for the specified keywords\nthe median of the values in the keywords_positions array", "nullable": true }, "rating": { "type": "number", "description": "the margin between the greatest possible and actual keyword positions\nrepresents the relative visibility rate of the domain in SERP for the specified keywords\ncalculated as sum(100-keywords_positions)", "nullable": true }, "etv": { "type": "number", "description": "estimated traffic volume\nrepresents the estimated monthly traffic that specified keywords are driving to the website\ncalculated as the sum of the products of the specified keywords\u2019 search volume values and CTR (click-through-rate) rates at certain positions in SERP\nlearn more about how the metric is calculated in this help center article", "nullable": true }, "keywords_count": { "type": "integer", "description": "the number of specified keywords the domain has positions for in SERPs", "format": "int64", "nullable": true }, "visibility": { "type": "number", "description": "SERP visibility rate\nrepresents the website visibility rate based on the SERP positions of the specified keywords\nKeywords with positions in the range from 1 to 10 are assigned the visibility index from 1 to 0.1, respectively\nKeywords with positions in the range from 11 to 20 have the fixed visibility index of 0.05\nkeywords with positions from 20 to 100 have the visibility index equal to 0", "nullable": true }, "relevant_serp_items": { "type": "integer", "description": "the number of SERP elements relevant to the domain\nrepresents the number of search results in SERP relevant to the domain for the specified keywords", "nullable": true }, "keywords_positions": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "integer", "nullable": true }, "nullable": true }, "description": "keyword positions\nSERP positions the related domain holds in SERP for the specified keywords", "nullable": true } } }, "DataforseoLabsErrorsRequestInfo": { "type": "object", "properties": { "limit": { "type": "integer", "description": "the maximum number of returned tasks that responded with an error\noptional field\ndefault value: 1000\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned tasks\noptional field\ndefault value: 0\nif you specify the 10 value, the first ten tasks in the results array will be omitted and the data will be provided for the successive tasks", "nullable": true }, "filtered_function": { "type": "string", "description": "return tasks with a certain function\nuse this field to obtain a list of tasks that returned an error filtered by a certain function\nyou can filter the results by the values you receive in the function fields of the API response\ni.e., once you receive unfiltered results, you can call this API again to filter them by function\nexample: dataforseo_labs/related_keywords/live", "nullable": true }, "datetime_from": { "type": "string", "description": "start time for filtering results\noptional field\nallows filtering results by the datetime parameter within the range of the last 7 days;\nmust be specified in the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2021-11-15 12:57:46 +00:00", "nullable": true }, "datetime_to": { "type": "string", "description": "finish time for filtering results\noptional field\nallows filtering results by the datetime parameter within the range of the last 7 days;\nmust be specified in the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2021-11-15 13:57:46 +00:00", "nullable": true } }, "example": [ { "limit": 10, "offset": 0 } ] }, "DataforseoLabsErrorsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsErrorsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsErrorsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsErrorsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsErrorsResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "id of the task", "nullable": true }, "datetime": { "type": "string", "description": "date and time when an error occurred\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "function": { "type": "string", "description": "corresponding API function", "nullable": true }, "error_code": { "type": "integer", "description": "error code", "nullable": true }, "error_message": { "type": "string", "description": "error message or error URL\nerror message (see full list) or URL that caused an error", "nullable": true }, "http_url": { "type": "string", "description": "URL that caused an error\nURL you used for making an API call", "nullable": true }, "http_method": { "type": "string", "description": "HTTP method", "nullable": true }, "http_code": { "type": "integer", "description": "HTTP status code", "nullable": true }, "http_time": { "type": "number", "description": "time taken by HTTP request", "nullable": true }, "http_response": { "type": "string", "description": "HTTP response\nserver response", "nullable": true } } }, "DataforseoLabsGoogleKeywordsForAppLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordsForAppLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleKeywordsForAppLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordsForAppLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleKeywordsForAppLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "app_id": { "type": "string", "description": "id of the app in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleKeywordsForAppLiveItem" } ], "nullable": true }, "description": "contains data related to the ranking keywords for the app specified in the app_id field", "nullable": true } } }, "DataforseoLabsGoogleKeywordsForAppLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "description": "keyword data for the returned keyword", "nullable": true }, "ranked_serp_element": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GooglePlayRankedSerpElementInfo" } ], "description": "contains data on the domain\u2019s SERP element found for the returned keyword", "nullable": true } } }, "GooglePlayRankedSerpElementInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "serp_item": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GooglePlaySearchOrganic" } ], "description": "contains data on the SERP element\nthe list of supported SERP elements can be found below", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "se_results_count": { "type": "integer", "description": "number of search results for the returned keyword", "nullable": true }, "last_updated_time": { "type": "string", "description": "date and time when SERP data was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "previous_updated_time": { "type": "string", "description": "previous to the most recent date and time when SERP data was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-10-15 12:57:46 +00:00;\nin this case, will equal null", "nullable": true } } }, "GooglePlaySearchOrganic": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "description": "position within a group of elements with identical type values\npositions of elements with different type values are omitted from rank_group", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in SERP\ncan take the following values:\nleft, right", "nullable": true }, "app_id": { "type": "string", "description": "id of the app", "nullable": true }, "title": { "type": "string", "description": "title of the app", "nullable": true }, "url": { "type": "string", "description": "URL to the app page on Google Play", "nullable": true }, "icon": { "type": "string", "description": "URL to the app icon", "nullable": true }, "reviews_count": { "type": "integer", "description": "the total number of reviews of the app", "format": "int64", "nullable": true }, "rating": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RatingInfo" } ], "description": "average rating of the app", "nullable": true }, "is_free": { "type": "boolean", "description": "indicates whether the app is free", "nullable": true }, "price": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/PriceInfo" } ], "description": "price of the app", "nullable": true }, "developer": { "type": "string", "description": "name of the app developer", "nullable": true }, "developer_url": { "type": "string", "description": "URL to the developer page on Google Play", "nullable": true } } }, "DataforseoLabsGoogleRelatedKeywordsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleRelatedKeywordsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleRelatedKeywordsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleRelatedKeywordsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleRelatedKeywordsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "seed_keyword": { "type": "string", "description": "keyword in a POST array", "nullable": true }, "seed_keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "description": "keyword data for the seed keyword\nfields in the array are identical to that of keyword_data", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleRelatedKeywordsLiveItem" } ], "nullable": true }, "description": "contains keywords and related data", "nullable": true } } }, "DataforseoLabsGoogleRelatedKeywordsLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type\npossible values: google", "nullable": true }, "keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "properties": { "avg_backlinks_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AvgBacklinksInfo" } ], "nullable": true }, "search_intent_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SearchIntentInfo" } ], "nullable": true } }, "description": "keyword data for the returned keyword", "nullable": true }, "depth": { "type": "integer", "description": "keyword search depth", "nullable": true }, "related_keywords": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "list of related keywords\nrepresents the list of search queries which are related to the keyword returned in the array above", "nullable": true } } }, "DataforseoLabsAppleAppCompetitorsLiveRequestInfo": { "type": "object", "properties": { "app_id": { "type": "string", "description": "id of the app\nrequired field\nID of the mobile application on App Store;\nyou can find the ID in the URL of every app listed on App Store;\nexample:\nin the URL https://apps.apple.com/us/app/id835599320\nthe id is 835599320" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only;\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only\nexample:\nen", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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:\n<, <=, >, >=, =, <>, in, not_in\nexample:\n[\"intersections\",\">\",500]\n[[\"competitor_metrics.app_store_search_organic.pos_1\",\"<>\",10],\"and\",[\"avg_position\",\">=\",\"10\"]]\n[[[\"intersections\",\">=\",50],\"and\",[\"competitor_metrics.app_store_search_organic.pos_1\",\"in\",[1,5]]],\n\"or\",\n[\"sum_position\",\">=\",\"10000\"]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results;\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order;\ndesc \u2013 results will be sorted in the descending order;\nyou should use a comma to specify a sorting type;\nexample:\n[\"intersections,asc\"]\nNote: you can set no more than three sorting rules in a single request;\nyou should use a comma to separate several sorting rules;\nexample:\n[\"intersections,desc\",\"sum_position,asc\"]\ndefault rule:\n[\"intersections,desc\"]\nNote: 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", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned apps\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned apps\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "app_id": "686449807", "language_name": "English", "location_code": 2840, "limit": 10 } ] }, "DataforseoLabsAppleAppIntersectionLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAppleAppIntersectionLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsAppleAppIntersectionLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAppleAppIntersectionLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsAppleAppIntersectionLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "app_ids": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "ids of the apps in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsleAppIntersectionLiveItem" } ], "nullable": true }, "description": "contains data related to the ranking keywords for the app specified in the app_id field", "nullable": true } } }, "DataforseoLabsleAppIntersectionLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "description": "keyword data for the returned keyword", "nullable": true }, "intersection_result": { "type": "object", "additionalProperties": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GooglePlaySearchOrganic" } ], "nullable": true }, "description": "contains SERP data for the returned keyword\ndata will be provided in separate arrays for each app ID you specified in the app_ids object when setting a task;\ndepending on the number of specified app IDs, it can contain from 1 to 20 arrays named respectively", "nullable": true } } }, "DataforseoLabsGoogleCompetitorsDomainLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleCompetitorsDomainLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleCompetitorsDomainLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleCompetitorsDomainLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleCompetitorsDomainLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "target": { "type": "string", "description": "target domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleCompetitorsDomainLiveItem" } ], "nullable": true }, "description": "contains data related to the target and competitor domains", "nullable": true } } }, "DataforseoLabsGoogleCompetitorsDomainLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "domain": { "type": "string", "description": "domain name", "nullable": true }, "avg_position": { "type": "number", "description": "average position of the domain in SERP\nNote: average position is calculated for intersected keywords only;\nthe value for a given domain may differ when combined with different target websites", "format": "float", "nullable": true }, "sum_position": { "type": "integer", "description": "sum of all domain positions in SERP\nNote: average position is calculated for intersected keywords only;\nthe value for a given domain may differ when combined with different target websites", "nullable": true }, "intersections": { "type": "integer", "description": "number of intersecting keywords", "nullable": true }, "full_domain_metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataforseoLabsMetricsInfo" }, "description": "metrics for all keywords of the domain\nfull overview of ranking and traffic data relevant to all keywords that the provided domain is ranking for", "nullable": true }, "metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataforseoLabsMetricsInfo" }, "description": "metrics for intersecting keywords\nranking and traffic data relevant to the keywords that the provided domain shares with the target domain\nnote: in this array ranking and traffic data is provided for the target considering the keywords target shares in search with the competitor\u2019s domain", "nullable": true }, "competitor_metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataforseoLabsMetricsInfo" }, "description": "metrics for intersecting keywords\nranking and traffic data relevant to the keywords that the provided domain shares with the target domain\nnote: in this array ranking and traffic data is provided for the returned competitor\u2019s domain", "nullable": true } } }, "DataforseoLabsGoogleBulkKeywordDifficultyLiveRequestInfo": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" }, "description": "target keywords\nrequired field\nUTF-8 encoding\nmaximum number of keywords you can specify in this array: 1000\nthe keywords will be converted to lowercase format\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if don\u2019t specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if don\u2019t specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if don\u2019t specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if don\u2019t specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "location_code": 2840, "language_code": "en", "keywords": [ "dentist new york", "pizza brooklyn", "car dealer los angeles" ] } ] }, "DataforseoLabsGoogleKeywordIdeasLiveRequestInfo": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" }, "description": "keywords\nrequired field\nUTF-8 encoding\nThe maximum number of keywords you can specify: 200.\nThe keywords will be converted to lowercase format\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "unique location identifier\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\noptional field\nif you use this field, you don\u2019t need to specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish\nNote: if omitted, results default to the language with the most keyword records in the specified location;\nrefer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language", "nullable": true }, "language_code": { "type": "string", "description": "language code\noptional field\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen\nNote: if omitted, results default to the language with the most keyword records in the specified location;\nrefer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language", "nullable": true }, "closely_variants": { "type": "boolean", "description": "search mode\noptional field\nif set to\u00a0true the results will be based on the phrase-match search algorithm\nif set to false the results will be based on the broad-match search algorithm\ndefault value: false", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "include_serp_info": { "type": "boolean", "description": "include data from SERP for each keyword\noptional field\nif 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\ndefault value: false", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of keywords in the results array\noptional field\ndefault value: 700\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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\nNote: we recommend using this parameter only when retrieving up to 10,000 results\nfor retrieving over 10,000 results, use the offset_token instead.", "nullable": true }, "offset_token": { "type": "string", "description": "offset token for subsequent requests\noptional field\nprovided in the identical filed of the response to each request;\nuse this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;\nby specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;\noffset_token values are unique for each subsequent task\nNote: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.\nlearn more about this parameter on our Help Center", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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, match, not_match, ilike, not_ilike, like, not_like\nyou can use the % operator with like and not_like,as well as ilike, not_ilike to match any string of zero or more characters\nnote that you can not filter the results by relevance\nexample:\n[\"keyword_info.search_volume\",\">\",0]\n[[\"keyword_info.search_volume\",\"in\",[0,1000]],\n\"and\",\n[\"keyword_info.competition_level\",\"=\",\"LOW\"]]\n[[\"keyword_info.search_volume\",\">\",100],\n\"and\",\n[[\"keyword_info.cpc\",\"<\",0.5],\n\"or\",\n[\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to set up a sorting parameter\ndefault rule:\n[\"relevance,desc\"]\nrelevance 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.\nnote that you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"relevance,desc\",\"keyword_info.search_volume,desc\"]", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "keywords": [ "phone", "watch" ], "location_code": 2840, "language_code": "en", "include_serp_info": true, "limit": 3 } ] }, "DataforseoLabsAppleAppIntersectionLiveRequestInfo": { "type": "object", "properties": { "app_ids": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "ids of the target apps\nrequired field\nIDs of the target mobile applications on App Store;\nyou can find the ID in the URL of every app listed on App Store;\nexample:\nin the URL https://apps.apple.com/us/app/id835599320\nthe id is 835599320;\nthe ids should be specified the following way:\n\"app_ids\": {\n\"1\": \"686449807\",\n\"2\": \"382617920\"\n}\nif you specify a single ID here, the API will return results only for one application;\nthe maximum number of app IDs you can specify in this object is 20", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only;\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only\nexample:\nen", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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:\n<, <=, >, >=, =, <>, in, not_in\nexample:\n[\"keyword_data.keyword_info.search_volume\",\">\",500]\n[[\"keyword_data.keyword_info.search_volume\",\"<>\",500],\"and\",[intersection_result.382617920.rank_group\",\">=\",\"10\"]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results;\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order;\ndesc \u2013 results will be sorted in the descending order;\nyou should use a comma to specify a sorting type;\nexample:\n[\"intersection_result.382617920.rank_absolute,asc\"]\nNote: you can set no more than three sorting rules in a single request;\nyou should use a comma to separate several sorting rules;\nexample:\n[\"intersection_result.382617920.rank_absolute,desc\",\"keyword_data.keyword_info.search_volume,asc\"]\ndefault rule:\n[\"keyword_data.keyword_info.search_volume,desc\"]\nNote: 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", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned keywords\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "app_ids": { "1": "686449807", "2": "382617920" }, "language_name": "English", "location_code": 2840, "limit": 10 } ] }, "DataforseoLabsGoogleTopSearchesLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleTopSearchesLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleTopSearchesLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleTopSearchesLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleTopSearchesLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "offset": { "type": "integer", "description": "current offset value", "nullable": true }, "offset_token": { "type": "string", "description": "offset token for subsequent requests\nyou can use the string provided in this field to get the subsequent results of the initial task;\nnote: offset_token values are unique for each subsequent task", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "nullable": true }, "description": "contains keywords and related data", "nullable": true } } }, "DataforseoLabsGoogleRelevantPagesLiveRequestInfo": { "type": "object", "properties": { "target": { "type": "string", "description": "domain\nrequired field\nthe domain name of the target website\nthe domain should be specified without https:// and www." }, "location_name": { "type": "string", "description": "full name of the location\noptional field\nif you use this field, you don\u2019t need to specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\noptional field\nif you use this field, you don\u2019t need to specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\noptional field\nif you use this field, you don\u2019t need to specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\noptional field\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available languages\nexample:\nen", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string" }, "description": "display results by item type\noptional field\nindicates the type of search results included in the response\nNote: 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;\npossible values:\n[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]\ndefault value:\n[\"organic\", \"paid\"]", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_etv, clickstream_gender_distribution, and\u00a0clickstream_age_distribution\u00a0fields with clickstream data in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned pages\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned pages\noptional field\ndefault value: 0\nif 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", "nullable": true }, "historical_serp_mode": { "type": "string", "description": "data collection mode\noptional field\nyou can use this field to filter the results;\npossible types of filtering:\nlive \u2014 return metrics for SERPs in which the specified target currently has ranking results;\nlost \u2014 return metrics for SERPs in which the specified target had previously had ranking results, but didn\u2019t have them during the last check;\nall \u2014 return metrics for both types of SERPs.\ndefault value: live", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true, only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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\nexample:\n[\"metrics.paid.count\",\">\",0]\n[[\"metrics.organic.count\",\">\",50],\"and\",[\"metrics.organic.pos_1\",\"<>\",0]]\n[[\"\"metrics.organic.count\",\">\",50\"],\n\"and\",\n[[\"metrics.organic.pos_1\",\"<>\",0],\"or\",[\"metrics.organic.pos_2_3\",\"<>\",0]]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to specify a sorting type\nexample:\n[\"metrics.paid.etv,asc\"]\nNote: you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"metrics.organic.etv,desc\",\"metrics.paid.count,asc\"]\ndefault rule:\n[\"metrics.organic.count,desc\"]\nNote: 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "target": "amazon.com", "language_name": "English", "location_code": 2840, "filters": [ [ "metrics.organic.pos_1", "<>", 0 ], "or", [ "metrics.organic.pos_2_3", "<>", 0 ] ], "limit": 3 } ] }, "DataforseoLabsGoogleAppIntersectionLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleAppIntersectionLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleAppIntersectionLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleAppIntersectionLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleAppIntersectionLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "app_ids": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "ids of the apps in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsleAppIntersectionLiveItem" } ], "nullable": true }, "description": "contains data related to the ranking keywords for the app specified in the app_id field", "nullable": true } } }, "DataforseoLabsGoogleAppCompetitorsLiveRequestInfo": { "type": "object", "properties": { "app_id": { "type": "string", "description": "id of the app\nrequired field\nID of the mobile application on Google Play;\nyou can find the ID in the URL of every app listed on Google Play;\nexample:\nin the URL https://play.google.com/store/apps/details?id=org.telegram.messenger\nthe id is org.telegram.messenger" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only;\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only\nexample:\nen", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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:\n<, <=, >, >=, =, <>, in, not_in\nexample:\n[\"intersections\",\">\",500]\n[[\"competitor_metrics.google_play_search_organic.pos_1\",\"<>\",10],\"and\",[\"avg_position\",\">=\",\"10\"]]\n[[[\"intersections\",\">=\",50],\"and\",[\"competitor_metrics.google_play_search_organic.pos_1\",\"in\",[1,5]]],\n\"or\",\n[\"sum_position\",\">=\",\"10000\"]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results;\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order;\ndesc \u2013 results will be sorted in the descending order;\nyou should use a comma to specify a sorting type;\nexample:\n[\"intersections,asc\"]\nNote: you can set no more than three sorting rules in a single request;\nyou should use a comma to separate several sorting rules;\nexample:\n[\"intersections,desc\",\"sum_position,asc\"]\ndefault rule:\n[\"intersections,desc\"]\nNote: 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", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned apps\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned apps\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "app_id": "org.telegram.messenger", "language_name": "English", "location_code": 2840, "limit": 10 } ] }, "DataforseoLabsAppleBulkAppMetricsLiveRequestInfo": { "type": "object", "properties": { "app_ids": { "type": "array", "items": { "type": "string" }, "description": "ids of the apps\nrequired field\nIDs of mobile applications on App Store;\nyou can find the ID in the URL of every app listed on App Store;\nexample:\nin the URL https://apps.apple.com/us/app/id835599320\nthe id is 835599320;\nthe maximum number of IDs you can specify in this field is 1000" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US location only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only;\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the English language only\nexample:\nen", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "app_ids": [ "686449807", "382617920" ], "language_name": "English", "location_code": 2840 } ] }, "DataforseoLabsAmazonRankedKeywordsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonRankedKeywordsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsAmazonRankedKeywordsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonRankedKeywordsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsAmazonRankedKeywordsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "asin": { "type": "string", "description": "ASIN in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonRankedKeywordsLiveItem" } ], "nullable": true }, "description": "contains detected Amazon product competitors and related data", "nullable": true } } }, "DataforseoLabsAmazonRankedKeywordsLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "description": "keyword data for the returned keyword", "nullable": true }, "ranked_serp_element": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonRankedSerpElement" } ], "description": "contains data on the products\u2019s SERP element found for the returned keyword", "nullable": true } } }, "AmazonRankedSerpElement": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "serp_item": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonInfo" } ], "description": "contains data on the SERP element\nthe list of supported SERP elements can be found below", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to Amazon results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "serp_item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "direct URL to Amazon results\ncontains types of all search results (items) found in the returned SERP;\npossible item types:\namazon_serp, amazon_paid, editorial_recommendations, top_rated_from_our_brands, related_searches", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in Amazon SERP", "format": "int64", "nullable": true }, "last_updated_time": { "type": "string", "description": "date and time when SERP data was last updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "previous_updated_time": { "type": "string", "description": "previous to the most recent update of SERP data\nin the ISO 8601 format: \u201cYYYY-MM-DDThh:mm:ss.sssssssZ\u201d\nexample:\n2020-09-12T00:07:43.0733218Z", "nullable": true } } }, "AmazonInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "description": "position within a group of elements with identical type values\npositions of elements with different type values are omitted from rank_group", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in Amazon SERP\nabsolute position among all the elements in SERP", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in Amazon SERP\ncan take the following values:\nleft, right", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true }, "domain": { "type": "string", "description": "Amazon domain", "nullable": true }, "title": { "type": "string", "description": "product title", "nullable": true }, "url": { "type": "string", "description": "URL of the product page", "nullable": true }, "asin": { "type": "string", "description": "ASIN of the product\nlearn more about ASIN in this help center guide", "nullable": true }, "image_url": { "type": "string", "description": "URL of the product image featured in the results", "nullable": true }, "price_from": { "type": "number", "description": "the regular price of a product\nexample:\n49.98", "nullable": true }, "price_to": { "type": "number", "description": "the upper limit of the product price range\nexample:\n384.99", "nullable": true }, "currency": { "type": "string", "description": "currency in the ISO format\nexample:\nUSD", "nullable": true }, "special_offers": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "special offer details\ncontains special offer details, including coupon and Subscribe & Save discounts", "nullable": true }, "is_best_seller": { "type": "boolean", "description": "\u201cBest Seller\u201d label\nif the value is true, the product is marked with the \u201cBest Seller\u201d label", "nullable": true }, "is_amazon_choice": { "type": "boolean", "description": "\u201cAmazon\u2019s choice\u201d label\nif the value is true, the product is marked with the \u201cAmazon\u2019s choice\u201d label", "nullable": true }, "rating": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RatingInfo" } ], "properties": { "value": { "type": "number", "description": "the value of the rating", "format": "float", "nullable": true } }, "description": "the item\u2019s rating \nthe popularity rate based on reviews and displayed in SERP", "nullable": true }, "delivery_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonDeliveryInfo" } ], "description": "delivery information\ndelivery information including free and fast delivery date ranges", "nullable": true }, "bought_past_month": { "type": "integer", "nullable": true } } }, "AmazonDeliveryInfo": { "type": "object", "properties": { "delivery_message": { "type": "string", "description": "message accompanying the delivery information as posted by the seller", "nullable": true }, "delivery_date_from": { "type": "string", "description": "the earliest date when the product can be shipped", "nullable": true }, "delivery_date_to": { "type": "string", "description": "the latest date when the product can be delivered", "nullable": true }, "fastest_delivery_date_from": { "type": "string", "description": "the earliest date when the product can be delivered with a fast delivery option", "nullable": true }, "fastest_delivery_date_to": { "type": "string", "description": "the latest date when the product can be delivered with a fast delivery option", "nullable": true }, "delivery_price": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/PriceInfo" } ], "description": "price for the delivery\nprice of the delivery based on the location you specified in the POST request;\nif free delivery is available, the value is null", "nullable": true } } }, "DataforseoLabsGoogleHistoricalKeywordDataLiveRequestInfo": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" }, "description": "keywords\nrequired field\nThe maximum number of keywords you can specify: 700\nThe maximum number of characters for each keyword: 80\nThe maximum number of words for each keyword phrase: 10\nthe specified keywords will be converted to lowercase format, data will be provided in a separate array\nnote that if some of the keywords specified in this array are omitted in the results you receive, then our database doesn\u2019t contain such keywords and cannot return data on them\nyou will not be charged for the keywords omitted in the results\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available locations with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available locations with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keywords": [ "iphone" ] } ] }, "DataforseoLabsAmazonProductRankOverviewLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonProductRankOverviewLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsAmazonProductRankOverviewLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonProductRankOverviewLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsAmazonProductRankOverviewLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonProductRankOverviewLiveItem" } ], "nullable": true }, "description": "contains detected Amazon product competitors and related data", "nullable": true } } }, "DataforseoLabsAmazonProductRankOverviewLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "asin": { "type": "string", "description": "ASIN of the product\nunique product identifier on Amazon;\nfor more information, refer to this help center guide", "nullable": true }, "metrics": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonMetricsBundleInfo" } ], "description": "average keyword position of the product", "nullable": true } } }, "AmazonMetricsBundleInfo": { "type": "object", "properties": { "amazon_serp": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AppMetricsInfo" } ], "description": "ranking data from Amazon organic SERP", "nullable": true }, "amazon_paid": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AppMetricsInfo" } ], "description": "ranking data from Amazon paid SERP", "nullable": true } } }, "DataforseoLabsStatusResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsStatusTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsStatusTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsStatusResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsStatusResultInfo": { "type": "object", "properties": { "google": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsStatusInfo" } ], "description": "update information for the Google endpoints", "nullable": true }, "bing": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsStatusInfo" } ], "description": "update information for the Bing endpoints", "nullable": true }, "amazon": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsStatusInfo" } ], "description": "update information for the Amazon endpoints", "nullable": true } } }, "DataforseoLabsStatusInfo": { "type": "object", "properties": { "date_update": { "type": "string", "description": "update date of the Google endpoints\nindicates the last date when the Google endpoints of DataForSEO Labs API were updated;\nexample:\n2022-05-16", "nullable": true } } }, "DataforseoLabsAmazonProductKeywordIntersectionsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonProductKeywordIntersectionsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsAmazonProductKeywordIntersectionsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonProductKeywordIntersectionsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsAmazonProductKeywordIntersectionsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "asins": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "ASINs in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonProductKeywordIntersectionsLiveItem" } ], "nullable": true }, "description": "contains detected Amazon product competitors and related data", "nullable": true } } }, "DataforseoLabsAmazonProductKeywordIntersectionsLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonKeywordData" } ], "description": "keyword data for the returned keyword", "nullable": true }, "intersection_result": { "type": "object", "additionalProperties": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonInfo" } ], "nullable": true }, "description": "data on the intersection", "nullable": true } } }, "DataforseoLabsAmazonProductCompetitorsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonProductCompetitorsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsAmazonProductCompetitorsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonProductCompetitorsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsAmazonProductCompetitorsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "asin": { "type": "string", "description": "ASIN in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsAmazonProductCompetitorsLiveItem" } ], "nullable": true }, "description": "contains detected Amazon product competitors and related data", "nullable": true } } }, "DataforseoLabsAmazonProductCompetitorsLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "asin": { "type": "string", "description": "ASIN of the product\nunique product identifier on Amazon;\nfor more information, refer to this help center guide", "nullable": true }, "avg_position": { "type": "number", "description": "average position of the product in Amazon SERP\nNote: average position is calculated for intersected keywords only;\nthe value for a given product may differ when combined with different target products", "format": "float", "nullable": true }, "sum_position": { "type": "integer", "description": "sum of all product positions in Amazon SERP\nNote: average position is calculated for intersected keywords only;\nthe value for a given product may differ when combined with different target products", "nullable": true }, "intersections": { "type": "integer", "description": "number of intersecting keywords", "nullable": true }, "competitor_metrics": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonMetricsBundleInfo" } ], "description": "metrics for intersecting keywords\nranking data relevant to the keywords that the provided asin shares with the target asin;\nNote: in this object ranking data is provided for the returned competitor\u2019s asin", "nullable": true }, "full_metrics": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonMetricsBundleInfo" } ], "description": "metrics for all keywords of the product\nfull overview of ranking data relevant to all keywords that the provided asin is ranking for", "nullable": true } } }, "DataforseoLabsGoogleCategoriesForDomainLiveRequestInfo": { "type": "object", "properties": { "target": { "type": "string", "description": "domain or subdomain\nrequired field\nthe domain or subdomain name of the target website\nthe domain or subdomain should be specified without https:// and www." }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if you don\u2019t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if you don\u2019t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if you don\u2019t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if you don\u2019t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "include_subcategories": { "type": "boolean", "description": "indicates if the subcategories will be included in the search\noptional field\nif set to false, the subcategories will be ignored\ndefault value: false\nlearn more about the parameter in this help center article", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_etv, clickstream_gender_distribution, and\u00a0clickstream_age_distribution\u00a0fields with clickstream data in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "historical_serp_mode": { "type": "string", "description": "data collection mode\noptional field\nyou can use this field to filter the results;\npossible types of filtering:\nlive \u2014 return metrics for SERPs in which the specified target currently has ranking results;\nlost \u2014 return metrics for SERPs in which the specified target had previously had ranking results, but didn\u2019t have them during the last check;\nall \u2014 return metrics for both types of SERPs.\ndefault value: live", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string" }, "description": "display results by item type\noptional field\nindicates the type of search results included in the response\nNote: 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;\npossible values:\n[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]\ndefault value:\n[\"organic\", \"paid\"]", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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\nexample:\n[\"metrics.organic.pos_1,\">\",0]\n[[[\"metrics.organic.count\",\">=\",100],\"and\",[\"metrics.organic.pos_1\",\">\",0]],\n\"or\",\n[\"metrics.organic.etv\",\"in\",[10,100]]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to specify a sorting type\nexample:\n[\"metrics.paid.etv,asc\"]\nNote: you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"metrics.organic.etv,desc\",\"metrics.paid.count,asc\"]\ndefault rule:\n[\"metrics.organic.count,desc\"]\nNote: 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", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned categories\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned categories \noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "target": "dataforseo.com", "language_code": "en", "location_name": "United States", "item_types": [ "paid", "organic", "featured_snippet", "local_pack" ], "limit": 3 } ] }, "DataforseoLabsGoogleRankedKeywordsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleRankedKeywordsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleRankedKeywordsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleRankedKeywordsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleRankedKeywordsLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "target": { "type": "string", "description": "target domain or webpage in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array\nif there is no data, then the value is\u00a0null", "nullable": true }, "total_count": { "type": "integer", "description": "total number of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataforseoLabsMetricsInfo" }, "description": "ranking data relevant to the specified domain or webpage \nranking data is provided by the rank_group parameters that show the result\u2019s rank considering only equivalent SERP elements", "nullable": true }, "metrics_absolute": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataforseoLabsMetricsInfo" }, "description": "ranking data relevant to the specified domain or webpage\nranking data is provided by the rank_absolute parameters that indicate the result\u2019s position among all SERP elements", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleRankedKeywordsLiveItem" } ], "nullable": true }, "description": "contains ranked keywords and related data", "nullable": true } } }, "DataforseoLabsGoogleRankedKeywordsLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "keyword_data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordDataInfo" } ], "description": "keyword data for the returned keyword", "nullable": true }, "ranked_serp_element": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RankedSerpElement" } ], "description": "contains data on the domain\u2019s SERP element found for the returned keyword", "nullable": true } } }, "RankedSerpElement": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "serp_item": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseDataforseoLabsApiElementItem" } ], "description": "contains data on the SERP element\nthe list of supported SERP elements can be found below", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "serp_item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP\nall possible item types can be found here, they include:\nanswer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, images, jobs, knowledge_graph, local_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box;\nnote that the actual results will be returned only for organic, paid, featured_snippet, local_pack, and ai_overview_reference elements", "nullable": true }, "se_results_count": { "type": "integer", "description": "number of search results for the returned keyword", "format": "int64", "nullable": true }, "keyword_difficulty": { "type": "integer", "description": "difficulty of ranking in the first top-10 organic results for a keyword\nindicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100;\ncalculated by analysing, among other parameters, link profiles of the first 10 pages in SERP", "nullable": true }, "is_lost": { "type": "boolean", "description": "lost ranked elements\nindicates how many ranked elements of this target were previously presented in SERPs, but weren\u2019t found during the last check", "nullable": true }, "last_updated_time": { "type": "string", "description": "date and time when SERP data was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "previous_updated_time": { "type": "string", "description": "previous to the most recent date and time when SERP data was updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-10-15 12:57:46 +00:00", "nullable": true } } }, "DataforseoLabsAmazonProductRankOverviewLiveRequestInfo": { "type": "object", "properties": { "asins": { "type": "array", "items": { "type": "string" }, "description": "product IDs to compare\nrequired field\nproduct IDs to receive ranking data for;\nthe maximum number of ASINs you can specify in this array is 1000;\nyou can receive the asin parameter by making a separate request to the Amazon Products endpoint\nNote: all letters in ASIN code must be specified in uppercase format;\nexample:\nB01LW2SL7R" }, "location_name": { "type": "string", "description": "full name of the location\nrequired field if don\u2019t specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;\nexample:\nUnited States", "nullable": true }, "location_code": { "type": "integer", "description": "location code\nrequired field if don\u2019t specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;\nNote: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\nrequired field if don\u2019t specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\nrequired field if don\u2019t specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "asins": [ "B001TJ3HUG", "B01LW2SL7R" ], "language_name": "English", "location_code": 2840 } ] }, "DataforseoLabsGoogleCategoriesForDomainLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleCategoriesForDomainLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "DataforseoLabsGoogleCategoriesForDomainLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleCategoriesForDomainLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "DataforseoLabsGoogleCategoriesForDomainLiveResultInfo": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "target": { "type": "string", "description": "target domain or subdomain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "total_count": { "type": "integer", "description": "total amount of results in our database relevant to your request", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DataforseoLabsGoogleCategoriesForDomainLiveItem" } ], "nullable": true }, "description": "contains relevant categories and related ranking data", "nullable": true } } }, "DataforseoLabsGoogleCategoriesForDomainLiveItem": { "type": "object", "properties": { "se_type": { "type": "string", "description": "search engine type", "nullable": true }, "categories": { "type": "array", "items": { "type": "integer" }, "description": "product and service categories\nyou can download the full list of possible categories", "nullable": true }, "metrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataforseoLabsMetricsInfo" }, "description": "ranking data relevant to the specified domain or subdomain", "nullable": true } } }, "DataforseoLabsGoogleSubdomainsLiveRequestInfo": { "type": "object", "properties": { "target": { "type": "string", "description": "domain\nrequired field\nthe domain name of the target website\nthe domain should be specified without https:// and www." }, "location_name": { "type": "string", "description": "full name of the location\noptional field\nif you use this field, you don\u2019t need to specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\noptional field\nif you use this field, you don\u2019t need to specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\noptional field\nif you use this field, you don\u2019t need to specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\noptional field\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available languages\nexample:\nen", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string" }, "description": "display results by item type\noptional field\nindicates the type of search results included in the response\nNote: 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;\npossible values:\n[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]\ndefault value:\n[\"organic\", \"paid\"]", "nullable": true }, "include_clickstream_data": { "type": "boolean", "description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to\u00a0true, you will receive clickstream_etv, clickstream_gender_distribution, and\u00a0clickstream_age_distribution\u00a0fields with clickstream data in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article", "nullable": true }, "historical_serp_mode": { "type": "string", "description": "data collection mode\noptional field\nyou can use this field to filter the results;\npossible types of filtering:\nlive \u2014 return metrics for SERPs in which the specified target currently has ranking results;\nlost \u2014 return metrics for SERPs in which the specified target had previously had ranking results, but didn\u2019t have them during the last check;\nall \u2014 return metrics for both types of SERPs.\ndefault value: live", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true, only core keywords will be returned, all highly similar keywords will be excluded;\ndefault value: false", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parameters\noptional field\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\nexample:\n[\"metrics.paid.count\",\">\",0]\n[[\"metrics.paid.count\",\">\",0],\"and\",[\"metrics.paid.etv\",\">\",\"50\"]]\n[[\"metrics.organic.count\",\">\",\"10\"],\n\"and\",\n[[\"metrics.organic.pos_1\",\"<>\",0],\"or\",[\"metrics.organic.pos_2_3\",\"<>\",0]]]\nfor more information about filters, please refer to Dataforseo Labs \u2013 Filters or this help center guide", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rules\noptional field\nyou can use the same values as in the filters array to sort the results\npossible sorting types:\nasc \u2013 results will be sorted in the ascending order\ndesc \u2013 results will be sorted in the descending order\nyou should use a comma to specify a sorting type\nexample:\n[\"metrics.paid.etv,asc\"]\nNote: you can set no more than three sorting rules in a single request\nyou should use a comma to separate several sorting rules\nexample:\n[\"metrics.organic.etv,desc\",\"metrics.paid.count,asc\"]\ndefault rule:\n[\"metrics.organic.count,desc\"]\nNote: 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", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned keywords\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned keywords\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "target": "dataforseo.com", "language_name": "English", "location_code": 2840, "filters": [ [ "metrics.organic.pos_1", "<>", 0 ], "or", [ "metrics.organic.pos_2_3", "<>", 0 ] ] } ] }, "DataforseoLabsGoogleDomainRankOverviewLiveRequestInfo": { "type": "object", "properties": { "target": { "type": "string", "description": "domain\nrequired field\nthe domain name of the target website\nthe domain should be specified without https:// and www." }, "location_name": { "type": "string", "description": "full name of the location\noptional field\nif you use this field, you don\u2019t need to specify location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\nUnited Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "location code\noptional field\nif you use this field, you don\u2019t need to specify location_name\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available locations\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the language\noptional field\nif you use this field, you don\u2019t need to specify language_code\nyou can receive the list of available languages with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "language code\noptional field\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nignore this field to get the results for all available languages\nexample:\nen", "nullable": true }, "ignore_synonyms": { "type": "boolean", "description": "ignore highly similar keywords\noptional field\nif set to\u00a0true, 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\ndefault value: false", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned results for domain\noptional field\ndefault value: 100\nmaximum value: 1000", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned items\noptional field\ndefault value: 0\nif 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "target": "dataforseo.com", "language_name": "English", "location_code": 2840 } ] } } }