--- title: "Search" description: "在 Google Shopping 搜索商品，每件商品附带价格、商家和评分。" --- > Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt; this API family in one file: https://apinoa.com/docs/serp/llms.txt) ```http GET | POST /v1/google-shopping/search ``` 参数可以用 `GET` 的查询字符串发送，也可以用 `POST` 的 JSON 请求体发送，两者等价。 ## 请求 ```bash tab="cURL" curl "https://gateway.apinoa.com/v1/google-shopping/search?query=running+shoes®ion=US" \ -H "x-api-key: $APINOA_API_KEY" ``` ```js tab="JavaScript" const params = new URLSearchParams({ query: "running shoes", region: "US" }); const res = await fetch(`https://gateway.apinoa.com/v1/google-shopping/search?${params}`, { headers: { "x-api-key": process.env.APINOA_API_KEY }, }); const { success, data, error } = await res.json(); ``` ```python tab="Python" import os import requests res = requests.get( "https://gateway.apinoa.com/v1/google-shopping/search", params={"query": "running shoes", "region": "US"}, headers={"x-api-key": os.environ["APINOA_API_KEY"]}, ) body = res.json() ``` ## 参数 | Parameter | Type | Required | Notes | |---|---|---|---| | `cursor` | string | | Next page: pass the previous result's `cursor` alone. | | `facets` | string \| object list | | One value from a result's `facets` (include=facets), e.g. facets=Brand:. Google applies one at a time. | | `include` | string list | | `facets` — the filter rail Google shows beside the results, on the same page (no extra request). | | `priceMax` | number ≥ 0 | | Highest price, in the market's currency (decimal major units). | | `priceMin` | number ≥ 0 | | Lowest price, in the market's currency (decimal major units). | | `query` | string | | Keywords to search for. | | `region` | enum | | The market, ISO 3166-1 alpha-2: US (default), GB, CA, AU. Sets the shops, prices and currency. `US` `GB` `CA` `AU` | The same parameters, and every response type, are in the OpenAPI document: https://apinoa.com/openapi.json ## 响应 在 `data` 中返回 [`SearchResult`](/docs/api-reference/marketplaces/response-schema#searchresult)。 真实响应的节选：数组只保留前几项，长文本已截断。 ```json { "success": true, "data": { "marketplace": "google-shopping", "query": "running shoes", "page": {"index": 1, "size": 54}, "items": [ { "marketplace": "google-shopping", "id": "14699928440903523478", "url": "https://www.google.com/search?ibp=oshop&q=Hoka+Men%27s+Clifton+11&prds=catalogid%3A5939486839279040471%2Cgpcid%3A14699928440903523478%2CheadlineOfferDocid%3A905…", "title": "Hoka Men's Clifton 11", "price": {"currency": "USD", "amount": 154.95}, "brand": "Hoka One One", "seller": {"name": "Zappos.com", "logoUrl": "data:image/png;base64,iVBORw0KGgoAAAANSU…"}, "rating": {"average": 4.484, "count": 412}, "delivery": {"estimate": "Free delivery by Mon", "free": true}, "returnsPolicy": "Free 365-day returns", "badges": [], "promotions": [], "attributes": [], "groupId": "14699928440903523478", "imageUrl": "https://encrypted-tbn3.gstatic.com/shopping?q=tbn:ANd9GcRqYH_zOknkUmPHPQooSsPMYiYGJMv-jev2oHa3IYWYR3S1ZdTQiAb3gLS_dNid6BzrdE1cSbjGZFbQVF2Nkj2ST_R5sfE4Tw", "ext": { "summary": "Hoka Men's Clifton 11. Current Price: $154.95. Zappos.com & more. Free delivery by Mon. Free 365-day returns. Rated 4.5 out of 5. 412 reviews.", "moreStores": true, "shelf": "Beginner Running Shoes", "catalogId": "5939486839279040471", "productId": "13107188378090301883", "offerId": "9057001329748764354", "imageId": "8494207511608046187" }, "offers": [ { "seller": { "name": "Peter Glenn Ski & Sports", "logoUrl": "https://encrypted-tbn2.gstatic.com/favicon-tbn?q=tbn%3AANd9GcTgj6MTV2jVPsWTKNdSwoPkVupNia0bUqnfBm8PYegVt-ywkuVH1n9-VCekAnK6c1rBK6Eho-3SEcUhcTEOMxTwKsE_qF3XMchpt…" }, "price": {"currency": "USD", "amount": 155}, "delivery": {"estimate": "Free delivery by Tue", "free": true}, "ext": {"offerId": "18164253511807076099", "shelf": "All products"} } ] }, { "marketplace": "google-shopping", "id": "1522057692120988320", "url": "https://www.google.com/search?ibp=oshop&q=New+Balance+Women%27s+Fresh+Foam+X+Kaiha+Road+V2+Running+Shoes&prds=catalogid%3A2224207068186773069%2Cgpcid%3A15220576…", "title": "New Balance Women's Fresh Foam X Kaiha Road V2 Running Shoes", "price": {"currency": "USD", "amount": 104.99}, "brand": "New Balance", "seller": {"name": "New Balance", "logoUrl": "data:image/png;base64,iVBORw0KGgoAAAANSU…"}, "rating": {"average": 5, "count": 166}, "returnsPolicy": "45-day returns", "badges": [], "promotions": [], "attributes": [], "groupId": "1522057692120988320", "imageUrl": "https://encrypted-tbn3.gstatic.com/shopping?q=tbn:ANd9GcSSyE2K1PfUS8yxgpTwvT2vlaiCaO84uGQNRSOkkjF_LCLn3s7bRKN1RMRFX2rwek5QYVUaeWIIL4W6zE7k1A266nu7dx6K", "ext": { "summary": "New Balance Women's Fresh Foam X Kaiha Road V2 Running Shoes. Current Price: $104.99. New Balance & more. 45-day returns. Rated 5.0 out of 5. 166 reviews.", "moreStores": true, "shelf": "Beginner Running Shoes", "catalogId": "2224207068186773069", "productId": "16229217600571913203", "offerId": "8468470629989173210", "imageId": "1190089453230405951" } } ], "cursor": "tRlUbjVXzLQ2mckO_0hUg_oRXAX71LylzGzTA4ov5NQm-NnRYdL9Cydv_yTsWQvUY7ouiehwkp5AzTrHVcRpPcxjhMZBDfWSR6cMUeo1EiZf7Lnj_fUyC3sfVIdge_nN-YWBk_4YkMM" } } ``` ## 错误 | 状态 | 代码 | 含义 | |---|---|---| | 400 | `INVALID_CURSOR` | 该 `cursor` 不是本操作返回的。请不带它重新开始。 | | 400 | `INVALID_PARAMS` | 参数缺失、未知、超出范围，或该引擎不接受。消息中会指出是哪一个。 | | 401 | `UNAUTHORIZED` | 缺少 `x-api-key` 请求头，或密钥已吊销或未知。 | | 402 | `INSUFFICIENT_BALANCE` | 余额不足以支付本次调用。请在控制台充值。 | | 429 | `MARKETPLACE_SATURATED` | 并发调用过多。请等待 `Retry-After` 秒后重试。 | | 502 | `UPSTREAM_ERROR` | 引擎返回了无法使用的内容。请退避后重试。 | | 503 | `SERVICE_UNAVAILABLE` | 临时故障。请退避后重试。 | 全部错误代码见 [Errors](/docs/errors)。失败的调用不计费。 ## 价格 **Price** $0.0012 per call. [List price](https://apinoa.com/en/pricing); the rate steps down above 1,000 calls a day. ## 说明 - `include=facets` 会附上 Google 在结果旁显示的筛选栏，不额外收费。把其中一个值作为 `facets` 传入即可筛选。 - `priceMin` 和 `priceMax` 以该市场货币的主单位（可带小数）表示。