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.
Every SocialCrawl endpoint that returns a product gives you this exact shape, whatever the source platform. Write your parser once and the same code reads product 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 | Platform product ID (Amazon ASIN / Google Shopping product id) |
url | string | Yes | Direct URL to the product page |
title | string | Yes | Product title |
description | string | Yes | |
seller | string | Yes | |
brand | string | Yes | Brand name (cleaned). Null when the platform exposes a seller instead. |
price.current | integer | Yes | |
price.original | integer | Yes | |
price.currency | string | Yes | |
rating.average | integer | Yes | |
rating.count | integer | Yes | |
image_urls | string or string[] | Yes | Primary image URL, or an array of image URLs for products with a gallery. |
availability | string | Yes | Stock/availability string when surfaced |
reviews_count | integer | Yes | |
features | string[] | Yes | |
specifications | object[] | Yes | |
variations | object[] | Yes |
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.gid | string | Yes | |
ext.data_docid | string | Yes | |
ext.pvf | string | Yes | |
ext.seller_id | string | Yes | |
ext.sold_count | integer | Yes | |
ext.catalog_id | string | Yes | |
ext.requested_id | string | Yes | |
ext.rating_distribution.star_1 | integer | Yes | |
ext.rating_distribution.star_2 | integer | Yes | |
ext.rating_distribution.star_3 | integer | Yes | |
ext.rating_distribution.star_4 | integer | Yes | |
ext.rating_distribution.star_5 | integer | Yes | |
ext.store_inventory | object[] | Yes | |
ext.promotion.label | string | Yes | |
ext.promotion.amount_off | integer | Yes | |
ext.promotion.percent_off | integer | Yes | |
ext.price_note | string | Yes | |
ext.condition | string | Yes | |
ext.available_quantity | integer | Yes | |
ext.watchers | integer | Yes | |
ext.sold_at | string | Yes | |
ext.sold_caption | string | Yes | |
ext.buying_format | string | Yes | |
ext.seller_reputation.feedback_percentage | integer | Yes | |
ext.seller_reputation.feedback_count | integer | Yes | |
ext.seller_reputation.top_rated | boolean | Yes | |
ext.seller_reputation.items_sold | integer | Yes | |
ext.seller_reputation.joined | string | Yes | |
ext.seller_reputation.url | string | Yes | |
ext.seller_reputation.detailed_ratings.accurate_description | integer | Yes | |
ext.seller_reputation.detailed_ratings.reasonable_shipping_cost | integer | Yes | |
ext.seller_reputation.detailed_ratings.shipping_speed | integer | Yes | |
ext.seller_reputation.detailed_ratings.communication | integer | Yes | |
ext.g2 | string | Yes | |
ext.etsy | string | Yes | |
ext.sephora | string | Yes | |
ext.hm | string | Yes | |
ext.kohls | string | Yes | |
ext.gumtree | string | Yes | |
ext.sku_id | string | Yes | |
ext.aliexpress | string | Yes | |
ext.tiktokshop | string | Yes |
Platform availability
16 platforms return the Product 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 | image_urls | reviews_count | seller | price.currency | price.original | brand | description | price.current | rating.average | rating.count | availability | features |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| AliExpress | yes | yes | yes | yes | ||||||||
| Amazon | yes | yes | yes | yes | yes | yes | yes | yes | ||||
| eBay | yes | yes | yes | yes | yes | yes | yes | yes | yes | |||
| Etsy | yes | yes | yes | yes | yes | yes | yes | yes | yes | |||
| G2 | yes | yes | yes | yes | yes | yes | yes | |||||
| Google Shopping | yes | yes | yes | yes | yes | yes | yes | yes | yes | |||
| Gumtree | yes | yes | yes | yes | yes | |||||||
| H&M | yes | |||||||||||
| Home Depot | yes | yes | yes | yes | yes | yes | yes | yes | ||||
| Klarna | yes | yes | yes | yes | yes | yes | yes | yes | yes | |||
| Kohl's | yes | yes | ||||||||||
| Sephora | yes | yes | yes | yes | yes | |||||||
| Target | yes | yes | yes | yes | yes | yes | yes | |||||
| TikTok Shop | yes | yes | yes | yes | yes | yes | yes | yes | yes | |||
| Walmart | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| Wayfair | yes | yes | yes | yes | yes | 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 Product / ProductList archetype return this shape:
AliExpress · Amazon · eBay · Etsy · G2 · Google Shopping · Gumtree · H&M · Home Depot · Klarna · Kohl's · Sephora · Target · TikTok Shop · Walmart · Wayfair
See how the same fields map to each platform's raw upstream names in the cross-platform field equivalence table.