App schema
The unified SocialCrawl app-store listing schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.
Every SocialCrawl endpoint that returns a app-store listing gives you this exact shape, whatever the source platform. Write your parser once and the same code reads app data from every platform below. That is the unified schema: one contract instead of a dozen raw upstream formats.
Field reference
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | No | Store app ID (Google Play package name / App Store numeric id) |
store | string | No | App marketplace ("google_play" or "app_store") |
url | string | Yes | URL of the app's store page. |
title | string | Yes | App title |
subtitle | string | Yes | App Store marketing subtitle under the app name. Absent on Google Play. |
icon | string | Yes | URL of the app icon. |
description | string | Yes | Full store description. Present on app detail, null on search and chart rows. |
developer.id | string | Yes | The store's id for the developer. |
developer.name | string | Yes | Developer or publisher name. |
developer.url | string | Yes | URL of the developer's page in the store. |
developer.email | string | Yes | Contact email the developer published. Google Play only. |
developer.address | string | Yes | Postal address the developer published. Google Play only. |
developer.website | string | Yes | The developer's own website. Google Play only. |
rating.value | number | Yes | Average rating from 0 to the rating max. |
rating.max | number | Yes | Highest possible rating value, normally 5. |
rating.count | number | Yes | How many ratings the average is based on. |
price.current | number | Yes | Current price in the price currency. 0 for a free app. |
price.original | number | Yes | Regular price before any discount, in the price currency. |
price.currency | string | Yes | Currency code of the price. Often null on the App Store. |
price.is_free | boolean | Yes | Whether the app is free to download. |
price.displayed | string | Yes | Price exactly as the store shows it, for example '$4.99' or 'Free'. |
reviews_count | number | Yes | Number of written reviews. |
category | string | Yes | The app's main store category. |
categories | string[] | Yes | Extra categories the app is listed under. App Store only. |
installs.display | string | Yes | Install count as the store prints it, for example '1,000,000,000+'. Google Play only. |
installs.count | number | Yes | Install count as a number. Google Play only, null on the App Store. |
version | string | Yes | Latest version string. |
minimum_os_version | string | Yes | Lowest operating system version the app runs on. |
size | string | Yes | Download size as the store prints it. |
released_at | string or number | Yes | When the app was first released. A date string or an epoch number as the store gives it, and null when the store does not say, which is always the case on the App Store. |
updated_at | string or number | Yes | When the latest version was published. A date string or an epoch number as the store gives it, and null when the store does not say. |
update_notes | string | Yes | The 'what's new' text of the latest release. |
image_urls | string[] | Yes | Screenshot URLs |
video_urls | string[] | Yes | Preview video URLs from the store page. Google Play only. |
languages | string[] | Yes | Languages the app supports. App Store only. |
advisories | string[] | Yes | Apple age/content advisories (null on Google) |
genres | string[] | Yes | Google Play genres (null on Apple) |
tags | string[] | Yes | Chart tags the store attaches to the app. Google Play only. |
similar_apps | object[] | Yes | Apps the store lists as similar. |
more_by_developer | object[] | Yes | Other apps from the same developer. |
rank | number | Yes | 1-based position in the store chart (app-list) or the keyword results (app-search); absent on app-info and app-listings-search |
Extension fields (ext)
Platform-specific passthrough. Each field is present only on the platforms that expose it and is absent everywhere else, so treat every ext.* field as optional. These carry the richer, per-platform signals the unified leaves cannot hold, and the join keys that chain endpoints together.
| Field | Type | Nullable | Description |
|---|---|---|---|
ext.appdata.type | string | No | The kind of row the source returned. |
ext.appdata.rank_group | number | No | Position within the group. |
ext.appdata.rank_absolute | number | No | Position among all rows. |
ext.appdata.position | string | No | Where the row sits in the source's layout. |
ext.appdata.app_id | string | No | The app's id in the store. |
ext.appdata.title | string | No | The app's name. |
ext.appdata.subtitle | string | No | The app's subtitle. |
ext.appdata.url | string | No | Link to the app's store page. |
ext.appdata.icon | string | No | Link to the app's icon. |
ext.appdata.description | string | No | The app's description. |
ext.appdata.reviews_count | number | Yes | How many reviews the app has. |
ext.appdata.rating.rating_type | string | No | The rating scale's label, such as Max5. |
ext.appdata.rating.value | number | No | The rating. |
ext.appdata.rating.votes_count | number | Yes | How many ratings it is based on. |
ext.appdata.rating.rating_max | number | No | The top of the scale. |
ext.appdata.price.current | number | No | Current price. |
ext.appdata.price.regular | number | Yes | Regular price. |
ext.appdata.price.max_value | number | Yes | Top of the price range. |
ext.appdata.price.currency | string | No | ISO 4217 currency code. |
ext.appdata.price.is_price_range | boolean | No | True when the price is a range. |
ext.appdata.price.displayed_price | string | Yes | Price as displayed. |
ext.appdata.is_free | boolean | No | True when the app is free. |
ext.appdata.main_category | string | Yes | The app's main category. |
ext.appdata.categories | string[] | Yes | All categories the app is in. |
ext.appdata.languages | string[] | No | Languages the app supports. |
ext.appdata.advisories | string[] | No | Content advisories, such as age ratings. |
ext.appdata.developer | string | No | The developer's name. |
ext.appdata.developer_id | string | No | The developer's id in the store. |
ext.appdata.developer_url | string | Yes | Link to the developer's store page. |
ext.appdata.developer_website | string | No | The developer's own website. |
ext.appdata.developer_email | string | No | The developer's contact email, as the store lists it. |
ext.appdata.developer_address | string | No | The developer's postal address, as the store lists it. |
ext.appdata.version | string | Yes | Current version. |
ext.appdata.minimum_os_version | string | Yes | Minimum OS version required. |
ext.appdata.size | string | Yes | Download size, such as 287.4 MB. |
ext.appdata.released_date | string | Yes | First release date, ISO 8601. |
ext.appdata.last_update_date | string | No | Last update date, ISO 8601. |
ext.appdata.time_update | string | No | When the listing was last refreshed in the source's database. |
ext.appdata.update_notes | string | Yes | Release notes of the latest version. |
ext.appdata.images | string[] | No | Links to the app's screenshots. |
ext.appdata.videos | string[] | Yes | Links to the app's preview videos. |
ext.appdata.similar_apps | object[] | No | Apps the store suggests as similar. |
ext.appdata.more_apps_by_developer | object[] | Yes | Other apps by the same developer. |
ext.appdata.installs | string | No | Install band, such as 1,000,000,000+. |
ext.appdata.installs_count | number | No | Install count as a number. |
ext.appdata.genres | string[] | No | Genres the app is listed under. |
ext.appdata.tags | string[] | No | Tags and chart badges the store shows. |
ext.appdata.category_drift_probe | boolean | No | An internal consistency marker the source row can carry. It has no meaning for callers and can be ignored. |
Platform availability
2 platforms return the App shape. id, store are never null on any platform. The fields below vary: yes means the platform populates it (the value may still be null); a blank means the platform never provides it, so it is always null.
| Platform | url | title | subtitle | icon | description | developer.id | developer.name | developer.url | developer.email | developer.address | developer.website | rating.value |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Apple App Store | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| Google Play | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
Machine-readable schema
Validate responses programmatically against the JSON Schema (2020-12):
Point a validator (Ajv, jsonschema, or your framework's) at that URL, or hand it to an agent so it can check the shape without a live call.
Returned by
Endpoints with the App / AppList archetype return this shape:
See how the same fields map to each platform's raw upstream names in the cross-platform field equivalence table.
Place schema
The unified SocialCrawl place or business schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.
Quote schema
The unified SocialCrawl financial quote schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.
