DataForSEO · Schema
DataForSEO App 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 App Data API Schemas",
"definitions": {
"AppDataAppleAppReviewsTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppDataAppleAppReviewsTaskGetAdvancedTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"AppDataAppleAppReviewsTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppDataAppleAppReviewsTaskGetAdvancedResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"AppDataAppleAppReviewsTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"app_id": {
"type": "string",
"description": "application id received in a POST array",
"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
},
"title": {
"type": "string",
"description": "title of the app\ntitle of the application for which the reviews are collected",
"nullable": true
},
"rating": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/RatingInfo"
}
],
"description": "rating of the app\nrating of the application for which the reviews are collected",
"nullable": true
},
"reviews_count": {
"type": "integer",
"description": "the total number of reviews\nin this case, the value will be null as App Store does not indicate the total number of app reviews",
"format": "int64",
"nullable": true
},
"items_count": {
"type": "integer",
"description": "the number of reviews items in the results array\nyou can get more results by using the depth parameter when setting a task",
"format": "int64",
"nullable": true
},
"items": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppStoreReviewsSearch"
}
],
"nullable": true
},
"description": "found reviews",
"nullable": true
}
}
},
"RatingInfo": {
"properties": {
"rating_type": {
"type": "string",
"description": "the type of rating\nhere you can find the following elements: Max5, Percents, CustomMax",
"nullable": true
},
"value": {
"type": "number",
"description": "the value of the rating",
"format": "double",
"nullable": true
},
"votes_count": {
"type": "integer",
"description": "the amount of feedback",
"format": "int64",
"nullable": true
},
"rating_max": {
"type": "integer",
"description": "the maximum value for a rating_type",
"nullable": true
}
}
},
"AppStoreReviewsSearch": {
"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 among all the listed reviews\nabsolute position among all reviews on the list",
"nullable": true
},
"position": {
"type": "string",
"description": "the alignment of the review in SERP\ncan take the following values: left",
"nullable": true
},
"version": {
"type": "string",
"description": "version of the app\nversion of the app for which the review is submitted",
"nullable": true
},
"rating": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/RatingInfo"
}
],
"description": "the rating score submitted by the reviewer",
"nullable": true
},
"timestamp": {
"type": "string",
"description": "date and time when the review was published\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d;\nexample:\n2019-11-15 12:57:46 +00:00",
"nullable": true
},
"id": {
"type": "string",
"description": "id of the review",
"nullable": true
},
"title": {
"type": "string",
"description": "title of the review",
"nullable": true
},
"review_text": {
"type": "string",
"description": "content of the review",
"nullable": true
},
"user_profile": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppUserProfileInfo"
}
],
"description": "user profile of the reviewer",
"nullable": true
}
}
},
"AppUserProfileInfo": {
"type": "object",
"properties": {
"profile_name": {
"type": "string",
"description": "profile name of the reviewer",
"nullable": true
},
"profile_image_url": {
"type": "string",
"description": "URL to the reviewer\u2019s profile image",
"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
}
}
},
"AppDataGoogleLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppDataGoogleLocationsTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"AppDataGoogleLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppDataGoogleLocationsResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"AppDataGoogleLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": "integer",
"description": "location code",
"nullable": true
},
"location_name": {
"type": "string",
"description": "full name of the location",
"nullable": true
},
"location_name_parent": {
"type": "string",
"description": "the name of the superordinate location\nexample:\n\"location_code\": 1006473,\n\"location_name\": \"Altrincham,England,United Kingdom\",\n\"location_name_parent\": \"England,United Kingdom\", where location_name_parent corresponds to:\n\"location_code\": 20339,\n\"location_name\": \"England,United Kingdom\"",
"nullable": true
},
"country_iso_code": {
"type": "string",
"description": "ISO country code of the location",
"nullable": true
},
"location_type": {
"type": "string",
"description": "location type",
"nullable": true
}
}
},
"AppDataAppleAppSearchesTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppDataAppleAppSearchesTaskGetAdvancedTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"AppDataAppleAppSearchesTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppDataAppleAppSearchesTaskGetAdvancedResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"AppDataAppleAppSearchesTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword received in a POST request",
"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\nin this case, the value will be null",
"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
},
"se_results_count": {
"type": "integer",
"description": "the total number of results",
"format": "int64",
"nullable": true
},
"items_count": {
"type": "integer",
"description": "the number of items in the results array",
"format": "int64",
"nullable": true
},
"items": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppStoreSearchOrganic"
}
],
"nullable": true
},
"description": "found apps",
"nullable": true
}
}
},
"AppStoreSearchOrganic": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "type of element",
"nullable": true
},
"rank_group": {
"type": "integer",
"description": "position within a group of elements with identical type values\npositions of elements with different type values are omitted from rank_group",
"nullable": true
},
"rank_absolute": {
"type": "integer",
"description": "absolute rank in SERP\nabsolute position among all the elements in SERP",
"nullable": true
},
"position": {
"type": "string",
"description": "the alignment of the element in SERP\ncan take the following values:\nleft, right",
"nullable": true
},
"app_id": {
"type": "string",
"description": "id of the app",
"nullable": true
},
"title": {
"type": "string",
"description": "title of the app",
"nullable": true
},
"url": {
"type": "string",
"description": "URL to the app page on App Store",
"nullable": true
},
"icon": {
"type": "string",
"description": "URL to the app icon",
"nullable": true
},
"reviews_count": {
"type": "integer",
"description": "the total number of reviews of the app",
"format": "int64",
"nullable": true
},
"rating": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/RatingInfo"
}
],
"description": "average rating of the app",
"nullable": true
},
"is_free": {
"type": "boolean",
"description": "indicates whether the app is free",
"nullable": true
},
"price": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/PriceInfo"
}
],
"description": "price of the app",
"nullable": true
}
}
},
"PriceInfo": {
"type": "object",
"properties": {
"current": {
"type": "number",
"description": "current price\nindicates the current price of the product or service featured in the result",
"format": "double",
"nullable": true
},
"regular": {
"type": "number",
"description": "regular price\nindicates the regular price of the product or service with no discounts applied",
"format": "double",
"nullable": true
},
"max_value": {
"type": "number",
"description": "the maximum price\nthe maximum price of the product or service as indicated in the result",
"format": "double",
"nullable": true
},
"currency": {
"type": "string",
"description": "currency of the listed price\nISO code of the currency applied to the price",
"nullable": true
},
"is_price_range": {
"type": "boolean",
"description": "price is provided as a range\nindicates whether a price is provided in a range",
"nullable": true
},
"displayed_price": {
"type": "string",
"description": "price string in the result\nraw price string as provided in the result",
"nullable": true
}
}
},
"AppDataAppleCategoriesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppDataAppleCategoriesTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"AppDataAppleCategoriesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppDataAppleCategoriesResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"AppDataAppleCategoriesResultInfo": {
"type": "object",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string",
"nullable": true
},
"description": "contains full list of supported app categories",
"nullable": true
}
}
},
"AppDataAppleAppReviewsTaskPostRequestInfo": {
"type": "object",
"properties": {
"app_id": {
"type": "string",
"description": "id of the app\nrequired field\nID of the mobile application on App Store;\nyou can find the ID in the URL of every app listed on App Store;\nexample:\nin the URL https://apps.apple.com/us/app/id835599320\nthe id is 835599320"
},
"location_name": {
"type": "string",
"description": "full name of search engine location\nrequired field if you don\u2019t specify location_code\nif you use this field, you don\u2019t 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 https://api.dataforseo.com/v3/app_data/apple/locations\nexample:\nWest Los Angeles,California,United States",
"nullable": true
},
"location_code": {
"type": "integer",
"description": "search engine location code\nrequired field if you don\u2019t specify location_name\nif you use this field, you don\u2019t need to specify location_name\nyou can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations\nexample:\n9061121",
"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 languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages\nexample:\nEnglish",
"nullable": true
},
"language_code": {
"type": "string",
"description": "search engine 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 languages with their language_code\u00a0by making a separate request to https://api.dataforseo.com/v3/app_data/apple/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
},
"depth": {
"type": "integer",
"description": "parsing depth\noptional field\nnumber of reviews to be returned in the API response;\nwe strongly recommend setting the parsing depth in the multiples of 50, because our system processes 50 reviews in a row;\ndefault value: 50;\nmaximum value: 500;\nYour account will be billed per each SERP containing up to 50 results;\nSetting depth above 50 may result in additional charges if the search engine returns more than 50 results;\nThe cost can be calculated on the Pricing page.",
"nullable": true
},
"sort_by": {
"type": "string",
"description": "results sorting parameters\noptional field\nyou can use this field to sort the results;\npossible types of sorting:\nmost_recent \u2014 sort by the most recent reviews;\nmost_helpful \u2014 sort by the most relevant reviews;\ndefault rule: most_helpful",
"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\nrequired field if you specify postback_url\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": [
{
"app_id": "835599320",
"location_code": 2840,
"language_code": "en",
"depth": 200
}
]
},
"AppDataAppleLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppDataAppleLanguagesTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"AppDataAppleLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppDataAppleLanguagesResultInfo"
}
],
"nullable": true
},
"description": "array of results",
"nullable": true
}
}
}
]
},
"AppDataAppleLanguagesResultInfo": {
"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
}
}
},
"AppDataIdListRequestInfo": {
"type": "object",
"properties": {
"datetime_from": {
"type": "string",
"description": "start time for filtering results\nrequired field\nif include_metadata is set to true, maximum value: a month from current datetime;\nif include_metadata is set to false, maximum value: six months from current datetime;\nmust be specified in the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2023-01-15 12:57:46 +00:00"
},
"datetime_to": {
"type": "string",
"description": "finish time for filtering results\nrequired field\nmaximum value: current datetime;\nmust be specified in the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2023-01-31 13:57:46 +00:00"
},
"limit": {
"type": "integer",
"description": "the maximum number of returned task IDs\noptional field\ndefault value: 1000\nmaximum value: 1000",
"nullable": true
},
"offset": {
"type": "integer",
"description": "offset in the results array of returned task IDs\noptional field\ndefault value: 0\nif you specify the 10 value, the first ten tasks in the results array will be omitted",
"nullable": true
},
"sort": {
"type": "string",
"description": "sorting by task execution time\noptional field\npossible values: \"asc\", \"desc\"\ndefault value: \"asc\"",
"nullable": true
},
"include_metadata": {
"type": "boolean",
"description": "include task metadata in the respond\noptional field\ndefault value: false",
"nullable": true
}
},
"example": [
{
"datetime_from": "2026-04-12 04:39:39 +00:00",
"datetime_to": "2026-04-14 04:39:39 +00:00",
"limit": 100,
"offset": 0,
"sort": "desc",
"include_metadata": true
}
]
},
"AppDataAppleAppListingsCategoriesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/AppDataAppleAppListingsCategoriesTaskInfo"
}
],
"nullable": true
},
"description": "array of tasks",
"nullable": true
}
}
}
]
},
"AppDataAppleAppListingsCategoriesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"oneOf": [
{
# --- truncated at 32 KB (193 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dataforseo/refs/heads/main/json-schema/dataforseo-app-data-schema.json