---
document_id: agent.collection.task.amazon_search_products_v1
schema_version: 2
parent_document_id: agent.querying
section: querying
---

<!-- Generated by scripts.build_agent_guide; do not edit. -->

# Product search / 商品搜索

Search Amazon products by keyword, one page per call, including available listing sales estimates. Use product detail for one ASIN.

按关键词搜索 Amazon 商品，返回单页商品与可用的 Listing 销售估算。获取单个商品详情请使用产品详情任务。

Task / 任务: `amazon_search_products_v1`
Platform / 平台: Amazon / Amazon
Billing / 计费: 20 Credits per successful task / 每个成功任务 20 Credits
Estimate / 估价: call `estimate_collection`; start directly when `approval_required=false`, otherwise obtain approval for `upper_bound_credits`.
估价：调用 `estimate_collection`；`approval_required=false` 时直接启动，否则请用户确认 `upper_bound_credits`。

## Limitations / 限制

- One product or one page per request. Each successful request, including an empty page, is charged independently.
- Listing sales are estimates and may cover multiple variants. Published ASIN sales are not exact real-time sales.
- Amounts use the currency's minor unit; JPY has no fractional unit. Missing data is null, not zero.
- Stored reviews may be delayed and refer to other variants. No live review collection is started.
- 14 marketplaces are supported by the source contract; live verification is recorded separately.

## Inputs / 输入

- `country` — Country / marketplace / 国家/站点; kind=select; required=False; default='US'; allowed=US, GB, DE, FR, IN, CA, JP, ES, IT, MX, AE, AU, BR, SA
- `query` — Product keywords / 商品关键词; kind=text; required=True; default=''; bounds=min_length=1, max_length=200
- `page` — Page / 页码; kind=integer; required=False; default=1; bounds=min=1, max=10000

## Minimal call / 最小调用

`estimate_collection`

```json
{
  "task_query": "搜索美国 Amazon 的椅套商品",
  "task_code": "amazon_search_products_v1",
  "input": {
    "query": "chair slipcover",
    "country": "US",
    "page": 1
  }
}
```


## Result and pagination / 结果与分页

- mode=page
- current page: `data.page`; page bound: `data.max_page`; next page: `data.next_page` → `page` (null means stop). / 下一页使用 `data.next_page`，为 null 时结束；总页数未知不代表没有下一页。

Only the fields listed below are part of the stable result contract. /
只有下方列出的字段属于稳定结果契约。

## Result fields / 结果字段

- `meta.request_id` — type=string; Asklear request identifier for tracing. / 用于追踪的 Asklear 请求 ID。
- `meta.api_name` — type=string; Executed collection operation name. / 实际执行的采集操作名称。
- `meta.latency_ms` — type=integer; Collection execution latency in milliseconds. / 采集执行耗时（毫秒）。
- `meta.credits_charged` — type=integer; Asklear user-side Credits settled for this task after completion. / 任务完成后 Asklear 用户侧实际结算的 Credits。
- `data.country` — type=string; Marketplace: US, GB, DE, FR, IN, CA, JP, ES, IT, MX, AE, AU, BR or SA. Defaults to US. Source support does not imply every country was live-tested. / 国家站点：US、GB、DE、FR、IN、CA、JP、ES、IT、MX、AE、AU、BR、SA，默认 US。接口声明支持不等于各国已完成实测。
- `data.page` — type=integer; Requested page, starting at 1. One call purchases one page. / 本次请求的页码，从 1 开始，一次调用只获取一页。
- `data.next_page` — type=integer|null; Pass this as page with the same country and filters. For search, a full page only permits trying the next page; it does not guarantee more matches. Each successful page is charged, including an empty page. / 保持国家和筛选条件，将此值作为 page 继续查询。搜索满页仅表示可尝试下一页，不保证还有结果；每个成功页独立计费，包括成功空页。
- `data.max_page` — type=integer|null; Total pages when known. Search has no total and returns null; Playground does not enable its next-page button for an unknown total. / 已知时返回总页数，搜索无总数时为 null；总页数未知时 Playground 不启用下一页按钮。
- `data.total` — type=integer|null; Matching review count from the original page metadata; search returns null. / 原始分页元数据中的评论总数；搜索返回 null。
- `data.items` — type=array<object>; Up to 100 products on this page; no hidden detail lookups. Search summaries have no trend arrays. / 本页最多 100 个商品，不会隐式追加详情查询。搜索摘要没有趋势数组。
- `data.items[].asin` — type=string; Returned ASIN; pass this to the detail or reviews task. / 返回商品的 ASIN，可传给产品详情或商品评论任务。
- `data.items[].parent_asin` — type=string|null; Parent listing ASIN when available. / 可用时返回父 Listing 的 ASIN。
- `data.items[].title` — type=string; Product title. / 商品名称。
- `data.items[].url` — type=string; Canonical product URL in the selected marketplace. / 所选国家站点的标准商品链接。
- `data.items[].images` — type=array<string>; Public product image URLs. / 商品公开图片链接。
- `data.items[].brand` — type=string|null; Product brand when available. / 商品品牌，未知为 null。
- `data.items[].description` — type=string|null; Stored product description; may include source formatting. / 已收录的商品说明，可能保留原文格式。
- `data.items[].price` — type=object|null; Recorded selling price, not a real-time checkout quote. / 收录时的销售价，不代表实时下单价格。
- `data.items[].price.amount_minor` — type=integer; Amount in the currency's smallest unit: 4199 USD means $41.99; 4199 JPY means ¥4199. Never divide every currency by 100. / 金额为币种最小单位：USD 4199 表示 41.99 美元，JPY 4199 表示 4199 日元，不能一律除以 100。
- `data.items[].price.currency` — type=string; ISO currency code for the selected marketplace. / 所选国家站点的 ISO 币种代码。
- `data.items[].rating` — type=number|null; Rating from 0 to 5; unavailable values are null. / 0–5 分评分，不可用时为 null。
- `data.items[].ratings_count` — type=integer|null; Number of ratings, distinct from the stored review count. / 评分数量，不等于可查询的已收录评论数量。
- `data.items[].categories` — type=array<string>; Category labels recorded for the product. / 已收录的商品类目名称。
- `data.items[].updated_at` — type=string|null; Product snapshot update date (YYYY-MM-DD), if reported. / 来源提供时返回商品快照更新日期（YYYY-MM-DD）。
- `data.items[].variation_count` — type=integer|null; Number of listing variants, if available. / Listing 的变体数量，未知为 null。
- `data.items[].asin_published_sales` — type=integer|null; ASIN-level sales count publicly displayed by Amazon, typically a rounded recent-month count. Not an exact sales total; missing or unreported zero becomes null. / Amazon 页面公布的 ASIN 级销量，通常为近期一个月的粗略数量，不是精确销量。未报告或表示未报告的 0 返回 null。
- `data.items[].listing_sales.scope` — type=string; Always listing: estimates may cover several variants, not just the requested ASIN. / 固定 listing：估算可能涵盖多个变体，不仅是输入的 ASIN。
- `data.items[].listing_sales.estimated` — type=boolean; Always true; units and revenue are estimates. / 固定 true；销量和销售额均为估算。
- `data.items[].listing_sales.daily.date` — type=string|null; Date of the one-day estimate, YYYY-MM-DD; null when not reported. / 单日估算对应日期（YYYY-MM-DD），来源未提供时为 null。
- `data.items[].listing_sales.daily.units` — type=integer|null; Estimated one-day listing units; missing is null, not zero. / Listing 的单日估算销量，缺失为 null，不填 0。
- `data.items[].listing_sales.daily.revenue` — type=object|null; Estimated one-day listing revenue; no currency conversion. / Listing 的单日估算销售额，不做汇率转换。
- `data.items[].listing_sales.daily.revenue.amount_minor` — type=integer; Revenue in the currency's smallest unit. / 销售额，单位为对应币种的最小单位。
- `data.items[].listing_sales.daily.revenue.currency` — type=string; ISO currency code, matching the marketplace. / 对应国家站点的 ISO 币种代码。
- `data.items[].listing_sales.rolling_30d.date` — type=string|null; Date of the rolling 30-day estimate, YYYY-MM-DD; null when not reported. / 滚动 30 天估算对应日期（YYYY-MM-DD），来源未提供时为 null。
- `data.items[].listing_sales.rolling_30d.units` — type=integer|null; Estimated rolling 30-day listing units; missing is null, not zero. / Listing 的滚动 30 天估算销量，缺失为 null，不填 0。
- `data.items[].listing_sales.rolling_30d.revenue` — type=object|null; Estimated rolling 30-day listing revenue; no currency conversion. / Listing 的滚动 30 天估算销售额，不做汇率转换。
- `data.items[].listing_sales.rolling_30d.revenue.amount_minor` — type=integer; Revenue in the currency's smallest unit. / 销售额，单位为对应币种的最小单位。
- `data.items[].listing_sales.rolling_30d.revenue.currency` — type=string; ISO currency code, matching the marketplace. / 对应国家站点的 ISO 币种代码。

Use `list_collection_tasks` as the runtime authority, then `describe_collection_task` for one task's full input contract, examples and limits. Collection access is entitlement-gated. /
以 `list_collection_tasks` 返回为运行时准据，再用 `describe_collection_task` 取单个任务的完整入参契约、示例与限制；采集能力受 entitlement 控制。