SocialCrawl
Unified schema

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

FieldTypeNullableDescription
idstringNoStore app ID (Google Play package name / App Store numeric id)
storestringNoApp marketplace ("google_play" or "app_store")
urlstringYesURL of the app's store page.
titlestringYesApp title
subtitlestringYesApp Store marketing subtitle under the app name. Absent on Google Play.
iconstringYesURL of the app icon.
descriptionstringYesFull store description. Present on app detail, null on search and chart rows.
developer.idstringYesThe store's id for the developer.
developer.namestringYesDeveloper or publisher name.
developer.urlstringYesURL of the developer's page in the store.
developer.emailstringYesContact email the developer published. Google Play only.
developer.addressstringYesPostal address the developer published. Google Play only.
developer.websitestringYesThe developer's own website. Google Play only.
rating.valuenumberYesAverage rating from 0 to the rating max.
rating.maxnumberYesHighest possible rating value, normally 5.
rating.countnumberYesHow many ratings the average is based on.
price.currentnumberYesCurrent price in the price currency. 0 for a free app.
price.originalnumberYesRegular price before any discount, in the price currency.
price.currencystringYesCurrency code of the price. Often null on the App Store.
price.is_freebooleanYesWhether the app is free to download.
price.displayedstringYesPrice exactly as the store shows it, for example '$4.99' or 'Free'.
reviews_countnumberYesNumber of written reviews.
categorystringYesThe app's main store category.
categoriesstring[]YesExtra categories the app is listed under. App Store only.
installs.displaystringYesInstall count as the store prints it, for example '1,000,000,000+'. Google Play only.
installs.countnumberYesInstall count as a number. Google Play only, null on the App Store.
versionstringYesLatest version string.
minimum_os_versionstringYesLowest operating system version the app runs on.
sizestringYesDownload size as the store prints it.
released_atstring or numberYesWhen 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_atstring or numberYesWhen 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_notesstringYesThe 'what's new' text of the latest release.
image_urlsstring[]YesScreenshot URLs
video_urlsstring[]YesPreview video URLs from the store page. Google Play only.
languagesstring[]YesLanguages the app supports. App Store only.
advisoriesstring[]YesApple age/content advisories (null on Google)
genresstring[]YesGoogle Play genres (null on Apple)
tagsstring[]YesChart tags the store attaches to the app. Google Play only.
similar_appsobject[]YesApps the store lists as similar.
more_by_developerobject[]YesOther apps from the same developer.
ranknumberYes1-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.

FieldTypeNullableDescription
ext.appdata.typestringNoThe kind of row the source returned.
ext.appdata.rank_groupnumberNoPosition within the group.
ext.appdata.rank_absolutenumberNoPosition among all rows.
ext.appdata.positionstringNoWhere the row sits in the source's layout.
ext.appdata.app_idstringNoThe app's id in the store.
ext.appdata.titlestringNoThe app's name.
ext.appdata.subtitlestringNoThe app's subtitle.
ext.appdata.urlstringNoLink to the app's store page.
ext.appdata.iconstringNoLink to the app's icon.
ext.appdata.descriptionstringNoThe app's description.
ext.appdata.reviews_countnumberYesHow many reviews the app has.
ext.appdata.rating.rating_typestringNoThe rating scale's label, such as Max5.
ext.appdata.rating.valuenumberNoThe rating.
ext.appdata.rating.votes_countnumberYesHow many ratings it is based on.
ext.appdata.rating.rating_maxnumberNoThe top of the scale.
ext.appdata.price.currentnumberNoCurrent price.
ext.appdata.price.regularnumberYesRegular price.
ext.appdata.price.max_valuenumberYesTop of the price range.
ext.appdata.price.currencystringNoISO 4217 currency code.
ext.appdata.price.is_price_rangebooleanNoTrue when the price is a range.
ext.appdata.price.displayed_pricestringYesPrice as displayed.
ext.appdata.is_freebooleanNoTrue when the app is free.
ext.appdata.main_categorystringYesThe app's main category.
ext.appdata.categoriesstring[]YesAll categories the app is in.
ext.appdata.languagesstring[]NoLanguages the app supports.
ext.appdata.advisoriesstring[]NoContent advisories, such as age ratings.
ext.appdata.developerstringNoThe developer's name.
ext.appdata.developer_idstringNoThe developer's id in the store.
ext.appdata.developer_urlstringYesLink to the developer's store page.
ext.appdata.developer_websitestringNoThe developer's own website.
ext.appdata.developer_emailstringNoThe developer's contact email, as the store lists it.
ext.appdata.developer_addressstringNoThe developer's postal address, as the store lists it.
ext.appdata.versionstringYesCurrent version.
ext.appdata.minimum_os_versionstringYesMinimum OS version required.
ext.appdata.sizestringYesDownload size, such as 287.4 MB.
ext.appdata.released_datestringYesFirst release date, ISO 8601.
ext.appdata.last_update_datestringNoLast update date, ISO 8601.
ext.appdata.time_updatestringNoWhen the listing was last refreshed in the source's database.
ext.appdata.update_notesstringYesRelease notes of the latest version.
ext.appdata.imagesstring[]NoLinks to the app's screenshots.
ext.appdata.videosstring[]YesLinks to the app's preview videos.
ext.appdata.similar_appsobject[]NoApps the store suggests as similar.
ext.appdata.more_apps_by_developerobject[]YesOther apps by the same developer.
ext.appdata.installsstringNoInstall band, such as 1,000,000,000+.
ext.appdata.installs_countnumberNoInstall count as a number.
ext.appdata.genresstring[]NoGenres the app is listed under.
ext.appdata.tagsstring[]NoTags and chart badges the store shows.
ext.appdata.category_drift_probebooleanNoAn 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.

Platformurltitlesubtitleicondescriptiondeveloper.iddeveloper.namedeveloper.urldeveloper.emaildeveloper.addressdeveloper.websiterating.value
Apple App Storeyesyesyesyesyesyesyesyesyesyesyesyes
Google Playyesyesyesyesyesyesyesyesyesyesyesyes

Machine-readable schema

Validate responses programmatically against the JSON Schema (2020-12):

/schemas/app.json

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:

Apple App Store · Google Play

See how the same fields map to each platform's raw upstream names in the cross-platform field equivalence table.

On this page