GET /api/categorysearch

按关键词搜索 Amazon 分类，返回匹配的分类列表。常用于在 Product Finder 之前定位类目 ID。

接口

GET https://mcp.keepamore.com/api/categorysearch

计费

项目	units
任意一次成功调用	1

任何参数都不会改变本接口的计费金额。

参数（Query String）

名称	类型	必填	默认	约束	说明
domain	integer	✅	—	1–12	站点 ID，参见 domain 映射。也可用 domainId / country 别名
term	string	✅	—	非空	搜索关键词。框架会自动 URL encode，无需手动转义

响应

{
	"code": "0000",
	"msg": "ok",
	"data": {
		"categories": [{ "catId": 12097479011, "name": "Earbud Headphones" }],
		"fromCache": false
	}
}

返回的每个分类对象的完整字段（parent / children / productCount / avgBuyBox / topBrands 等）见 Category Object。

示例

cURL

# 请将 km_xxx 替换为你的 API Key
curl "https://mcp.keepamore.com/api/categorysearch?domain=1&term=earbuds" \
  -H "X-API-Key: km_xxx"

JavaScript

// 请将 km_xxx 替换为你的 API Key
const r = await fetch(
	"https://mcp.keepamore.com/api/categorysearch?domain=1&term=earbuds",
	{ headers: { "X-API-Key": "km_xxx" } },
);
console.log(await r.json());

Python

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

resp = requests.get(
    "https://mcp.keepamore.com/api/categorysearch",
    params={"domain": 1, "term": "earbuds"},
    headers={"X-API-Key": "km_xxx"},
    timeout=60,
)
print(resp.json())

PHP

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

$client = new Client();
$resp = $client->get('https://mcp.keepamore.com/api/categorysearch', [
    'headers' => ['X-API-Key' => 'km_xxx'],
    'query'   => ['domain' => 1, 'term' => 'earbuds'],
    'timeout' => 60,
]);
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;

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://mcp.keepamore.com/api/categorysearch?domain=1&term=earbuds"))
    .header("X-API-Key", "km_xxx")
    .timeout(Duration.ofSeconds(60))
    .GET()
    .build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

Go

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

import (
    "fmt"
    "io"
    "net/http"
    "time"
)

func main() {
    url := "https://mcp.keepamore.com/api/categorysearch?domain=1&term=earbuds"
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("X-API-Key", "km_xxx")

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

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

典型工作流

1. categorysearch 用关键词定位 catId
2. category 查该分类下的子分类，进一步细化
3. productfinder 用 categories_include: [catId] 做精细筛选

错误处理

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

• 缺少 term / domain，或 term 为空 → HTTP 400，code 以 VALIDATION 开头
• 上游数据源拒绝或不可达 → HTTP 502，code = UPSTREAM_ERROR，可携带 metadata.errorId 联系支持

对应 MCP 工具

kmore_category_search