> ## Documentation Index
> Fetch the complete documentation index at: https://clair.im/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Shopping API reference

> Google Shopping API for developers. One live google.com search per request: every Google Shopping product card it shows, with price, pre-discount price, store, delivery, and rating.

Live scrape of **google.com**. One request returns the Google Shopping
products Google shows for a query, usually 20 to 30, in its shopping sections
(deals, popular products, more products). Each card carries one store's offer:
its price, the pre-discount price when the product is on sale, delivery terms,
and the product's rating. A product listed in more than one section appears
once.

This is not Google's Merchant API, which manages a merchant's own listings.
See the [Google Shopping API: overview, pricing, and free tier](https://clair.im/apis/google-shopping).

## Endpoint

`GET /v1/google-shopping` · **1 request**

```sh theme={null}
curl -G https://api.clair.im/v1/google-shopping \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "q=wireless earbuds"
```

## Parameters

| Parameter | Required | Contract |
| - | - | - |
| `q` | yes | Product query. |
| `language` | no | ISO 639-1 interface language. Default `en`. |
| `country` | no | ISO 3166-1 alpha-2 country the search is made from. Default `us`. Sets the stores and currency. |

`country` sets where the search is made from, so it sets the stores and the
currency. Sending `page`, `cursor`, or `limit` returns `locked_parameter`:
Google shows these sections once per query, so `next_cursor` is always `null`.

## Response

```json theme={null}
{
  "engine": "google_shopping",
  "family": "ecommerce",
  "query": { "q": "wireless earbuds", "language": "en", "country": "us" },
  "count": 31,
  "total_results": null,
  "results": [
    {
      "position": 1,
      "title": "JLab GO Air Pop True Wireless Earbuds",
      "product_id": "9146411353573113826",
      "price_text": "$14.99",
      "price": 14.99,
      "currency": "USD",
      "original_price_text": "$20",
      "original_price": 20,
      "badge": "24% OFF",
      "merchant": "Target",
      "more_merchants": true,
      "delivery": "Free delivery on $35+",
      "rating": 4.3,
      "ratings_count": 33000,
      "section": "Popular products"
    }
  ],
  "next_cursor": null
}
```

| Field | Contents |
| - | - |
| `product_id` | Google's product id: one product across every store that sells it. Stable between searches, so use it to join snapshots. |
| `price`, `original_price` | Parsed from `price_text` and `original_price_text`. `original_price` is null when the product is not on sale. A card priced from several stores shows `$890+`: `price` is that lowest price. |
| `badge` | Google's label, such as `25% OFF` or `LOW PRICE`. |
| `merchant`, `more_merchants` | The store whose offer the card shows, and whether other stores sell it too. `merchant` is null on a card priced from several stores. |
| `rating`, `ratings_count` | The product's rating out of 5, and its review count as Google rounds it (`33K` is 33000). |
| `section` | The block the card sits in, such as `Popular products`. |

A query no product matches returns `count: 0` and an empty `results`.

## What this API does not do

* It does not list every store's price for a product. Google shows those in a
  product viewer that opens in the browser, which a fetched page does not
  render for most products.
* It does not return images: Google embeds thumbnails in the page instead of
  linking them.
* It does not paginate.

Auth, plans, rate limits, and error codes: [Authentication](https://clair.im/docs/authentication.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.