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
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | No | Review ID (parsed from the review URL when not first-class) |
entity_id | string | Yes | ID of the reviewed entity (e.g. the Amazon ASIN) |
url | string | Yes | URL of the review. |
title | string | Yes | Review headline. |
text | string | Yes | Full review body |
rating.value | number | Yes | The rating the reviewer gave. |
rating.max | number | Yes | Highest possible rating value, normally 5. |
author.name | string | Yes | Reviewer name. |
author.avatar_url | string | Yes | URL of the reviewer's avatar. |
author.url | string | Yes | URL of the reviewer's profile. |
author.location | string | Yes | Where the reviewer says they are from. |
author.reviews_count | number | Yes | Number of reviews the reviewer has written. |
helpful_votes | number | Yes | Helpful-vote count (Amazon; null elsewhere) |
verified | boolean | Yes | Verified-purchase flag (Amazon; null elsewhere) |
source | string | Yes | Where the review was originally posted, as a provider name or retailer domain. |
language | string | Yes | Language code of the review text. |
original_language | string | Yes | Language the review was written in, when the text shown is a translation. |
translated | boolean | Yes | Whether the text shown is a translation of the original. |
images | string[] | Yes | URLs of images attached to the review. |
responses | object[] | Yes | Owner/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_at | string or number | Yes | Review 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.
| 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.id | string | No | The review's id in the store. |
ext.appdata.version | string | Yes | App version the review was written for. |
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.timestamp | string | No | When the review was posted, ISO 8601. |
ext.appdata.title | string | Yes | The review's title. |
ext.appdata.review_text | string | No | The review text. |
ext.appdata.user_profile.profile_name | string | No | The reviewer's name. |
ext.appdata.user_profile.profile_image_url | string | Yes | Link to the reviewer's picture. |
ext.appdata.entity_id | string | No | Id of the app the review is about. |
ext.appdata.helpful_count | number | Yes | How many people found the review helpful. |
ext.appdata.responses | object[] | Yes | Developer replies to the review. |
ext.tiktokshop.reviewer_id | string | No | The reviewer's id. |
ext.tiktokshop.is_incentivized_review | boolean | No | True when the reviewer was given an incentive. |
ext.tiktokshop.sku_specification | string | No | The variant the reviewer bought. |
ext.naver.visit_count | number | Yes | Which visit this was for the reviewer, counting from 1. |
ext.naver.verified_by | string | Yes | The proof of visit Naver recorded, such as a receipt, a payment or a booking. |
ext.naver.treatment | string | Yes | The treatment or menu item the visit was for. |
ext.naver.view_count | number | Yes | How many times the review was viewed. |
ext.naver.keywords | string[] | Yes | Keyword chips attached to the review. |
ext.naver.dedupe_key | string | Yes | A key that is the same for one review from either source (place, visit day, nickname and the start of the text). |
ext.traveler_type | string | Yes | |
ext.stay_check_in | string | Yes | |
ext.stay_check_out | string | Yes | |
ext.stay_nights | number | Yes | |
ext.room_type | string | Yes | |
ext.google.local_guide | boolean | Yes | True when the reviewer is a Google Local Guide. |
ext.google.local_guide_level | number | Yes | The reviewer's Local Guide level, 1 to 10. Null when they are not a Local Guide. |
ext.google.author_id | string | Yes | The reviewer's Google contributor id. |
ext.google.edited_at | string | Yes | When 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.aspects | any | No | Google'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_text | string | Yes | The 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.
| Platform | rating.max | author.location | author.avatar_url | url | language | helpful_votes | title | author.reviews_count | author.url | verified | images | responses |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Airbnb | yes | yes | yes | yes | yes | |||||||
| AliExpress | yes | yes | ||||||||||
| Amazon | yes | yes | yes | yes | yes | |||||||
| Apple App Store | yes | yes | yes | yes | ||||||||
| Booking.com | yes | yes | yes | yes | yes | yes | ||||||
| G2 | yes | yes | ||||||||||
| Goodreads | yes | yes | yes | yes | yes | yes | ||||||
| yes | yes | yes | yes | yes | yes | yes | ||||||
| Google Play | yes | yes | yes | yes | ||||||||
| Google Shopping | yes | yes | yes | |||||||||
| Home Depot | yes | yes | yes | |||||||||
| Klarna | yes | yes | yes | yes | yes | |||||||
| Kohl's | yes | yes | yes | yes | ||||||||
| Naver | yes | yes | yes | yes | yes | yes | yes | |||||
| Sephora | yes | yes | yes | |||||||||
| Target | yes | yes | yes | yes | yes | |||||||
| TikTok Shop | yes | yes | yes | yes | yes | |||||||
| Tripadvisor | yes | yes | yes | yes | yes | yes | yes | |||||
| Trustpilot | yes | yes | yes | yes | yes | yes | yes | yes | yes | |||
| Walmart | yes | yes | ||||||||||
| Wayfair | yes | yes | yes | |||||||||
| Yelp | 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 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.
Product schema
The unified SocialCrawl product schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.
Seller schema
The unified SocialCrawl seller offer schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.
