DataForSEO · Schema
DataForSEO Merchant 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 Merchant API Schemas",
"definitions": {
"MerchantGoogleProductsTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/MerchantGoogleProductsTaskGetAdvancedTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"MerchantGoogleProductsTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/MerchantGoogleProductsTaskGetAdvancedResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"MerchantGoogleProductsTaskGetAdvancedResultInfo": {
"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
},
"check_url": {
"type": "string",
"description": "direct URL to Google Shopping 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 found in Google Shopping SERP\ncontains types of all search results (items) found in the returned SERP\npossible item types:\ngoogle_shopping_sponsored_carousel, google_shopping_paid, google_shopping_serp",
"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/BaseMerchantGoogleShoppingProductsElementItem"
}
],
"nullable": true
},
"description": "additional items present in the element\ncontains a list of related keywords;\nif there are none, equals null",
"nullable": true
}
}
},
"BaseMerchantGoogleShoppingProductsElementItem": {
"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 found in Google Shopping SERP",
"nullable": true
},
"position": {
"type": "string",
"description": "alignment of the element in SERP\ncan take the following values:\nleft, right",
"nullable": true
},
"xpath": {
"type": "string",
"description": "XPath of the element",
"nullable": true
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"google_shopping_serp": "#/components/schemas/GoogleShoppingSerpElementItem",
"google_shopping_paid": "#/components/schemas/GoogleShoppingPaidElementItem",
"google_shopping_sponsored_carousel": "#/components/schemas/GoogleShoppingSponsoredCarouselElementItem",
"google_shopping_carousel": "#/components/schemas/GoogleShoppingCarouselElementItem",
"related_searches": "#/components/schemas/RelatedSearchesElementItem"
}
}
},
"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
}
}
},
"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
}
}
},
"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
}
}
},
"MerchantGoogleSellersAdUrlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/MerchantGoogleSellersAdUrlTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"MerchantGoogleSellersAdUrlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/MerchantGoogleSellersAdUrlResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"MerchantGoogleSellersAdUrlResultInfo": {
"type": "object",
"properties": {
"ad_aclk": {
"type": "string",
"description": "unique ad click referral parameter",
"nullable": true
},
"ad_url": {
"type": "string",
"description": "full URL of the advertisement",
"nullable": true
},
"ad_url_redirects": {
"type": "array",
"items": {
"type": "string",
"nullable": true
},
"description": "URLs where the link from Google Shopping redirects before reaching a final URL\nincludes up to 10 URLs of the ad\u2019s redirect path to the seller\u2019s ad_url",
"nullable": true
}
}
},
"MerchantIdListResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/MerchantIdListTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"MerchantIdListTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/MerchantIdListResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"MerchantIdListResultInfo": {
"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
}
}
},
"MerchantGoogleLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/MerchantGoogleLanguagesTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"MerchantGoogleLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/MerchantGoogleLanguagesResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"MerchantGoogleLanguagesResultInfo": {
"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
}
}
},
"MerchantGoogleSellersTaskPostRequestInfo": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "unique product identifier on Google Shopping\nrequired field if data_docid or gid is not specified\nwe recommend specifying product_id together with data_docid and gid for optimal results;\nyou can get this value for a certain product by making a separate request to the Google Shopping Products endpoint\nexample:\n4485466949985702538\nlearn more about the parameter in this help center guide",
"nullable": true
},
"data_docid": {
"type": "string",
"description": "unique identifier of the SERP data element\nrequired field if product_id or gid is not specified\nwe recommend specifying data_docid together with product_id and gid for optimal results;\nyou can get this value for a certain element by making a separate request to the Google Shopping Products endpoint\nexample:\n13071766526042404278",
"nullable": true
},
"gid": {
"type": "string",
"description": "global product identifier on Google Shopping\nrequired field if product_id or data_docid is not specified\nwe recommend specifying gid together with product_id and data_docid for optimal results;\nyou can get this value for a certain product by making a separate request to the Google Shopping Products endpoint\nexample:\n4702526954592161872\nlearn more about the parameter in this help center guide",
"nullable": true
},
"pvf": {
"type": "string",
"description": "product variant filter on Google Shopping\noptional field\nparameter in Google Shopping URL, setting optional product variant filtration;\nexample:\nEg4iBWNvbG9yKgV3aGl0ZRISIgxwYWNrYWdlIHNpemUqAjE0EgoiBHNpemUqAnhs",
"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
},
"location_name": {
"type": "string",
"description": "full name of the 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 Google Shopping locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations\nexample:\nLondon,England,United Kingdom",
"nullable": true
},
"location_code": {
"type": "integer",
"description": "location code\nrequired field if you don\u2019t specify location_name\u00a0or 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 Google Shopping locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations\nexample:\n2840",
"nullable": true
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location\nrequired field if you don\u2019t specify location_name\u00a0or 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,radius\u201d format\nthe maximum number of decimal digits for \u201clatitude\u201d and \u201clongitude\u201d: 7\nthe minimum value for \u201cradius\u201d: 199.9\nexample:\n53.476225,-2.243572,200",
"nullable": true
},
"language_name": {
"type": "string",
"description": "full name of the 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 Google Shopping languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages\nexample:\nEnglish",
"nullable": true
},
"language_code": {
"type": "string",
"description": "language code\nrequired field if you don\u2019t specify language_name\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available Google Shopping languages with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages\nexample:\nen",
"nullable": true
},
"depth": {
"type": "integer",
"description": "parsing depth\noptional field\nnumber of results to be retrieved from Google Shopping SERP\ndefault value: 10\nmax value: 200\nyour account will be billed per each SERP containing up to 10 results;\nsetting depth above 10 may result in additional charges if the search engine returns more than 10 results;\nthe cost can be calculated on the Pricing page",
"nullable": true
},
"se_domain": {
"type": "string",
"description": "search engine domain\noptional field\nwe choose the relevant search engine domain automatically according to the location and language you specify\nhowever, you can set a custom search engine domain in this field\nexample:\ngoogle.co.uk, google.com.au, google.de, etc.",
"nullable": true
},
"get_shops_on_google": {
"type": "boolean",
"description": "include \u201cbuy on Google\u201d shops\noptional field\nif set to true, the response will contain the list of sellers that allow to purchase a given product directly on Google\nNote: if set to true, the cost of a task will be doubled",
"nullable": true
},
"additional_specifications": {
"type": "object",
"additionalProperties": {
"type": "string",
"nullable": true
},
"description": "object containing additional url parameters\nyou can get additional information about the product by using the \"additional_specifications object, which you can get by making a separate request to the Google Shopping Products endpoint\nexample:\n\"additional_specifications\": {\n\"eto\": \"16157121050167572763_0\"\n}",
"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
},
"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 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\noptional field\ncorresponds to the datatype that will be sent to your server\npossible values:\nadvanced",
"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
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"product_id": "1113158713975221117"
}
]
},
"MerchantGoogleProductInfoTaskPostRequestInfo": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "unique product identifier on Google Shopping\nrequired field if data_docid or gid is not specified\nwe recommend specifying product_id together with data_docid and gid for optimal results;\nyou can get this value for a certain product by making a separate request to the Google Shopping Products endpoint\nexample:\n4485466949985702538\nlearn more about the parameter in this help center guide",
"nullable": true
},
"data_docid": {
"type": "string",
"description": "unique identifier of the SERP data element\nrequired field if product_id or gid is not specified\nwe recommend specifying data_docid together with product_id and gid for optimal results;\nyou can get this value for a certain element by making a separate request to the Google Shopping Products endpoint\nexample:\n13071766526042404278",
"nullable": true
},
"gid": {
"type": "string",
"description": "global product identifier on Google Shopping\nrequired field if product_id or data_docid is not specified\nwe recommend specifying gid together with product_id and data_docid for optimal results;\nyou can get this value for a certain product by making a separate request to the Google Shopping Products endpoint\nexample:\n4702526954592161872\nlearn more about the parameter in this help center guide",
"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
},
"location_name": {
"type": "string",
"description": "full name of the 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 Google Shopping locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations\nexample:\nLondon,England,United Kingdom",
"nullable": true
},
"location_code": {
"type": "integer",
"description": "location code\nrequired field if you don\u2019t specify location_name\u00a0or 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 Google Shopping locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations\nexample:\n2840",
"nullable": true
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location\nrequired field if you don\u2019t specify location_name\u00a0or 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,radius\u201d format\nthe maximum number of decimal digits for \u201clatitude\u201d and \u201clongitude\u201d: 7\nthe minimum value for \u201cradius\u201d: 199.9\nexample:\n53.476225,-2.243572,200",
"nullable": true
},
"language_name": {
"type": "string",
"description": "full name of the 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 Google Shopping languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages\nexample:\nEnglish",
"nullable": true
},
"language_code": {
"type": "string",
"description": "language code\nrequired field if you don\u2019t specify language_name\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available Google Shopping languages with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages\nexample:\nen",
"nullable": true
},
"se_domain": {
"type": "string",
"description": "search engine domain\noptional field\nwe choose the relevant search engine domain automatically according to the location and language you specify\nhowever, you can set a custom search engine domain in this field\nexample:\ngoogle.co.uk, google.com.au, google.de, etc.",
"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
},
"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 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\noptional field\ncorresponds to the datatype that will be sent to your server\npossible values:\nadvanced",
"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
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"product_id": "1113158713975221117"
}
]
},
"MerchantGoogleProductsTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
# --- truncated at 32 KB (178 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dataforseo/refs/heads/main/json-schema/dataforseo-merchant-schema.json