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.
Review schema
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 | integer | Yes | |
rating.max | integer | Yes | |
author.name | string | Yes | |
author.avatar_url | string | Yes | |
author.url | string | Yes | |
author.location | string | Yes | |
author.reviews_count | integer | Yes | |
helpful_votes | integer | 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 | |
published_at | string or integer | Yes | Union: string | integer | null |
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 | string | Yes | |
ext.tiktokshop | string | Yes |
Platform availability
11 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 | helpful_votes | url | verified | author.avatar_url | author.location | author.url | language | rating.max | author.reviews_count | original_language | images | source |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Amazon | yes | yes | yes | yes | ||||||||
| Apple App Store | yes | yes | yes | |||||||||
| yes | yes | yes | yes | yes | yes | |||||||
| Google Play | yes | yes | yes | |||||||||
| Google Shopping | yes | yes | yes | |||||||||
| Home Depot | yes | yes | yes | yes | ||||||||
| Target | 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 | ||||
| Walmart | 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:
Amazon · Apple App Store · Google · Google Play · Google Shopping · Home Depot · Target · TikTok Shop · Tripadvisor · Trustpilot · Walmart
See how the same fields map to each platform's raw upstream names in the cross-platform field equivalence table.