Google Shopping
Google Shopping product search, listing detail, cross-retailer reviews, and total delivered price by seller
Google Shopping is the retailer-agnostic view of a product: one listing aggregating every store that sells it, the reviews shoppers left across all of them, and the total delivered price each seller is asking. Where Amazon or Home Depot tell you about one retailer's catalogue, this tells you about the product across the market.
Base URL: /v1/google_shopping/...
Everything starts at product-search, because the other three endpoints all need an id it returns.
reviews requires gid specifically. product_id alone is a 400.
Search returns up to three ids per row (product_id, gid, data_docid), so
store all three when you index a product.
Quickstart
Search for a product
This is the only expensive call here at 5 credits. The three id-driven endpoints are 1 credit each, so the shape rewards searching once and then reading the same product from three angles.
curl "https://www.socialcrawl.dev/v1/google_shopping/product-search?query=wireless%20earbuds&sort_by=review_score" \
-H "x-api-key: YOUR_API_KEY"Read the listing, then every seller
sellers is the one that justifies the platform: the single price on a search row is a headline number, while the total on a seller row is what a shopper actually pays.
curl "https://www.socialcrawl.dev/v1/google_shopping/product?product_id=PRODUCT_ID" \
-H "x-api-key: YOUR_API_KEY"
curl "https://www.socialcrawl.dev/v1/google_shopping/sellers?product_id=PRODUCT_ID" \
-H "x-api-key: YOUR_API_KEY"Search
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/google_shopping/product-search | 5 | Title, seller, current and original price, currency, rating, images, and the ids the rest of the platform needs | query (required), country, language, depth, price_min, price_max, sort_by |
depth defaults to 40 and caps at 120; a larger depth means a longer task upstream. sort_by accepts review_score, price_low_to_high or price_high_to_low.
Three ids, and which one each endpoint wants
Search returns up to three identifiers per row, and the endpoints do not treat them identically:
productandsellersaccept any one ofproduct_id,gidordata_docidreviewsrequiresgid, and additionally acceptsproduct_idordata_docidalongside it for a more accurate match
Detail, sellers and reviews
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/google_shopping/product | 1 | Description, rating, image gallery, feature bullets, grouped specifications, product variations | one of product_id / gid / data_docid, country, language |
GET /v1/google_shopping/sellers | 1 | Per store: seller name, domain, itemised base price, tax, shipping, total, rating, condition, availability, special-offer annotation | one of product_id / gid / data_docid, country, language |
GET /v1/google_shopping/reviews | 1 | Shopper reviews gathered across retailers, each carrying the retailer domain it came from alongside title, full text, star rating, images and date | gid (required), product_id, data_docid, depth, country, language |
On reviews, depth defaults to 10, runs in multiples of 10, and goes as high as 8000.
All endpoints
5 endpoints available.
| Endpoint | Path | Credit Tier |
|---|---|---|
| Get Google Shopping price history for a product | /v1/google_shopping/price-history | standard (1cr) |
| Get Google Shopping product detail | /v1/google_shopping/product | standard (1cr) |
| Get Google Shopping product reviews | /v1/google_shopping/reviews | standard (1cr) |
| Get Google Shopping sellers for a product | /v1/google_shopping/sellers | standard (1cr) |
| Search Google Shopping products | /v1/google_shopping/product-search | advanced (5cr) |
Platform notes
Ids are not stable across countries. country (an ISO code such as US, or a full name) selects the market, and a product's ids belong to the market you searched. Search and read in the same country.
No 404 on an empty search, but 404 on empty reviews. A search that matches nothing returns an empty result set. reviews on a product nobody reviewed returns a not-found, refunded automatically. Handle the two differently.
Ratings on a listing and reviews on it are different populations. The listing's rating aggregates across sellers; the review rows are the ones Google collected text for. Expect the counts to disagree.
The headline price and the delivered total rank sellers differently. A seller row itemises base price, tax and shipping separately from total. Compare on total when you are modelling what a shopper actually pays.
First calls are slow, then cached. A cold product-search takes roughly 20 to 30 seconds because the upstream settles a task before answering; repeats serve from cache. Set client timeouts accordingly.
language does not change the market. It defaults to en and only affects the language of the response, not which country is queried. Use country for that.
Next steps
Pagination
The universal cursor, and where depth replaces it.
Credits
What each tier costs, and which failures are refunded.
API reference
Every Google Shopping parameter and response field.
Amazon
One retailer's catalogue, with competing seller offers.
eBay
Listing search with seller reputation and sold history.