SocialCrawl
Unified schema

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

FieldTypeNullableDescription
idstringNoPlatform product ID (Amazon ASIN / Google Shopping product id)
urlstringYesDirect URL to the product page
titlestringYesProduct title
descriptionstringYesProduct description.
sellerstringYesName of the seller. Null where the source names none.
brandstringYesBrand name (cleaned). Null when the platform exposes a seller instead.
price.currentnumberYesCurrent price, in the price currency.
price.originalnumberYesPrice before any discount, in the price currency.
price.currencystringYesCurrency code of the price.
rating.averagenumberYesAverage rating, normally out of 5.
rating.countnumberYesNumber of ratings behind the average.
image_urlsstring or string[]YesPrimary image URL, or an array of image URLs for products with a gallery.
availabilitystringYesStock/availability string when surfaced
reviews_countnumberYesNumber of written reviews.
featuresstring[]YesFeature bullet points from the product page. Detail only.
specificationsobject[]YesSpecification rows from the product page. Detail only.
variationsobject[]YesOther variants of the product, such as colour or size. Detail only.

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.gidstringYesGoogle Shopping product group id used to chain from search to detail, reviews and sellers.
ext.data_docidstringYesGoogle Shopping identifier used to look up the product's detail, reviews and sellers.
ext.pvfstringYesGoogle Shopping identifier that goes with gid when looking up the product.
ext.seller_idstringYesThe seller's id on the retailer.
ext.sold_countnumberYesUnits sold, as the listing reports it.
ext.bought_past_monthnumberYesLower bound of the purchase badge, for example 10000 for '10K+ bought in past month'. Null when there is no count.
ext.bought_past_month_labelstringYesThe purchase badge text exactly as Amazon prints it.
ext.catalog_idstringYesWalmart's alphanumeric catalog id. product.id holds the numeric id from the URL.
ext.requested_idstringYesThe id you asked for, when the retailer rolled a variant up to its parent. Set only when it differs from product.id.
ext.rating_distribution.star_1numberYesReviews that gave 1 star.
ext.rating_distribution.star_2numberYesReviews that gave 2 stars.
ext.rating_distribution.star_3numberYesReviews that gave 3 stars.
ext.rating_distribution.star_4numberYesReviews that gave 4 stars.
ext.rating_distribution.star_5numberYesReviews that gave 5 stars.
ext.store_inventoryobject[]YesStock at individual stores or fulfilment points.
ext.promotion.labelstringYesThe retailer's own label, for example Clearance or Special Buys.
ext.promotion.amount_offnumberYesAmount off the original price, in the price currency.
ext.promotion.percent_offnumberYesPercentage off the original price.
ext.price_notestringYesWhy the retailer shows no price, for example 'see final price in cart'.
ext.conditionstringYesCondition of a marketplace listing, for example Used or Open Box.
ext.available_quantitynumberYesUnits the seller currently has listed. eBay only.
ext.watchersnumberYesPeople watching the listing. eBay only.
ext.sold_atstringYesWhen the listing sold, as a UTC midnight ISO 8601 time. Sold and completed searches only.
ext.sold_captionstringYesThe listing's sold ribbon text, for example 'Sold' with a date. Sold and completed searches only.
ext.buying_formatstringYesSale type of the listing: auction, buy_it_now or accepts_offers.
ext.seller_reputation.feedback_percentagenumberYesShare of the seller's feedback that is positive, as a percentage.
ext.seller_reputation.feedback_countnumberYesLifetime number of feedback ratings the seller received.
ext.seller_reputation.top_ratedbooleanYesWhether the marketplace gives the seller its top rated status.
ext.seller_reputation.items_soldnumberYesItems the seller has sold.
ext.seller_reputation.joinedstringYesWhen the seller joined the marketplace, as the marketplace prints it.
ext.seller_reputation.urlstringYesURL of the seller's page.
ext.seller_reputation.detailed_ratings.accurate_descriptionnumberYesScore for how accurately listings describe the item, up to 5.
ext.seller_reputation.detailed_ratings.reasonable_shipping_costnumberYesScore for how reasonable shipping costs are, up to 5.
ext.seller_reputation.detailed_ratings.shipping_speednumberYesScore for shipping speed, up to 5.
ext.seller_reputation.detailed_ratings.communicationnumberYesScore for the seller's communication, up to 5.
ext.g2.product_uuidstringNoG2's unique id for the product.
ext.g2.solution_typestringNoKind of solution, such as All-in-One.
ext.g2.ai_verifiedbooleanNoTrue when G2 verified the listing with AI.
ext.g2.g2_reviews_linkstringNoLink to the product's reviews on G2.
ext.g2.categoriesobject[]NoG2 categories the product is listed in.
ext.g2.comparisonsobject[]NoHead-to-head comparisons G2 offers.
ext.g2.alternativesobject[]NoAlternatives G2 suggests.
ext.g2.pricing_plansobject[]NoThe product's pricing plans.
ext.g2.pricing_details.free_trialbooleanNoTrue when a free trial exists.
ext.g2.pricing_details.overviewstringNoG2's summary of the pricing.
ext.g2.pricing_details.last_updatedstringNoWhen the pricing was last updated, as text.
ext.g2.pricing_details.faqsobject[]NoPricing questions and answers.
ext.g2.pricing_details.alternatives_pricingobject[]NoPricing of alternative products.
ext.g2.featuresobject[]NoFeature groups.
ext.g2.detailed_featuresobject[]NoFeature groups with a description per feature.
ext.g2.prosstring[]NoWhat reviewers like.
ext.g2.consstring[]NoWhat reviewers dislike.
ext.g2.pros_detailsobject[]NoWhat reviewers like, with evidence.
ext.g2.cons_detailsobject[]NoWhat reviewers dislike, with evidence.
ext.g2.integrations.countnumberNoHow many integrations G2 lists.
ext.g2.integrations.itemsobject[]NoThe integrations shown.
ext.etsy.is_handmadebooleanNoTrue when the seller marks the item handmade.
ext.etsy.favoritesnumberNoHow many people favourited the item.
ext.etsy.is_bestsellerbooleanNoTrue when Etsy marks the item a bestseller.
ext.etsy.is_top_ratedbooleanNoTrue when Etsy marks the item top rated.
ext.etsy.materialsstring[]NoMaterials the item is made of.
ext.etsy.taxonomy_pathstringNoEtsy's category path, dot-separated.
ext.etsy.when_madestringNoWhen the item was made, such as made_to_order.
ext.etsy.user_idstringNoThe seller's user id.
ext.sephora.skustringNoThe SKU.
ext.sephora.sizestringNoSize or volume, such as 3.3 oz/100 mL.
ext.sephora.ingredientsstringNoThe ingredient list as printed.
ext.sephora.loves_countnumberNoHow many shoppers loved the product.
ext.hm.colorstringNoThe colour name.
ext.hm.category_codestringNoH&M's category code.
ext.hm.sizesstring[]NoSizes on offer.
ext.hm.new_arrivalbooleanNoTrue when H&M marks the item a new arrival.
ext.kohls.colorsstring[]NoColours on offer.
ext.kohls.display_colorstringNoThe colour shown for the item.
ext.kohls.skustringNoThe SKU.
ext.kohls.coupon_eligiblebooleanNoTrue when store coupons apply.
ext.kohls.shipbooleanNoTrue when the item ships.
ext.gumtree.user_idstringNoThe seller's user id.
ext.gumtree.public_user_idstringNoThe seller's public id.
ext.gumtree.account_idstringNoThe seller's account id.
ext.gumtree.seller_typestringNoKind of seller, such as trade.
ext.gumtree.category_idstringNoThe category's id.
ext.gumtree.categorystringNoThe category's name.
ext.gumtree.locationstringNoWhere the item is.
ext.gumtree.location_idstringNoThe location's id.
ext.sku_idstringYesColour or size variant id. Shipping quotes need it beside the product id.
ext.aliexpress.commission_ratestringNoAffiliate commission rate, such as 7.0%.
ext.aliexpress.discountstringNoDiscount, such as 49%.
ext.aliexpress.categorystringNoTop-level category.
ext.aliexpress.subcategorystringNoSub-category.
ext.aliexpress.positive_ratestringNoShare of positive feedback, such as 90.8%.
ext.aliexpress.shop_urlstringNoLink to the seller's shop.
ext.tiktokshop.categorystringNoThe product's category.
ext.tiktokshop.category_idstringNoThe category's id.
ext.tiktokshop.discount_percentnumberNoDiscount as a percentage.
ext.tiktokshop.stocknumberNoUnits in stock.
ext.tiktokshop.seller_namestringNoThe seller's name.
ext.tiktokshop.seller_locationstringNoWhere the seller is based.
ext.tiktokshop.seller_ratingnumberNoThe seller's rating.
ext.tiktokshop.seller_products_countnumberNoHow many products the seller lists.
ext.tiktokshop.seller_followersnumberNoThe seller's follower count.
ext.tiktokshop.seller_sold_countnumberNoUnits the seller has sold.
ext.tiktokshop.shop_identitystringNoKind of shop, such as official.
ext.tiktokshop.shop_performance_percentilenumberNoShop performance percentile, 0 to 100.
ext.tiktokshop.positive_feedback_percentnumberNoShare of positive feedback, 0 to 100.
ext.tiktokshop.response_rate_24hnumberNoShare of buyers answered within 24 hours, 0 to 100.
ext.tiktokshop.free_shippingbooleanNoTrue when shipping is free.
ext.tiktokshop.shipping_feenumberNoShipping fee.
ext.tiktokshop.delivery_estimatestringNoEstimated delivery window, as text.
ext.tiktokshop.delivery_days_minnumberNoFewest days delivery takes.
ext.tiktokshop.delivery_days_maxnumberNoMost days delivery takes.
ext.tiktokshop.shop_idstringNoThe shop's id.
ext.tiktokshop.shop_namestringNoThe shop's name.
ext.tiktokshop.shop_urlstringNoLink to the shop.
ext.tiktokshop.shop_ratingnumberNoThe shop's rating.
ext.tiktokshop.shop_regionstringNoThe shop's country code.
ext.tiktokshop.shop_followersnumberNoThe shop's follower count.
ext.tiktokshop.shop_products_countnumberNoHow many products the shop lists.
ext.tiktokshop.shop_reviews_countnumberNoHow many reviews the shop has.
ext.tiktokshop.shop_sold_countnumberNoUnits the shop has sold.
ext.tiktokshop.shop_videos_countnumberNoHow many videos the shop has.
ext.tiktokshop.shop_logo_urlstringNoLink to the shop's logo.
ext.tiktokshop.trust_labelstringNoTikTok's trust badge, such as most_loved.
ext.tiktokshop.promotion_labelsstring[]NoPromotion badges on the product.

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.

Platformimage_urlsreviews_countsellerprice.currencyprice.originalbranddescriptionprice.currentrating.averagerating.countavailabilityfeatures
AliExpressyesyesyesyes
Amazonyesyesyesyesyesyesyesyes
eBayyesyesyesyesyesyesyesyesyes
Etsyyesyesyesyesyesyesyesyesyes
G2yesyesyesyesyesyesyes
Google Shoppingyesyesyesyesyesyesyesyesyes
Gumtreeyesyesyesyesyes
H&Myes
Home Depotyesyesyesyesyesyesyesyes
Klarnayesyesyesyesyesyesyesyesyes
Kohl'syesyes
Sephorayesyesyesyesyes
Targetyesyesyesyesyesyesyes
TikTok Shopyesyesyesyesyesyesyesyesyes
Walmartyesyesyesyesyesyesyesyesyesyes
Wayfairyesyesyesyesyesyesyesyesyesyes

Machine-readable schema

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

/schemas/product.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 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.

On this page