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
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 toUS, the store’s country. Any other country is rejected with422 REGION_UNSUPPORTED.
include: even include: {} returns 422 VALIDATION_ERROR on payload.include before credits are held.
Response example
Result fields
site,queryandcountryecho the request.returnedCountis the number of entries inproducts.- Each product includes
rank,productId,titleandurl.productIdis Google’s product ID, or the offer ID for a listing Google has not grouped into a product.rankfollows the store’s default order, and listings the store marks as sponsored are left out. price,rating,reviewCount,imageUrlandsellerappear when the results page shows them.priceis a number in the product’scurrency(ISO 4217); when sizes are priced apart, it is the lowest one.ratinguses a five-point scale. Abbreviated review counts such as 999+ are left out.reviewCountappears 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
urlis the Google Shopping results page the product was ranked on, with#product={productId}&title={title}at the end. Pass thaturltoCOMMERCE_PRODUCTto read the product’s stores, specs and description.sellernames the store Google lists first.
Product page
Parameters
url: Required. A producturlfrom a Google Shopping search, up to 2,048 characters:google.com/search?q={query}&udm=28&gl={market}#product={productId}&title={title}. TheproductDetailUrlof a product in Google Search, Google AI Overviews and Google AI Mode results works as it is too.country: Optional. Defaults to theglin theurl, one ofUS,GB,AU,CA,KR,JP,TW,HK,DE,FR,ES,IT,PL,PT,BR,IN,ID,THandVN. Any other country is rejected with422 REGION_UNSUPPORTED.
include: even include: {} returns 422 VALIDATION_ERROR on payload.include before credits are held.
Response example
Result fields
site,country,urlandproductIdidentify the page.urlis the page that was read, andproductIdmatches the one a search returns.titleis always present.brand,price,listPrice,currency,inStock,seller,rating,reviewCount,images,description,specsandoffersappear when the page shows them.priceis what a shopper pays as the page first shows it, before coupons and delivery, incurrency(ISO 4217).listPriceis the regular price the page strikes through, present when it is aboveprice.inStockis the product’s stock status.selleris the merchant selling it.ratinguses a five-point scale with two decimals.reviewCountis the number of reviews.reviewCountappears only when Google shows the exact count (below 1,000).imageslists up to 30 photos from the product’s gallery, in page order.descriptionis plain text with one line per paragraph, up to 10,000 characters; text that appears only inside images is not included.specslists 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 withPAGE_UNAVAILABLE. offerslists the stores Google shows for the product, starting with the one Google marks as the best price, each withseller,title(the store’s product name),url(the store’s product page),price,listPrice,currencyandinStock. The product’sprice,listPrice,sellerandinStockare the first store’s. Prices carry the currency of the market’s Shopping tab (ISO 4217), whatever language the labels are in.- A
productDetailUrlfrom a Google AI Overviews or AI Mode product searches the product’s title, and the result returns that product’sproductDocid.
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.