GET / POST /api/keepa/product

按 ASIN 批量拉取 Amazon 产品数据：标题、品牌、分类、图片、价格、历史 CSV、销量排名、评分等全部信息。是 Keepamore 使用频率最高的接口。

对应 Keepa 官方接口：Request Products

接口

GET  https://mcp.keepamore.com/api/keepa/product
POST https://mcp.keepamore.com/api/keepa/product

GET：参数走 Query String，适合 1–10 个 ASIN
POST：参数走 JSON body，ASIN 较多时强烈推荐（避免 URL 长度限制，也更适合包含 dateRange 之类的嵌套字段）

计费

项目	units
单次请求中每个去重后的 ASIN	1

重复 ASIN 会自动去重后再计费（例如传 5 个但其中 2 个重复，按 3 units 扣减）。
offers / rating / buybox / stock / update 等附加参数不会额外计费。
单次请求最少 1 unit（即使 ASIN 列表全部去重后只剩 1 个）。

参数

标 🛠 的为 Keepamore 增强参数——是我们在 Keepa 原始接口基础上的增强字段，用于减小响应体积、提升 AI 上下文友好度，不会改变本接口的计费。

名称	类型	必填	默认	约束	说明
`domain`	integer	✅¹	—	1–12	站点 ID，参见 domain 映射。也可用 `domainId` / `country` 别名
`asins`	string[] / csv	✅	—	1–100，每个 10 位字母数字	ASIN 列表。GET 时可写 `?asins=A,B,C` 或多次 `?asins=A&asins=B`；POST 直接传数组。也可用 `asin` 别名
`stats`	integer		—	≥ 1	统计天数（如 `180`），返回价格统计摘要
`history`	boolean		`true`	`0`/`1` 或 `true/false`	是否返回价格历史 CSV。⚠️ 关掉可大幅减小响应体积
`update`	integer		—	≥ 0	数据新鲜度阈值（小时）。`0` 强制刷新；不传按默认策略
`offers`	integer		—	0–100	返回 offer 数量
`rating`	boolean		`false`	`0`/`1` 或 `true/false`	是否包含评分 / 评论数历史
`buybox`	boolean		`false`	`0`/`1` 或 `true/false`	是否包含 Buy Box 数据
`stock`	boolean		`false`	`0`/`1` 或 `true/false`	是否包含库存数据
🛠 `days`	integer		—	≥ 1	仅返回最近 N 天历史（与 `dateRange` 互斥）。比 `history=true` 体积小很多
🛠 `dateRange`	object / 扁平字段		—	`start` / `end` 为 Unix 毫秒	按时间范围截取历史（与 `days` 互斥，优先）。POST 传 `{start,end}`；GET 用 `dateRangeStart`/`dateRangeEnd`
🛠 `detailLevel`	enum		`lite`	`summary`/`lite`/`full`	产品对象精简级别，详见下文

¹ domain / domainId / country 三选一；同时传入时若不一致会返回 400。

`detailLevel` 取值

级别	含义	适用场景
`summary`	仅核心字段：`asin`、`title`、`brand`、当前价格、评分、销量排名等	AI 上下文敏感、列表展示、首屏摘要
`lite`（默认）	移除 `csv` / `salesRanks` / `variationCSV` 等大字段，保留其他全部	大多数业务场景的最佳平衡
`full`	完整原始 product 对象，与 Keepa 官方一致	需要离线分析或下游再处理

响应

json

{
	"code": "0000",
	"msg": "ok",
	"data": {
		"country": "us",
		"count": 2,
		"products": [
			{
				"asin": "B08N5WRWNW",
				"title": "...",
				"brand": "..." /* 见字段说明 */
			}
		],
		"errors": [{ "asin": "B0DEADBEEF", "errorId": "uuid-..." }],
		"responseShape": { "detailLevel": "lite", "hint": "..." }
	},
	"metadata": {
		/* 见 errors.md */
	}
}

批量请求中部分 ASIN 失败不会让整个请求失败：成功的进入 products，失败的进入 errors 并附带可用于工单追溯的 errorId。
产品对象字段定义详见 Product Object 字段速查；其中 stats 子对象详见 Statistics Object；KeepaTime / cents / csv 二维数组等共用约定详见字段速查 · 公共约定。

示例

bash

# 请将 km_xxx 替换为你的 API Key
# 1) GET，单个 ASIN，最小调用（摘要）
curl "https://mcp.keepamore.com/api/keepa/product?domain=1&asins=B08N5WRWNW&detailLevel=summary" \
  -H "X-API-Key: km_xxx"

# 2) GET，批量 + 最近 90 天历史 + 30 天统计
curl "https://mcp.keepamore.com/api/keepa/product?domain=1&asins=B08N5WRWNW,B0BSHF7WHW&days=90&stats=30" \
  -H "X-API-Key: km_xxx"

# 3) POST，长 ASIN 列表 / 嵌套 dateRange
curl -X POST "https://mcp.keepamore.com/api/keepa/product" \
  -H "X-API-Key: km_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": 1,
    "asins": ["B08N5WRWNW", "B0BSHF7WHW", "B09JQMJSXY"],
    "stats": 30,
    "detailLevel": "lite",
    "dateRange": { "start": 1704067200000, "end": 1717200000000 }
  }'

// 请将 km_xxx 替换为你的 API Key
const URL = "https://mcp.keepamore.com/api/keepa/product";
const HEADERS = { "X-API-Key": "km_xxx" };

// 1) GET：单个 ASIN，摘要
const r1 = await fetch(`${URL}?domain=1&asins=B08N5WRWNW&detailLevel=summary`, {
	headers: HEADERS,
});
console.log(await r1.json());

// 2) POST：批量 + 90 天历史
const r2 = await fetch(URL, {
	method: "POST",
	headers: { ...HEADERS, "Content-Type": "application/json" },
	body: JSON.stringify({
		domain: 1,
		asins: ["B08N5WRWNW", "B0BSHF7WHW"],
		stats: 30,
		days: 90,
		detailLevel: "lite",
	}),
});
console.log(await r2.json());

python

# 请将 km_xxx 替换为你的 API Key
import requests

URL = "https://mcp.keepamore.com/api/keepa/product"
HEADERS = {"X-API-Key": "km_xxx"}

# 1) GET：单个 ASIN，摘要
r1 = requests.get(URL, params={"domain": 1, "asins": "B08N5WRWNW", "detailLevel": "summary"},
                  headers=HEADERS, timeout=180)
print(r1.json())

# 2) POST：批量 + 90 天历史
r2 = requests.post(URL, json={
    "domain": 1,
    "asins": ["B08N5WRWNW", "B0BSHF7WHW"],
    "stats": 30,
    "days": 90,
    "detailLevel": "lite",
}, headers=HEADERS, timeout=180)
print(r2.json())

php

<?php
// 请将 km_xxx 替换为你的 API Key
require 'vendor/autoload.php';
use GuzzleHttp\Client;

$client = new Client();
$resp = $client->post('https://mcp.keepamore.com/api/keepa/product', [
    'headers' => [
        'X-API-Key'    => 'km_xxx',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'domain'      => 1,
        'asins'       => ['B08N5WRWNW', 'B0BSHF7WHW'],
        'stats'       => 30,
        'days'        => 90,
        'detailLevel' => 'lite',
    ],
    'timeout' => 180,
]);
echo $resp->getBody();

java

// 请将 km_xxx 替换为你的 API Key（Java 11+ 标准库）
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

String body = """
    {"domain":1,"asins":["B08N5WRWNW","B0BSHF7WHW"],
     "stats":30,"days":90,"detailLevel":"lite"}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://mcp.keepamore.com/api/keepa/product"))
    .header("X-API-Key", "km_xxx")
    .header("Content-Type", "application/json")
    .timeout(Duration.ofSeconds(180))
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

// 请将 km_xxx 替换为你的 API Key（Go 标准库 net/http + encoding/json）
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "domain":      1,
        "asins":       []string{"B08N5WRWNW", "B0BSHF7WHW"},
        "stats":       30,
        "days":        90,
        "detailLevel": "lite",
    })

    req, _ := http.NewRequest("POST",
        "https://mcp.keepamore.com/api/keepa/product", bytes.NewReader(body))
    req.Header.Set("X-API-Key", "km_xxx")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{Timeout: 180 * time.Second}
    resp, err := client.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    out, _ := io.ReadAll(resp.Body)
    fmt.Println(string(out))
}

典型配方

场景	建议参数
AI 快速问价 / 摘要展示	`detailLevel=summary` + `history=false` + `stats=180`
画 90 天价格曲线	`detailLevel=lite` + `days=90`
完整选品分析	`detailLevel=full` + `offers=20` + `rating=1` + `buybox=1`
实时报价	加 `update=0`
批量 50+ ASIN	改用 `POST` + JSON body，`asins` 直接传数组

错误处理

通用错误码、metadata 字段定义见错误码总览。常见情况：

缺少 asins、ASIN 数量超过 100、domain 与 country 同时传入但不一致 → HTTP 400，code 以 VALIDATION 开头
单条 ASIN 上游不可达：整体仍返回 200，对应 ASIN 出现在 data.errors[] 中，可凭 errorId 联系支持
全量请求被上游拒绝 → HTTP 502，code = UPSTREAM_ERROR

对应 MCP 工具

keepa_get_product

GET / POST /api/keepa/product ​

接口 ​

计费 ​

参数 ​

detailLevel 取值 ​

响应 ​

示例 ​

典型配方 ​

错误处理 ​

对应 MCP 工具 ​

GET / POST /api/keepa/product

接口

计费

参数

`detailLevel` 取值

响应

示例

典型配方

错误处理

对应 MCP 工具