DataForSEO · Schema
DataForSEO Keywords Data 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 Keywords Data API Schemas",
"definitions": {
"KeywordsDataBingKeywordPerformanceTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordsDataBingKeywordPerformanceTaskGetTaskInfo"
}
],
"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
}
}
},
"KeywordsDataBingKeywordPerformanceTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordsDataBingKeywordPerformanceTaskGetResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"KeywordsDataBingKeywordPerformanceTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword 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
},
"year": {
"type": "integer",
"description": "indicates the year for which the data is provided for\nexample:\n2020",
"nullable": true
},
"month": {
"type": "integer",
"description": "indicates the month for which the data is provided for\nexample:\n10",
"nullable": true
},
"keyword_kpi": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordKpi"
}
],
"description": "object containing keyword metrics\nif there is no data, then the value is\u00a0null",
"nullable": true
}
}
},
"KeywordKpi": {
"type": "object",
"properties": {
"desktop": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordKpiItemInfo"
}
],
"nullable": true
},
"description": "keyword data aggregated for desktop devices\nif there is no data, then the value is\u00a0null",
"nullable": true
},
"mobile": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordKpiItemInfo"
}
],
"nullable": true
},
"description": "keyword data aggregated for mobile devices\nif there is no data, then the value is\u00a0null",
"nullable": true
},
"tablet": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordKpiItemInfo"
}
],
"nullable": true
},
"description": "keyword data aggregated for tablet devices\nif there is no data, then the value is\u00a0null",
"nullable": true
}
}
},
"KeywordKpiItemInfo": {
"type": "object",
"properties": {
"ad_position": {
"type": "string",
"description": "represents the position of the relevant ad in SERP\ncan take the following values:\nFirstPage1: The first ad to appear on the right side of the first search results page\nFirstPage2: The second ad to appear on the right side of the first search results page\nFirstPage3: The third ad to appear on the right side of the first search results page\nFirstPage4: The fourth ad to appear on the right side of the first search results page\nFirstPage5: The fifth ad to appear on the right side of the first search results page\nFirstPage6: The sixth ad to appear on the right side of the first search results page\nFirstPage7: The seventh ad to appear on the right side of the first search results page\nFirstPage8: The eighth ad to appear on the right side of the first search results page\nFirstPage9: The ninth ad to appear on the right side of the first search results page\nFirstPage10: The tenth ad to appear on the right side of the first search results page\nMainLine1: The first ad to appear at the top of the search results page\nMainLine2: The second ad to appear at the top of the search results page\nMainLine3: The third ad to appear at the top of the search results page\nMainLine4: The fourth ad to appear at the top of the search results page",
"nullable": true
},
"clicks": {
"type": "integer",
"description": "ad clicks\nthe number of clicks that the keyword and match type generated during the last month",
"nullable": true
},
"impressions": {
"type": "integer",
"description": "ad impressions\nthe number of impressions that the keyword and match type generated during the last month",
"nullable": true
},
"average_cpc": {
"type": "number",
"description": "average cost per click, USD\ncalculated by dividing the cost of all clicks by the number of clicks",
"format": "double",
"nullable": true
},
"ctr": {
"type": "number",
"description": "click-through rate as a percentage\ncalculated by dividing the number of clicks by the number of impressions and multiplying the result by 100",
"format": "double",
"nullable": true
},
"total_cost": {
"type": "number",
"description": "total cost of an ad, USD\nthe cost of using the specified keyword and match type during the last month",
"format": "int64",
"nullable": true
},
"average_bid": {
"type": "number",
"description": "average bid of the keyword",
"format": "double",
"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
}
}
},
"KeywordsDataBingAudienceEstimationTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordsDataBingAudienceEstimationTaskPostTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"KeywordsDataBingAudienceEstimationTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "object",
"description": "array of results\nin this case, the value will be null",
"nullable": true
}
}
}
]
},
"KeywordsDataGoogleAdsKeywordsForKeywordsTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordsDataGoogleAdsKeywordsForKeywordsTasksReadyTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"KeywordsDataGoogleAdsKeywordsForKeywordsTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordsDataGoogleAdsKeywordsForKeywordsTasksReadyResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"KeywordsDataGoogleAdsKeywordsForKeywordsTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "task identifier of the completed task\nunique task identifier in our system in the UUID format",
"nullable": true
},
"se": {
"type": "string",
"description": "search engine specified when setting the task",
"nullable": true
},
"se_type": {
"type": "string",
"nullable": true
},
"date_posted": {
"type": "string",
"description": "date when the task was posted (in the UTC format)",
"nullable": true
},
"tag": {
"type": "string",
"description": "user-defined task identifier",
"nullable": true
},
"endpoint": {
"type": "string",
"description": "URL for collecting the results of the task",
"nullable": true
}
}
},
"KeywordsDataDataforseoTrendsExploreLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordsDataDataforseoTrendsExploreLiveTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"KeywordsDataDataforseoTrendsExploreLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordsDataDataforseoTrendsExploreLiveResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"KeywordsDataDataforseoTrendsExploreLiveResultInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string",
"nullable": true
},
"description": "keywords in a POST array",
"nullable": true
},
"type": {
"type": "string",
"description": "type of element",
"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
},
"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
},
"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/DataforseoTrendsDataforseoTrendsGraphElementItem"
}
],
"nullable": true
},
"description": "contains keyword popularity and related data",
"nullable": true
}
}
},
"DataforseoTrendsDataforseoTrendsGraphElementItem": {
"type": "object",
"allOf": [
{
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/BaseKeywordDataDataforseoTrendsItem"
}
],
"nullable": true
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/DataforseoTrendsGraphDataTrendsGraphDataInfo"
}
],
"nullable": true
},
"description": "DataForSEO Trends data for the specified parameters",
"nullable": true
},
"averages": {
"type": "array",
"items": {
"type": "integer",
"nullable": true
},
"description": "keyword popularity values averaged over the whole time range",
"nullable": true
}
}
}
]
},
"BaseKeywordDataDataforseoTrendsItem": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "type of element",
"nullable": true
},
"position": {
"type": "integer",
"description": "the alignment of the element\ncan take the following values: 1, 2, 3, 4, etc.",
"nullable": true
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"nullable": true
},
"description": "relevant keywords\nthe data included in the dataforseo_trends_graph element is based on the keywords listed in this array",
"nullable": true
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"dataforseo_trends_graph": "#/components/schemas/DataforseoTrendsDataforseoTrendsGraphElementItem",
"subregion_interests": "#/components/schemas/DataforseoTrendsSubregionInterestsElementItem",
"demography": "#/components/schemas/DataforseoTrendsDemographyElementItem"
}
}
},
"DataforseoTrendsGraphDataTrendsGraphDataInfo": {
"type": "object",
"properties": {
"date_from": {
"type": "string",
"description": "start date of the corresponding time range\nin the UTC format: \u201cyyyy-mm-dd\u201d",
"nullable": true
},
"date_to": {
"type": "string",
"description": "end date of the corresponding time range\nin the UTC format: \u201cyyyy-mm-dd\u201d",
"nullable": true
},
"timestamp": {
"type": "integer",
"description": "a point in time in the Unix time format",
"nullable": true
},
"values": {
"type": "array",
"items": {
"type": "integer",
"nullable": true
},
"description": "relative keyword popularity rate at a specific timestamp\nrepresents the keyword popularity rate over the given time range\nif you specify more than one keyword, the values will be averaged to the highest value across all specified keywords\na value of 100 is the peak popularity for the term. A value of 50 means that the term is half as popular. A score of 0 means there was not enough data for this term",
"nullable": true
}
}
},
"KeywordsDataBingKeywordsForSiteTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordsDataBingKeywordsForSiteTaskGetTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"KeywordsDataBingKeywordsForSiteTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordsDataBingKeywordsForSiteTaskGetResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"KeywordsDataBingKeywordsForSiteTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword in a POST array",
"nullable": true
},
"location_code": {
"type": "integer",
"description": "location code in a POST array\nif there is no data the value is null",
"nullable": true
},
"language_code": {
"type": "string",
"description": "language code in a POST array\nif there is no data the value is null",
"nullable": true
},
"search_partners": {
"type": "boolean",
"description": "indicates whether data from partner networks included in the response",
"nullable": true
},
"device": {
"type": "string",
"description": "device type in a POST array\nif there is no data, then the value is\u00a0null",
"nullable": true
},
"competition": {
"type": "number",
"description": "competition\nrepresents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Bing Ads data.\nPossible values: 0.1, 0.5,0.9 \n0.1 \u2013 low competition,\n0.5 \u2013 medium competition,\n0.9 \u2013 high competition;\nif there is no data the value is null",
"nullable": true
},
"cpc": {
"type": "number",
"description": "cost-per-click\nrepresents the average cost per click (USD) historically paid for the keyword.\nif there is no data the value is null",
"nullable": true
},
"search_volume": {
"type": "integer",
"description": "monthly average search volume rate\nrepresents the (approximate) number of searches for the given keyword idea on Bing search engine depending on the user\u2019s targeting\nif there is no data then the value is\u00a0null",
"format": "int64",
"nullable": true
},
"categories": {
"type": "array",
"items": {
"type": "string",
"nullable": true
},
"description": "product and service categories\nlegacy field, the value will always be null",
"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\nsearch volume is rounded to the closest decimal values\nif there is no data the value is null",
"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
}
}
},
"KeywordsDataBingKeywordPerformanceLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordsDataBingKeywordPerformanceLiveTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"KeywordsDataBingKeywordPerformanceLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordsDataBingKeywordPerformanceLiveResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"KeywordsDataBingKeywordPerformanceLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword 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
},
"year": {
"type": "integer",
"description": "indicates the year for which the data is provided for\nexample:\n2020",
"nullable": true
},
"month": {
"type": "integer",
"description": "indicates the month for which the data is provided for\nexample:\n10",
"nullable": true
},
"keyword_kpi": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/KeywordKpi"
}
],
"description": "object containing keyword metrics\nif there is no data, then the value is\u00a0null",
"nullable": true
}
}
},
"KeywordsDataBingKeywordPerformanceTaskPostRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords\nrequired field\nThe maximum number of keywords you can specify: 1000\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, data will be provided in a separate array\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"device": {
"type": "string",
"description": "device type\noptional field\nspecify this field if you want to get the data for a particular device typepossible values: desktop, mobile, tablet, all\ndefault value: all",
"nullable": true
},
"match": {
"type": "string",
"description": "keywords match type\noptional field\ncan take the following values:\naggregate returns data across all match types;\nbroad returns data for all user queries containing the specified keyword with varying word order;\nphrase returns data for all user queries containing the specified keyword with identical word order;\nexact returns data for user query that matches the specified keyword;Note: the aggregate match type is applied by default",
"nullable": true
},
"location_name": {
"type": "string",
"description": "full name of search engine location\nrequired field if you don\u2019t specify location_code or location_coordinate\nif you use this field, you don\u2019t need to specify location_code or location_coordinate\nyou can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages\nexample:\n\"United States\"",
"nullable": true
},
"location_code": {
"type": "integer",
"description": "search engine location code\nrequired field if you don\u2019t specify location_name or location_coordinate\nif you use this field, you don\u2019t need to specify location_name or location_coordinate\nyou can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages\nexample:\n2840",
"nullable": true
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location\nrequired field if you don\u2019t specify location_name or location_code\nif you use this field, you don\u2019t need to specify location_name or location_code\nlocation_coordinate parameter should be specified in the \u201clatitude,longitude\u201d format\nthe data will be provided for the country the specified coordinates belong to\nexample:\n52.6178549,-155.352142",
"nullable": true
},
"language_name": {
"type": "string",
"description": "full name of search engine language\nrequired field if you don\u2019t specify language_code\nif you use this field, you don\u2019t need to specify language_code\nyou can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages\nexample:\nEnglish",
"nullable": true
},
"language_code": {
"type": "string",
"description": "search engine language code\nrequired field if you don\u2019t specify language_name\nyou can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages\nexample:\n\"en\"",
"nullable": true
},
"postback_url": {
"type": "string",
"description": "URL for sending task results\noptional field\nonce the task is completed, we will send a POST request with its results compressed
# --- truncated at 32 KB (393 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dataforseo/refs/heads/main/json-schema/dataforseo-keywords-data-schema.json