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

# Google Shopping API

> Search Google Shopping and read its product pages as JSON: ranked products with prices, ratings, review counts and sellers, and each product's price, stock, seller, images and specs.

Search Google Shopping (shopping.google.com) and read its product pages through the async task API. Send `COMMERCE_SERP` with `site` `google_shopping` to get the products a search shows, in the store's order, or `COMMERCE_PRODUCT` with a product's `url` to read that product. A completed search or product page costs **2 credits**.

## Search

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "COMMERCE_SERP", "payload": { "site": "google_shopping", "query": "wireless earbuds", "limit": 3 } }'
```

Submit the task, then poll `GET /v1/async/task/{id}` or receive its webhook. See [Async tasks](https://docs.querying.ai/concepts/async-tasks.md).

### Parameters

* `site`: Required. `google_shopping`.
* `query`: Required. The search query, 1-500 characters.
* `limit`: Optional integer from 1 to 40, default 20.
* `country`: Optional. Defaults to `US`, the store's country. Any other country is rejected with `422 REGION_UNSUPPORTED`.

Only the payload fields listed above are accepted. Omit `include`: even `include: {}` returns `422 VALIDATION_ERROR` on `payload.include` before credits are held.

### Response example

```json theme={"theme":"css-variables"}
{
  "site": "google_shopping",
  "query": "wireless earbuds",
  "country": "US",
  "returnedCount": 3,
  "products": [
    {
      "rank": 1,
      "productId": "1067219252613399794",
      "title": "JLab Go Air Sport True Wireless Earbuds",
      "url": "https://www.google.com/search?q=wireless+earbuds&udm=28&gl=us&hl=en#product=1067219252613399794&title=JLab+Go+Air+Sport+True+Wireless+Earbuds",
      "price": 9.88,
      "currency": "USD",
      "rating": 4.1,
      "seller": "Walmart"
    },
    {
      "rank": 2,
      "productId": "5295866786049939613",
      "title": "JBL Vibe Beam 2 Noise Cancelling True Wireless Earbuds",
      "url": "https://www.google.com/search?q=wireless+earbuds&udm=28&gl=us&hl=en#product=5295866786049939613&title=JBL+Vibe+Beam+2+Noise+Cancelling+True+Wireless+Earbuds",
      "price": 39.95,
      "currency": "USD",
      "rating": 4.2,
      "seller": "Best Buy",
      "imageUrl": "https://encrypted-tbn0.gstatic.com/shopping?q=tbn:ANd9GcTxk4D_LlWLl4n-ponPRc2ihvXVxc8LIg5CGbLCdzmKDbN8zVii50zLQ0tUpH6TwjuCdY2RS3wRw93no9--JdlU6yG_udswoQ"
    },
    {
      "rank": 3,
      "productId": "549048356659243400",
      "title": "Beats Solo Buds True Wireless Earbuds",
      "url": "https://www.google.com/search?q=wireless+earbuds&udm=28&gl=us&hl=en#product=549048356659243400&title=Beats+Solo+Buds+True+Wireless+Earbuds",
      "price": 69.99,
      "currency": "USD",
      "rating": 3.8,
      "seller": "Target",
      "imageUrl": "https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcSQnGg6ee9gh0KOOWZFMqbmbUGjWa3kZ5V5EBOzJjb6JRM9z6TdPAoGlSi5_f6cPsEXle-oiBJ8EJ-FaREc98Wqt8jC8WzmfQ"
    }
  ]
}
```

### Result fields

* `site`, `query` and `country` echo the request. `returnedCount` is the number of entries in `products`.
* Each product includes `rank`, `productId`, `title` and `url`. `productId` is Google's product ID, or the offer ID for a listing Google has not grouped into a product. `rank` follows the store's default order, and listings the store marks as sponsored are left out.
* `price`, `rating`, `reviewCount`, `imageUrl` and `seller` appear when the results page shows them. `price` is a number in the product's `currency` (ISO 4217); when sizes are priced apart, it is the lowest one.
* `rating` uses a five-point scale. Abbreviated review counts such as 999+ are left out. `reviewCount` appears only when Google shows the exact count (below 1,000).
* Each search returns products from the store's first results page.
* Google's page links no product or merchant page, so `url` is the Google Shopping results page the product was ranked on, with `#product={productId}&title={title}` at the end. Pass that `url` to `COMMERCE_PRODUCT` to read the product's stores, specs and description. `seller` names the store Google lists first.

## Product page

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "COMMERCE_PRODUCT", "payload": { "url": "https://www.google.com/search?q=wireless+earbuds&udm=28&gl=us&hl=en#product=5295866786049939613&title=JBL+Vibe+Beam+2+Noise+Cancelling+True+Wireless+Earbuds" } }'
```

### Parameters

* `url`: Required. A product `url` from a Google Shopping search, up to 2,048 characters: `google.com/search?q={query}&udm=28&gl={market}#product={productId}&title={title}`. The `productDetailUrl` of a product in [Google Search](https://docs.querying.ai/engines/google-serp.md), [Google AI Overviews](https://docs.querying.ai/engines/google-ai-overviews.md) and [Google AI Mode](https://docs.querying.ai/engines/google-ai-mode.md) results works as it is too.
* `country`: Optional. Defaults to the `gl` in the `url`, one of `US`, `GB`, `AU`, `CA`, `KR`, `JP`, `TW`, `HK`, `DE`, `FR`, `ES`, `IT`, `PL`, `PT`, `BR`, `IN`, `ID`, `TH` and `VN`. Any other country is rejected with `422 REGION_UNSUPPORTED`.

Only the payload fields listed above are accepted. Omit `include`: even `include: {}` returns `422 VALIDATION_ERROR` on `payload.include` before credits are held.

### Response example

```json theme={"theme":"css-variables"}
{
  "site": "google_shopping",
  "country": "US",
  "url": "https://www.google.com/search?q=wireless+earbuds&udm=28&gl=us&hl=en#product=5295866786049939613&title=JBL+Vibe+Beam+2+Noise+Cancelling+True+Wireless+Earbuds",
  "productId": "5295866786049939613",
  "title": "JBL Vibe Beam 2 Noise Cancelling True Wireless Earbuds",
  "brand": "JBL",
  "price": 39.95,
  "listPrice": 65,
  "currency": "USD",
  "inStock": true,
  "seller": "Scheels",
  "rating": 4.2,
  "images": [
    "https://encrypted-tbn0.gstatic.com/shopping?q=tbn:ANd9GcTxk4D_LlWLl4n-ponPRc2ihvXVxc8LIg5CGbLCdzmKDbN8zVii50zLQ0tUpH6TwjuCdY2RS3wRw93no9--JdlU6yG_udswoQ",
    "https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcQ64EZlooEjcI4GdHBULPySzyZvLSCxjsMi8raMFjbWdZv_KK0cL6P2pIc7nts3uk7G0_XBWBBhVjcuz92sCo2lcDw4hW2H"
  ],
  "description": "The JBL Vibe Beam 2 is a true wireless in-ear earbud system designed to deliver strong audio performance, effective noise control, and seamless everyday usability. Equipped with Bluetooth 5.3, it…",
  "specs": [
    { "name": "Brand", "value": "JBL" },
    { "name": "Noise Canceling", "value": "Yes" },
    { "name": "With Microphone", "value": "Yes" }
  ],
  "offers": [
    {
      "price": 39.95,
      "title": "JBL Vibe Beam 2 headphones",
      "seller": "Scheels",
      "inStock": true,
      "currency": "USD",
      "listPrice": 65
    },
    {
      "url": "https://www.walmart.com/ip/JBL-Vibe-Beam-2-True-Wireless-Noise-Cancelling-In-Ear-Earbuds-Black/21106652379?wmlspartner=wlpa&selectedSellerId=609&veh=seo_fpl&cn=google",
      "price": 39.77,
      "title": "Jbl Vibe Beam 2 True Wireless Noise Cancelling In-Ear Earbuds, Black",
      "seller": "Walmart - Electronics Expo (Authorized Dealer)",
      "inStock": true,
      "currency": "USD"
    }
  ]
}
```

### Result fields

* `site`, `country`, `url` and `productId` identify the page. `url` is the page that was read, and `productId` matches the one a search returns.
* `title` is always present. `brand`, `price`, `listPrice`, `currency`, `inStock`, `seller`, `rating`, `reviewCount`, `images`, `description`, `specs` and `offers` appear when the page shows them.
* `price` is what a shopper pays as the page first shows it, before coupons and delivery, in `currency` (ISO 4217). `listPrice` is the regular price the page strikes through, present when it is above `price`. `inStock` is the product's stock status. `seller` is the merchant selling it.
* `rating` uses a five-point scale with two decimals. `reviewCount` is the number of reviews. `reviewCount` appears only when Google shows the exact count (below 1,000).
* `images` lists up to 30 photos from the product's gallery, in page order.
* `description` is plain text with one line per paragraph, up to 10,000 characters; text that appears only inside images is not included.
* `specs` lists up to 100 `{ name, value }` pairs from the product details.
* The read runs the `url`'s query again on Google Shopping in its market, or the product's title when Google no longer lists the product for the query, and opens the product's panel, so it takes longer than a store page. If Google lists the product for neither, the task ends with `PAGE_UNAVAILABLE`.
* `offers` lists the stores Google shows for the product, starting with the one Google marks as the best price, each with `seller`, `title` (the store's product name), `url` (the store's product page), `price`, `listPrice`, `currency` and `inStock`. The product's `price`, `listPrice`, `seller` and `inStock` are the first store's. Prices carry the currency of the market's Shopping tab (ISO 4217), whatever language the labels are in.
* A `productDetailUrl` from a Google AI Overviews or AI Mode product searches the product's title, and the result returns that product's `productDocid`.

## Errors and billing

* A search that returns no products ends as a failed task.
* Only completed tasks are charged: 2 credits for a search or a product page.

## Related

* [Google Search](https://docs.querying.ai/engines/google-serp.md)
* [Google AI Overviews](https://docs.querying.ai/engines/google-ai-overviews.md)
* [Google AI Mode](https://docs.querying.ai/engines/google-ai-mode.md)
* [All Commerce stores](https://docs.querying.ai/engines/overview.md#commerce)
* [Credits and limits](https://docs.querying.ai/concepts/credits-and-limits.md)


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