Amazon 关键词排名 API

POST

接口健康状态

24h 健康值: 正常
24h 平均耗时: —

健康 / 正常
可用
少量可用
基本不可用

正常

24 小时趋势

30 天趋势

关键词排名：返回列表，默认 20 条、单次最多 100 条；主要字段 asin、keyword、search_volume、search_rank、result_type、result_type_rank。

单价 $280 / 千次（每次 $0.28），失败与空结果不扣费。同步返回；慢任务可在请求体加 "mode": "async"，先拿 job_id 再轮询。

AI 提示词

复制下面这段给你常用的 AI 助手：里面写好了这个接口的参数、返回字段和示例请求，它会先问清你的需求，再帮你写采集脚本。

请帮我用 EveryInfra 的「Amazon 关键词排名」接口（amazon/ranked_keywords）写一个数据采集脚本。

接口约定：
- 请求：POST https://api.everyinfra.com/api/v1/social，请求头 Authorization: Bearer <API Key>；Key 从环境变量 EVERYINFRA_API_KEY 读取，不要写进代码。
- 请求体里 platform 填 amazon，action 填 ranked_keywords，参数放在 params 里。
- 必填参数：
  - asin：要查的商品 ASIN，一个 10 位大写字母/数字（例如 B0C2JXSHSK），不收列表。只查美国站；不是每个商品都有关键词排名数据，没有数据时返回空结果、不扣费。
- 可选参数：
  - limit：这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。（默认 20）
- 返回一组记录，每条记录的主要字段：asin（Amazon 标准识别号）、keyword（这个商品排得上的搜索关键词（ran…）、search_volume（该关键词在美国站的月搜索量估计（r…）、search_rank（这个商品在该词搜索结果页上的绝对名次）、result_type（这个名次是哪种结果（ranked_…）、result_type_rank（在同一种结果（organic 或…）、search_result_count（该关键词在美国站的搜索结果总数（r…）、ranked_at（观察到这个名次的时间）、title、url、image_url、price；一共 20 个字段，完整列表见 https://api.everyinfra.com/api/v1/social/catalog?platform=amazon。
- 示例请求体：
{
  "platform": "amazon",
  "action": "ranked_keywords",
  "params": {
    "asin": "B0C2JXSHSK"
  }
}
- 计费：$280 / 千次；失败和空结果不扣费。
- 一次要采几十上百个时，在请求体加 "mode": "async"：先拿到 job_id，再轮询 GET https://api.everyinfra.com/api/v1/jobs/{job_id} 取结果。
- 返回 422 时，按错误信息里的候选参数和允许值修正；返回 429 或 503 时，按 Retry-After 等待后重试。

写代码前，先问清楚我要采哪些对象、一共多少个、需要哪些字段、结果存成什么格式，再把方案和大概花费讲给我确认。

请求参数

参数名	位置	类型	必填	默认值	说明
`Authorization`	header	`string`	是	-	Bearer 加你的 API Key。在控制台创建；不要放进网址或代码仓库。
`platform`	body	`string`	是	`amazon`	平台标识，固定值。
`action`	body	`string`	是	`ranked_keywords`	能力标识，固定值。
`asin`	body.params	`string`	是	-	要查的商品 ASIN，一个 10 位大写字母/数字（例如 B0C2JXSHSK），不收列表。只查美国站；不是每个商品都有关键词排名数据，没有数据时返回空结果、不扣费。
`limit`	body.params	`integer (1–100)`	否	`20`	这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。

代码示例

bash

curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "amazon",
  "action": "ranked_keywords",
  "params": {
    "asin": "B0C2JXSHSK"
  }
}'

OpenAPI 定义 (JSON)示例从环境变量 EVERYINFRA_API_KEY 读取 Key，复制出去的代码不含你的 Key。

响应示例

字段预览

这组示例参数还没有真实样例：这里只按接口定义列出响应结构和字段，值用 … 占位，不是一次真实调用的结果。

json

{
  "id": "req_…",
  "platform": "amazon",
  "action": "ranked_keywords",
  "results": [
    {
      "asin": …,
      "keyword": …,
      "search_volume": …,
      "search_rank": …,
      "result_type": …,
      "result_type_rank": …,
      "search_result_count": …,
      "ranked_at": …,
      "title": …,
      "url": …,
      "image_url": …,
      "price": …,
      "currency": …,
      "rating": …,
      "rating_scale": …,
      "rating_count": …,
      "is_amazon_choice": …,
      "is_bestseller": …,
      "bought_past_month": …,
      "total_keywords": …,
      "platform": …
    }
  ],
  "count": …,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}

返回字段

业务数据在 results 里；下表是每条记录可能包含的字段，平台没有提供的值不会被补造。

字段	含义
`asin`	Amazon 标准识别号，站内唯一商品标识。
`keyword`	这个商品排得上的搜索关键词（ranked_keywords）。
`search_volume`	该关键词在美国站的月搜索量估计（ranked_keywords），是整个词的需求，不是这个商品的流量；0 表示量太小。
`search_rank`	这个商品在该词搜索结果页上的绝对名次，从 1 开始，自然结果和广告位一起数（ranked_keywords）。
`result_type`	这个名次是哪种结果（ranked_keywords）：organic 自然结果，sponsored 广告位。
`result_type_rank`	在同一种结果（organic 或 sponsored）里排第几（ranked_keywords）。
`search_result_count`	该关键词在美国站的搜索结果总数（ranked_keywords），可当竞争激烈程度的参考。
`ranked_at`	观察到这个名次的时间，ISO 8601、UTC（ranked_keywords）；不同关键词的观察时间不同，可能是几周前。
`title`	标题。平台无标题概念时（如纯文本帖）为 null。
`url`	该记录在原平台上的可访问链接。
`image_url`	图片链接。多图能力可能返回 image_urls 数组。
`price`	价格数值，不含货币符号；币种见 currency。
`currency`	价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。
`rating`	评分。分制随平台而异，同一行的 `rating_scale` 给出该平台满分 (多数是 5，Booking/豆瓣/爱奇艺/NAVER 是 10)。跨平台比较前必须先按 rating_scale 换算 —— 直接比数字会得出反的结论。
`rating_scale`	上一列 `rating` 的满分。5 表示五星制、10 表示十分制。只在该行有 rating 时出现。
`rating_count`	参与评分的人数。null 表示不公开，不等于 0。
`is_amazon_choice`	是否有 Amazon's Choice 标。
`is_bestseller`	观察到名次时是否带 Best Seller 标（ranked_keywords）。
`bought_past_month`	搜索结果页上「过去一个月已购」标记的数（ranked_keywords），是平台给的估计档位（如 1000 表示 1K+），不是这个商品的准确销量。
`total_keywords`	这个商品总共排得上多少个关键词（ranked_keywords），每行相同；一次最多返回 100 个。
`platform`	数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。

错误与计费

401: 缺少 Key 或 Key 无效。
402: 余额不足，先充值。
422: 参数名或取值不对，按错误信息给的候选改；不扣费。
429: 超过每分钟请求上限，按 Retry-After 等待后再试。
503: 暂时无法完成，预扣的费用退回；结果未知时先核对，不要直接重发。
200 空结果: 没有数据，不扣费。

错误码