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 | |
title | string | Yes | |
text | string | Yes | Full review body |
rating.value | number | Yes | |
rating.max | number | Yes | |
author.name | string | Yes | |
author.avatar_url | string | Yes | |
author.url | string | Yes | |
author.location | string | Yes | |
author.reviews_count | number | Yes | |
helpful_votes | number | Yes | Helpful-vote count (Amazon; null elsewhere) |
verified | boolean | Yes | Verified-purchase flag (Amazon; null elsewhere) |
source | string | Yes | |
language | string | Yes | |
original_language | string | Yes | |
translated | boolean | Yes | |
images | string[] | Yes | |
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 | object | Yes | |
ext.tiktokshop | object | Yes | |
ext.naver.visit_count | number | Yes | |
ext.naver.verified_by | string | Yes | |
ext.naver.treatment | string | Yes | |
ext.naver.view_count | number | Yes | |
ext.naver.keywords | string[] | Yes | |
ext.naver.dedupe_key | string | Yes |
Platform availability
19 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 | author.location | rating.max | url | author.avatar_url | helpful_votes | author.reviews_count | author.url | language | title | verified | images | entity_id |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| AliExpress | yes | yes | ||||||||||
| Amazon | yes | yes | yes | yes | yes | yes | ||||||
| Apple App Store | yes | yes | yes | yes | yes | |||||||
| G2 | yes | yes | ||||||||||
| yes | yes | yes | yes | yes | yes | |||||||
| Google Play | yes | yes | yes | yes | yes | |||||||
| Google Shopping | yes | yes | yes | yes | ||||||||
| Home Depot | yes | yes | yes | yes | ||||||||
| Klarna | yes | yes | yes | yes | yes | yes | ||||||
| Kohl's | yes | yes | yes | yes | yes | |||||||
| Naver | yes | yes | yes | yes | yes | yes | yes | |||||
| Sephora | yes | yes | yes | yes | ||||||||
| Target | yes | yes | yes | yes | yes | yes | ||||||
| TikTok Shop | yes | yes | yes | yes | yes | yes | ||||||
| Tripadvisor | yes | yes | yes | yes | yes | yes | yes | yes | ||||
| Trustpilot | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| Walmart | yes | yes | yes | |||||||||
| Wayfair | yes | yes | yes | yes | ||||||||
| Yelp | 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 Review / ReviewList archetype return this shape:
AliExpress · Amazon · Apple App Store · G2 · 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.