DataForSEO · Schema
DataForSEO Serp 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 Serp API Schemas",
"definitions": {
"SerpGoogleOrganicLiveHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SerpGoogleOrganicLiveHtmlTaskInfo"
}
],
"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
}
}
},
"SerpGoogleOrganicLiveHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SerpGoogleOrganicLiveHtmlResultInfo"
}
],
"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
}
}
},
"SerpGoogleOrganicLiveHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword received in a POST array\nkeyword 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
},
"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/HtmlItemInfo"
}
],
"nullable": true
},
"description": "elements of search results found in SERP",
"nullable": true
}
}
},
"HtmlItemInfo": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "serial number of the returned HTML page",
"nullable": true
},
"date": {
"type": "string",
"description": "date and time when the HTML page was scanned\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00",
"nullable": true
},
"html": {
"type": "string",
"description": "HTML\u00a0page",
"nullable": true
}
}
},
"SerpBingOrganicTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SerpBingOrganicTasksReadyTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"SerpBingOrganicTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SerpBingOrganicTasksReadyResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"SerpBingOrganicTasksReadyResultInfo": {
"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",
"description": "type of search engine\nexample: organic",
"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_regular": {
"type": "string",
"description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null",
"nullable": true
},
"endpoint_advanced": {
"type": "string",
"description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null",
"nullable": true
},
"endpoint_html": {
"type": "string",
"description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null",
"nullable": true
}
}
},
"SerpNaverOrganicTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SerpNaverOrganicTaskGetHtmlTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"SerpNaverOrganicTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SerpNaverOrganicTaskGetHtmlResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"SerpNaverOrganicTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \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
},
"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/HtmlItemInfo"
}
],
"nullable": true
},
"description": "elements of search results found in SERP",
"nullable": true
}
}
},
"SerpGoogleLocalFinderLiveHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SerpGoogleLocalFinderLiveHtmlTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"SerpGoogleLocalFinderLiveHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SerpGoogleLocalFinderLiveHtmlResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"SerpGoogleLocalFinderLiveHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword received in a POST array\nkeyword 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
},
"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/HtmlItemInfo"
}
],
"nullable": true
},
"description": "elements of search results found in SERP",
"nullable": true
}
}
},
"SerpYoutubeVideoInfoTaskPostRequestInfo": {
"type": "object",
"properties": {
"video_id": {
"type": "string",
"description": "ID of the video\nrequired field\nyou can find video ID in the URL or 'youtube_video' item of YouTube Organic result\nexample:\nvQXvyV0zIP4"
},
"location_code": {
"type": "integer",
"description": "search engine location code\nrequired field if you don't specify location_name\nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840",
"nullable": true
},
"language_code": {
"type": "string",
"description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen",
"nullable": true
},
"priority": {
"type": "integer",
"description": "task priority\noptional field\ncan take the following values:\n1 \u2013 normal execution priority (set by default)\n2 \u2013 high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page.",
"nullable": true
},
"device": {
"type": "string",
"description": "device type\noptional field\nonly value: desktop",
"nullable": true
},
"pingback_url": {
"type": "string",
"description": "notification URL of a completed task\noptional field\nwhen a task is completed we will notify you by GET request sent to the URL you have specified\nyou can use the \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the request.\nexample:\nhttp://your-server.com/pingscript?id=$id\nhttp://your-server.com/pingscript?id=$id&tag=$tag\nNote: special characters in pingback_url will be urlencoded;\ni.a., the # character will be encoded into %23\nlearn more on our Help Center",
"nullable": true
},
"postback_url": {
"type": "string",
"description": "return URL for sending task results\noptional field\nonce the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified\nyou can use the \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the request.\nexample:\nhttp://your-server.com/postbackscript?id=$id\nhttp://your-server.com/postbackscript?id=$id&tag=$tag\nNote: special characters in postback_url will be urlencoded;\ni.a., the # character will be encoded into %23\nlearn more on our Help Center",
"nullable": true
},
"postback_data": {
"type": "string",
"description": "postback_url datatype\nrequired field if you specify postback_url\ncorresponds to the datatype that will be sent to your server\npossible value:\nadvanced",
"nullable": true
},
"location_name": {
"type": "string",
"description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States",
"nullable": true
},
"language_name": {
"type": "string",
"description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish",
"nullable": true
},
"os": {
"type": "string",
"description": "device operating system\noptional field\nchoose from the following values: windows, macos\ndefault value: windows",
"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,
"video_id": "vQXvyV0zIP4"
}
]
},
"SerpNaverOrganicTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SerpNaverOrganicTaskGetAdvancedTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"SerpNaverOrganicTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SerpNaverOrganicTaskGetAdvancedResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"SerpNaverOrganicTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \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
},
"refinement_chips": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/RefinementChipsInfo"
}
],
"description": "search refinement chips\nequals null",
"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:\nimages, local_pack, map, organic, paid, related_searches, video",
"nullable": true
},
"se_results_count": {
"type": "integer",
"description": "total number of results in SERP",
"format": "int64",
"nullable": true
},
"pages_count": {
"type": "integer",
"description": "total pages retrieved\ntotal number of retrieved SERPs in the result",
"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/BaseSerpApiElementItem"
}
],
"nullable": true
},
"description": "additional items present in the element\nif there are none, equals null",
"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
}
}
},
"RefinementChipsInfo": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "type of element",
"nullable": true
},
"xpath": {
"type": "string",
"description": "the XPath of the element",
"nullable": true
},
"items": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/RefinementChipsElement"
}
],
"nullable": true
},
"description": "items of the element",
"nullable": true
}
}
},
"RefinementChipsElement": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "type of element",
"nullable": true
},
"title": {
"type": "string",
"description": "title of the element",
"nullable": true
},
"url": {
"type": "string",
"description": "search URL with refinement parameters",
"nullable": true
},
"domain": {
"type": "string",
"description": "domain in SERP",
"nullable": true
},
"options": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AmazonLabelElement"
}
],
"nullable": true
},
"description": "further search refinement options",
"nullable": true
}
}
},
"AmazonLabelElement": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "type of element",
"nullable": true
},
"title": {
"type": "string",
"description": "title of the element",
"nullable": true
},
"url": {
"type": "string",
"description": "search URL with refinement parameters",
"nullable": true
},
"domain": {
"type": "string",
"description": "domain in SERP",
"nullable": true
}
}
},
"BaseSerpApiElementItem": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "type of element",
"nullable": true
},
"page": {
"type": "integer",
"description": "search results page number\nindicates the number of the SERP page on which the element is located",
"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
},
"rectangle": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AiModeRectangleInfo"
}
],
"description": "rectangle parameters\ncontains cartesian coordinates and pixel dimensions of the result\u2019s snippet in SERP\nequals null if calculate_rectangles in the POST request is not set to true",
"nullable": true
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"paid": "#/components/schemas/PaidSerpElementItem",
"organic": "#/components/schemas/OrganicSerpElementItem",
"featured_snippet": "#/components/schemas/FeaturedSnippetSerpElementItem",
"knowledge_graph": "#/components/schemas/KnowledgeGraphSerpElementItem",
"top_stories": "#/components/schemas/TopStoriesSerpElementItem",
"people_also_ask": "#/components/schemas/PeopleAlsoAskSerpElementItem",
"people_also_search": "#/components/schemas/PeopleAlsoSearchSerpElementItem",
"images": "#/components/schemas/ImagesSerpElementItem",
"twitter": "#/components/schemas/TwitterSerpElementItem",
"google_reviews": "#/components/schemas/GoogleReviewsSerpElementItem",
"jobs": "#/components/schemas/JobsSerpElementItem",
"map": "#/components/schemas/MapSerpElementItem",
"app": "#/components/schemas/AppSerpElementItem",
"local_pack": "#/components/schemas/LocalPackSerpElementItem",
"carousel": "#/components/schemas/CarouselSerpElementItem",
"video": "#/components/schemas/VideoSerpElementItem",
"answer_box": "#/components/schemas/AnswerBoxSerpElementItem",
"shopping": "#/components/schemas/ShoppingSerpElementItem",
"google_flights": "#/components/schemas/GoogleFlightsSerpElementItem",
"mention_carousel": "#/components/schemas/MentionCarouselSerpElementItem",
"events": "#/components/schemas/EventsSerpElementItem",
"related_searches": "#/components/schemas/RelatedSearchesSerpElementItem",
"multi_carousel": "#/components/schemas/MultiCarouselSerpElementItem",
"recipes": "#/components/schemas/RecipesSerpElementItem",
"top_sights": "#/components/schemas/TopSightsSerpElementItem",
"scholarly_articles": "#/components/schemas/ScholarlyArticlesSerpE
# --- truncated at 32 KB (1061 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dataforseo/refs/heads/main/json-schema/dataforseo-serp-schema.json