Skip to main content
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.
Submit the task, then poll GET /v1/async/task/{id} or receive its webhook. See Async tasks.

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

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

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, Google AI Overviews and Google AI Mode 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

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.