# Google Shopping (/docs/google_shopping)



Google Shopping [#google-shopping]

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. It uses the same canonical commerce schema as the rest
of the commerce platforms here.

Base URL: `/v1/google_shopping/...`

<Callout>
  `/v1/google_shopping/reviews`

   

  **requires `gid`**

   specifically — 

  `product_id`

   alone is a 

  `400`

  . Search returns up to three ids per row (

  `product_id`

  , 

  `gid`

  , 

  `data_docid`

  ); store all three when you index a product.
</Callout>

Getting started [#getting-started]

Everything starts at `product-search`, because the other three endpoints all need an id it
returns.

```bash
# 1. Keyword to product ids (5 credits)
curl "https://www.socialcrawl.dev/v1/google_shopping/product-search?query=wireless%20earbuds&sort_by=review_score" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. Full listing detail (1 credit)
curl "https://www.socialcrawl.dev/v1/google_shopping/product?product_id=$PRODUCT_ID" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 3. Every seller and what they really charge (1 credit)
curl "https://www.socialcrawl.dev/v1/google_shopping/sellers?product_id=$PRODUCT_ID" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Search [#search]

`product-search` returns title, seller, current and original price, rating, images, and the ids
the rest of the platform needs. `depth` defaults to 40 and caps at 120 — a larger depth means a
longer task upstream. `price_min` and `price_max` bound the results, and `sort_by` accepts
`review_score`, `price_low_to_high` or `price_high_to_low`.

At 5 credits it is the expensive call here; the three id-driven endpoints are 1 credit each.
That shape rewards searching once and then reading the same product from three angles.

Three ids, and which one each endpoint wants [#three-ids-and-which-one-each-endpoint-wants]

Search returns up to three identifiers per row — `product_id`, `gid` and `data_docid` — and the
endpoints do not treat them identically:

* `product` and `sellers` accept any one of the three
* `/v1/google_shopping/reviews` &#x2A;*requires `gid`**, and additionally accepts `product_id` or
  `data_docid` alongside it for a more accurate match

Store all three when you index a product. Passing `product_id` to `reviews` on its own is a
`400`.

Detail, reviews and sellers [#detail-reviews-and-sellers]

`product` returns the listing record: description, rating, image gallery, feature bullets,
grouped specifications and the product variations.

`reviews` returns shopper reviews gathered **across retailers**, each carrying the retailer
domain it came from alongside the title, full text, star rating, images and date. `depth`
defaults to 10, runs in multiples of 10, and goes as high as 8000. A product with no reviews
returns a `404` rather than an empty list.

`sellers` is the one that justifies the platform. For each store offering the product it returns
seller name, domain, base price, tax, shipping, **total**, rating, condition and availability.
The single price on a search row is a headline number; the total on a seller row is what a
shopper actually pays, and the two frequently rank the sellers differently.

Endpoints [#endpoints]

<PlatformEndpoints platform="google_shopping" />

Read this before you build [#read-this-before-you-build]

**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. 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.

Notes [#notes]

* All endpoints use `GET` with query parameters
* Authentication via the `x-api-key` header
* Responses follow the unified SocialCrawl schema, shared with the other commerce platforms
* `product-search` is 5 credits; `product`, `reviews` and `sellers` are 1 credit each
* `language` defaults to `en` and does not change which market is queried