Amazon 产品排名（实时）

POST /v3/dataforseo_labs/amazon/ranked_keywords/live

接口说明

POST /v3/dataforseo_labs/amazon/ranked_keywords/live

本接口根据指定的 Amazon 产品 ASIN，返回该产品能够获得排名的，以及对应的搜索量、搜索结果排名、商品信息和 SERP 特征。

数据通常按周更新，最近更新时间可通过 /v3/dataforseo_labs/status/ 查询。

每个实时 API 请求只能一个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准，同时进行的请求数最多为 30。

所有 POST 请求体使用 UTF-8 编码的 JSON 数组格式：

json

[
  {
    "asin": "B00R92CL5E",
    "language_name": "English",
    "location_code": 2840
  }
]

计费说明

每次成功提交的请求均会产生费用。参考价约 ¥0.0792 / 次，价格可能根据账户和服务策略调整。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

参数	类型	填	说明
`asin`	string	是	Amazon 商品唯一标识符。可通过 `/v3/merchant/amazon/products/task_post/` 获取。
`location_name`	string	条件填	地区完整名称。当未指定 `location_code` 时填。当前支持美国、埃及、沙特阿拉伯和阿联。示例：`United States`。
`location_code`	integer	条件填	地区代码。当未指定 `location_name` 时填。当前支持美国、埃及、沙特阿拉伯和阿联。示例：`2840`。
`language_name`	string	条件填	语言完整名称。当未指定 `language_code` 时填。示例：`English`。
`language_code`	string	条件填	语言代码。当未指定 `language_name` 时填。示例：`en`。
`limit`	integer	否	返回结果中最多的数量。默认值为 `100`，最大值为 `1000`。
`ignore_synonyms`	boolean	否	是否忽略高度相似的。设置为 `true` 时返回核心；默认值为 `false`。
`filters`	array	否	结果过滤条件，最多支持 8 个过滤条件。多个条件之间指定逻辑运算符 `and` 或 `or`。
`order_by`	array	否	结果排序规则。可使用与 `filters` 相同的字段和排序表达式，支持 `asc` 升序和 `desc` 降序。单次请求最多设置 3 条排序规则。
`offset`	integer	否	结果偏移量，默认值为 `0`。例如设置为 `10` 时，将跳过前 10 条结果。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会原样返回在响应任务的 `data` 对象中。

地区和语言

可通过以下接口获取可用地区及语言：

text

GET /v3/dataforseo_labs/locations_and_languages

`filters` 示例

过滤条件通常由“字段、运算符、值”组成：

json

"filters": [
  ["keyword_info.search_volume", ">=", 1000],
  "and",
  ["keyword", "like", "%wireless%"]
]

支持以下运算符：

regex
not_regex
<
<=
>
>=
=
<>
in
not_in
like
not_like
match
not_match

使用 like 或 not_like 时，可以使用 % 匹零个或多个字符。

`order_by` 示例

json

"order_by": [
  ["keyword_info.search_volume", "desc"],
  ["ranked_serp_element.serp_item.rank_absolute", "asc"]
]

多个排序条件按数组顺序生效。

响应结构

接口返回 JSON 对象 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。
`status_message`	string	请求级状态信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	返回错误的任务数量。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`id`	string	任务唯一标识符，UUID 格式。
`status_code`	integer	任务状态码，通常位于 `10000` 至 `60000` 范围。
`status_message`	string	任务状态信息。
`time`	string	任务执行耗时。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求路径信息。
`data`	object	创建任务时提交的参数。
`result`	array	排名结果。

`result` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，通常为 `amazon`。
`asin`	string	请求中的 ASIN。
`location_code`	integer / null	请求中的地区代码。无数据时可能为 `null`。
`language_code`	string / null	请求中的语言代码。无数据时可能为 `null`。
`total_count`	integer	数据库中与请求条件匹的结果总数。
`items_count`	integer	`items` 数组中的结果数量。
`items`	array	排名明细。

`items` 字段

每个 items素代表一个产品排名，以下结构：

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword_data`	object	基础数据。
`ranked_serp_element`	object	该产品在指定下的 Amazon SERP 排名数据。

`keyword_data`

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword`	string	。
`location_code`	integer	地区代码。
`language_code`	string	语言代码。
`keyword_info`	object	指标信息。

`keyword_info`

字段	类型	说明
`se_type`	string	搜索引擎类型。
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-MM-dd HH:mm:ss +00:00`。
`search_volume`	integer	Amazon 平均月搜索量，为该在 Amazon 上的估算月搜索次数。

`ranked_serp_element`

字段	类型	说明
`se_type`	string	搜索引擎类型。
`serp_item`	object	产品在 SERP 中对应的信息。

serp_item 可能以下 SERP素类型：

amazon_serp
amazon_paid
editorial_recommendations
top_rated_from_our_brands
related_searches

Amazon 商品 SERP素

amazon_serp、amazon_paid、editorial_recommendations 和 top_rated_from_our_brands 使用相同的商品字段结构。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`type`	string	素类型。通常为对应的 SERP素名称。
`rank_group`	integer	在相同类型中的组排名。不同类型之间不会用此排名。
`rank_absolute`	integer	在 Amazon SERP 所有中的绝对排名。
`position`	string	素在 SERP 中的对齐位置，可选值为 `left`、`right`。
`xpath`	string	SERP素的 XPath。
`domain`	string	Amazon 域名。
`title`	string	商品标题。
`url`	string	商品页 URL。
`description`	string / null	商品描述。
`asin`	string	商品 ASIN。
`image_url`	string / null	搜索结果中展示的商品图片 URL。
`price_from`	float / null	商品常规起始价格。示例：`49.98`。
`price_to`	float / null	商品价格区间上限。示例：`384.99`。
`currency`	string	ISO 4217 货币代码。示例：`USD`。
`special_offers`	array / null	特价优惠信息优惠券和订购省优惠等。
`is_best_seller`	boolean	是否带有“销商品”标签。
`is_amazon_choice`	boolean	是否带有“平台精选”标签。
`rating`	object	商品评分信息。
`delivery_info`	object / null	送信息。
`check_url`	string	对应的 Amazon 搜索结果 URL，可用于核验返回结果。
`serp_item_types`	array	当前 SERP 中检测到的结果类型。
`se_results_count`	integer	Amazon SERP 中的结果总数。
`last_updated_time`	string	SERP 数据最近更新时间，UTC 格式：`yyyy-MM-dd HH:mm:ss +00:00`。
`previous_updated_time`	string / null	SERP 数据上一次更新时间，ISO 8601 格式，例如 `2020-09-12T00:07:43.0733218Z`。

`rating`

字段	类型	说明
`rating_type`	string	评分类型，可选值 `Max5`、`Percents`、`CustomMax`。
`value`	integer	当前评分值。
`votes_count`	integer	评价数量。
`rating_max`	integer	当前评分类型的最大值。

`delivery_info`

字段	类型	说明
`delivery_message`	string	卖家展示的说明。
`delivery_price`	object / null	根据请求地区计算的费用。若支持，则为 `null`。
`displayed_price`	string	Amazon 商品列表中原样展示的价格文本。

`delivery_price`

字段	类型	说明
`current`	float	当前价格。
`regular`	float	未折扣的常规价格。
`max_value`	float	未折扣价格的最大值。
`currency`	string	ISO 4217 货币代码。
`is_price_range`	boolean	是否为价格区间。

`related_searches`素

当 serp_item 的类型为 related_searches 时，结构如下：

字段	类型	说明
`se_type`	string	搜索引擎类型。
`type`	string	素类型，固定为 `related_searches`。
`rank_group`	integer	同类型中的组排名。
`rank_absolute`	integer	在 Amazon SERP 中的绝对排名。
`xpath`	string	素的 XPath。
`items`	array	搜索项列表。

`related_searches.items`

字段	类型	说明
`type`	string	素类型，固定为 `related_searches_element`。
`title`	string	搜索标题。
`url`	string	搜索或商品页面 URL。
`image_alt`	string	商品图片的替代文本。
`image_url`	string	商品图片 URL。

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/amazon/ranked_keywords/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "asin": "B00R92CL5E",
      "language_name": "English",
      "location_code": 2840,
      "limit": 10
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/amazon/ranked_keywords/live"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "asin": "B00R92CL5E",
        "location_name": "United States",
        "language_name": "English",
        "limit": 10,
    }
]

response = requests.post(url, headers=headers, json=payload)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，状态码：%s，信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    asin: "B00R92CL5E",
    language_name: "English",
    location_code: 2840,
    limit: 10,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/amazon/ranked_keywords/live",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理接口返回结果
    console.log(response.data);
  })
  .catch((error) => {
    // 处理网络或接口错误
    console.error(error.response?.data || error.message);
  });

PHP

php

<?php

$url = 'https://api.seermartech.cn/v3/dataforseo_labs/amazon/ranked_keywords/live';

$payload = [
    [
        'asin' => 'B00R92CL5E',
        'language_name' => 'English',
        'location_code' => 2840,
        'limit' => 10
    ]
];

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE)
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($response === false) {
    echo '请求失败：' . curl_error($ch);
} else {
    $result = json_decode($response, true);

    if (($result['status_code'] ?? null) === 20000) {
        print_r($result);
    } else {
        echo '接口错误：' .
            ($result['status_code'] ?? 'unknown') . ' ' .
            ($result['status_message'] ?? '');
    }
}

curl_close($ch);

C#

csharp

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "smt_live_YOUR_KEY");

var payload = new[]
{
    new
    {
        asin = "B00R92CL5E",
        location_name = "United States",
        language_name = "English",
        limit = 10
    }
};

var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api.seermartech.cn/v3/dataforseo_labs/amazon/ranked_keywords/live",
    content
);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

响应示例

以下为经过简化的有效响应结构示例：

json

{
  "version": "0.1.20220216",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2091 sec.",
  "cost": 0.011,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1800 sec.",
      "cost": 0.011,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "amazon",
        "ranked_keywords",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "ranked_keywords",
        "se_type": "amazon",
        "asin": "B00R92CL5E",
        "location_code": 2840,
        "language_code": "en",
        "limit": 10
      },
      "result": [
        {
          "se_type": "amazon",
          "asin": "B00R92CL5E",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 1250,
          "items_count": 1,
          "items": [
            {
              "se_type": "amazon",
              "keyword_data": {
                "se_type": "amazon",
                "keyword": "network switch gigabit",
                "location_code": 2840,
                "language_code": "en",
                "keyword_info": {
                  "se_type": "amazon",
                  "last_updated_time": "2022-02-04 12:51:48 +00:00",
                  "search_volume": 6800
                }
              },
              "ranked_serp_element": {
                "se_type": "amazon",
                "serp_item": {
                  "se_type": "amazon",
                  "type": "amazon_serp",
                  "rank_group": 57,
                  "rank_absolute": 78,
                  "position": "left",
                  "domain": "www.amazon.com",
                  "title": "Product title",
                  "url": "https://www.amazon.com/example",
                  "description": null,
                  "asin": "B00R92CL5E",
                  "image_url": null,
                  "price_from": 39,
                  "price_to": null,
                  "currency": "USD",
                  "special_offers": null,
                  "is_best_seller": false,
                  "is_amazon_choice": false,
                  "rating": {
                    "rating_type": "Max5",
                    "value": 3,
                    "votes_count": 68918,
                    "rating_max": 5
                  },
                  "delivery_info": null
                },
                "check_url": "https://www.amazon.com/s/?field-keywords=network%20switch%20gigabit",
                "serp_item_types": [
                  "amazon_serp",
                  "related_searches"
                ],
                "se_results_count": 1964,
                "last_updated_time": "2022-02-04 12:00:46 +00:00",
                "previous_updated_time": null
              }
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理

请根据以下字段判断请求和任务是否成功：

顶层 status_code
任务级 tasks[].status_code
对应的 status_message

当状态码不是 20000 时，应记录错误信息并执行重试、告警或人工处理。完整错误码请参考 /v3/appendix/errors。

实用场景

提取商品已获得排名的，扩展标题、五点描述和后台搜索词，提升商品自然覆盖率。
筛选高搜索量但排名靠后的，制定商品页优化计划，优改善潜在流量最大的词。
对比多个 ASIN 的排名和搜索量，识别竞品覆盖而自身缺失的，支持竞品差距分析。
结合 rank_absolute、价格、评分和促销信息分析 SERP 竞争环境，评估前排的难度。
按地区和语言分别获取排名，制定不同 Amazon 站点的本地化 SEO 和选品策略。

Amazon 产品排名（实时） ​

接口说明 ​

计费说明 ​

请求参数 ​

地区和语言 ​

filters 示例 ​

order_by 示例 ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

keyword_data ​

keyword_info ​

ranked_serp_element ​

Amazon 商品 SERP素 ​

rating ​

delivery_info ​

delivery_price ​

related_searches素 ​

related_searches.items ​

请求示例 ​

curl ​

Python ​

TypeScript ​

PHP ​

C# ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​

Amazon 产品排名（实时）

接口说明

计费说明

请求参数

地区和语言

`filters` 示例

`order_by` 示例

响应结构

顶层字段

任务字段

`result` 字段

`items` 字段

`keyword_data`

`keyword_info`

`ranked_serp_element`

Amazon 商品 SERP素

`rating`

`delivery_info`

`delivery_price`

`related_searches`素

`related_searches.items`

请求示例

curl

Python

TypeScript

PHP

C#

响应示例

状态码与错误处理

实用场景