DataForSEO · Schema
DataForSEO Labs API Schemas
SEOSERPKeywordsBacklinksDomain AnalyticsOn-Page SEOCompetitor ResearchSearch EnginesContent AnalysisE-CommerceApp StoreBusiness DataAI OptimizationSocial Media
JSON Schema
{
"$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 c
# --- truncated at 32 KB (467 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dataforseo/refs/heads/main/json-schema/dataforseo-labs-schema.json