# Google Shopping (/docs/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.

```bash title="cURL"
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.

```bash title="cURL"
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:

- `product` and `sellers` accept any one of `product_id`, `gid` or `data_docid`
- `reviews` **requires `gid`**, and additionally accepts `product_id` or `data_docid` alongside 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`, `label`, `judgments` |

On `reviews`, `depth` defaults to 10, runs in multiples of 10, and goes as high as 8000.

## All endpoints

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

## Labels

`/v1/google_shopping/reviews` labels each review by default, at no extra credit: `sentiment` (read from the words, never the stars, with `rating_mismatch` when the two clearly disagree) and `issue` (the main problem the review reports) on `computed.labels`. Send `judgments=off` for the page without them. See [Labels](/docs/labels.md) for the field shapes and the labels you can add with `label=`, such as `label=reports&reports=the battery drains quickly`.

## Next steps

- [Pagination](/docs/pagination.md): The universal cursor, and where depth replaces it.
- [Credits](/docs/credits.md): What each tier costs, and which failures are refunded.
- [API reference](/docs/api-reference.md): Every Google Shopping parameter and response field.
- [Amazon](/docs/amazon.md): One retailer
- [eBay](/docs/ebay.md): Listing search with seller reputation and sold history.