SocialCrawl
Unified schema

Review schema

The unified SocialCrawl review 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 review gives you this exact shape, whatever the source platform. Write your parser once and the same code reads review data from every platform below. That is the unified schema: one contract instead of a dozen raw upstream formats.

Field reference

FieldTypeNullableDescription
idstringNoReview ID (parsed from the review URL when not first-class)
entity_idstringYesID of the reviewed entity (e.g. the Amazon ASIN)
urlstringYesURL of the review.
titlestringYesReview headline.
textstringYesFull review body
rating.valuenumberYesThe rating the reviewer gave.
rating.maxnumberYesHighest possible rating value, normally 5.
author.namestringYesReviewer name.
author.avatar_urlstringYesURL of the reviewer's avatar.
author.urlstringYesURL of the reviewer's profile.
author.locationstringYesWhere the reviewer says they are from.
author.reviews_countnumberYesNumber of reviews the reviewer has written.
helpful_votesnumberYesHelpful-vote count (Amazon; null elsewhere)
verifiedbooleanYesVerified-purchase flag (Amazon; null elsewhere)
sourcestringYesWhere the review was originally posted, as a provider name or retailer domain.
languagestringYesLanguage code of the review text.
original_languagestringYesLanguage the review was written in, when the text shown is a translation.
translatedbooleanYesWhether the text shown is a translation of the original.
imagesstring[]YesURLs of images attached to the review.
responsesobject[]YesOwner/brand/management replies to the review, each {id, author, text, published_at} with published_at as an ISO 8601 UTC string (REL-07.6).
published_atstring or numberYesReview creation timestamp as an ISO 8601 UTC string (REL-07.6). Upstreams that send only a calendar date land on midnight UTC. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under review.ext.published_at_epoch.

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.idstringNoThe review's id in the store.
ext.appdata.versionstringYesApp version the review was written for.
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.timestampstringNoWhen the review was posted, ISO 8601.
ext.appdata.titlestringYesThe review's title.
ext.appdata.review_textstringNoThe review text.
ext.appdata.user_profile.profile_namestringNoThe reviewer's name.
ext.appdata.user_profile.profile_image_urlstringYesLink to the reviewer's picture.
ext.appdata.entity_idstringNoId of the app the review is about.
ext.appdata.helpful_countnumberYesHow many people found the review helpful.
ext.appdata.responsesobject[]YesDeveloper replies to the review.
ext.tiktokshop.reviewer_idstringNoThe reviewer's id.
ext.tiktokshop.is_incentivized_reviewbooleanNoTrue when the reviewer was given an incentive.
ext.tiktokshop.sku_specificationstringNoThe variant the reviewer bought.
ext.naver.visit_countnumberYesWhich visit this was for the reviewer, counting from 1.
ext.naver.verified_bystringYesThe proof of visit Naver recorded, such as a receipt, a payment or a booking.
ext.naver.treatmentstringYesThe treatment or menu item the visit was for.
ext.naver.view_countnumberYesHow many times the review was viewed.
ext.naver.keywordsstring[]YesKeyword chips attached to the review.
ext.naver.dedupe_keystringYesA key that is the same for one review from either source (place, visit day, nickname and the start of the text).
ext.traveler_typestringYes
ext.stay_check_instringYes
ext.stay_check_outstringYes
ext.stay_nightsnumberYes
ext.room_typestringYes
ext.google.local_guidebooleanYesTrue when the reviewer is a Google Local Guide.
ext.google.local_guide_levelnumberYesThe reviewer's Local Guide level, 1 to 10. Null when they are not a Local Guide.
ext.google.author_idstringYesThe reviewer's Google contributor id.
ext.google.edited_atstringYesWhen the reviewer last edited the review, ISO 8601. Null when it was never edited. Newest-first order sorts by the later of this and published_at.
ext.google.aspectsanyNoGoogle's aspect ratings for the visit, as the reviewer gave them: numbers from 1 to 5 for food, service and atmosphere, and short text such as pricePerPerson, mealType or orderType. The keys depend on the kind of place. Null when the reviewer rated none.
ext.google.original_textstringYesThe review as written. It differs from text only when the review was in another language than the one asked for and text holds the translation. Null on a stars-only review.

Platform availability

22 platforms return the Review shape. id 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.

Platformrating.maxauthor.locationauthor.avatar_urlurllanguagehelpful_votestitleauthor.reviews_countauthor.urlverifiedimagesresponses
Airbnbyesyesyesyesyes
AliExpressyesyes
Amazonyesyesyesyesyes
Apple App Storeyesyesyesyes
Booking.comyesyesyesyesyesyes
G2yesyes
Goodreadsyesyesyesyesyesyes
Googleyesyesyesyesyesyesyes
Google Playyesyesyesyes
Google Shoppingyesyesyes
Home Depotyesyesyes
Klarnayesyesyesyesyes
Kohl'syesyesyesyes
Naveryesyesyesyesyesyesyes
Sephorayesyesyes
Targetyesyesyesyesyes
TikTok Shopyesyesyesyesyes
Tripadvisoryesyesyesyesyesyesyes
Trustpilotyesyesyesyesyesyesyesyesyes
Walmartyesyes
Wayfairyesyesyes
Yelpyesyesyesyes

Machine-readable schema

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

/schemas/review.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 Review / ReviewList archetype return this shape:

Airbnb · AliExpress · Amazon · Apple App Store · Booking.com · G2 · Goodreads · Google · Google Play · Google Shopping · Home Depot · Klarna · Kohl's · Naver · Sephora · Target · TikTok Shop · Tripadvisor · Trustpilot · Walmart · Wayfair · Yelp

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

On this page