Java 实战：调用 item_search_tmall 按关键词搜索天猫商品

关键词：Java、天猫搜索、item_search_tmall、关键词、聚合 API

一、接口背景

淘宝/天猫官方并未对外公开「关键词搜索商品」接口。

目前 GitHub 与各大云市场上出现的 item_search_tmall 均属于第三方数据服务商（万邦、OneBound、凡邦等）基于「淘宝联盟+自营爬虫」二次封装的聚合 API，字段丰富、接入简单，适合「内部选品、价格监控、快速 MVP」等场景。

本文以万邦为例，给出完整 Java 调用示例，支持分页、排序、价格区间、仅天猫过滤。

二、接口速览

地址
方法	GET
鉴权	key + secret（平台颁发）
关键词	q=xxx
分页	page=1&page_size=20（最大 40）
排序	sort=sale_desc（销量降序）、price_asc（价格升序）...
过滤	filter=tmall（只返回天猫）
返回	JSON；含 total、page、item[]；单条含 num_iid、title、price、pic、sales、shop_type 等

三、Maven 依赖

python 复制代码

<!-- HTTP -->
<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.0</version>
</dependency>
<!-- JSON -->
<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.43</version>
</dependency>

四、统一入参实体

java 复制代码

@Data
public class TmallSearchReq {
    private String key;
    private String secret;
    private String q;           // 关键词
    private int page = 1;
    private int pageSize = 20;  // 最大 40
    private String sort;        // sale_desc | price_asc | price_desc
    private String filter;      // tmall
    private String startPrice;
    private String endPrice;
}

五、核心 Service（OkHttp + FastJSON）

java 复制代码

public class TmallSearchService {

    private static final String API = "https://api-gw.onebound.cn/taobao/item_search_tmall";

    public static JSONObject search(TmallSearchReq req) throws IOException {
        HttpUrl.Builder ub = HttpUrl.parse(API).newBuilder();
        ub.addQueryParameter("key", req.getKey());
        ub.addQueryParameter("secret", req.getSecret());
        ub.addQueryParameter("q", req.getQ());
        ub.addQueryParameter("page", String.valueOf(req.getPage()));
        ub.addQueryParameter("page_size", String.valueOf(req.getPageSize()));
        if (req.getSort() != null) ub.addQueryParameter("sort", req.getSort());
        if (req.getFilter() != null) ub.addQueryParameter("filter", req.getFilter());
        if (req.getStartPrice() != null) ub.addQueryParameter("start_price", req.getStartPrice());
        if (req.getEndPrice() != null) ub.addQueryParameter("end_price", req.getEndPrice());

        Request httpReq = new Request.Builder()
                .url(ub.build())
                .get()
                .header("Accept-Encoding", "gzip")
                .build();

        try (Response resp = new OkHttpClient().newCall(httpReq).execute()) {
            String json = resp.body().string();
            JSONObject root = JSON.parseObject(json);
            if (!"200".equals(root.getString("code"))) {
                throw new RuntimeException("API 错误：" + root.getString("msg"));
            }
            return root.getJSONObject("items");
        }
    }
}

六、返回 JSON 示例（节选）

java 复制代码

{
  "code": 200,
  "items": {
    "page": "1",
    "page_size": 20,
    "total_results": 842,
    "item": [
      {
        "num_iid": "723971306902",
        "title": "iPhone15 液态硅胶手机壳",
        "pic_url": "//g-search3.alicdn.com/img/imgextra/...jpg",
        "price": "28.8",
        "orginal_price": "88.0",
        "sales": 3200,
        "shop_type": "天猫",
        "detail_url": "https://detail.tmall.com/item.htm?id=723971306902"
      }
      // ... 19 more
    ]
  }
}

字段说明见万邦文档。

七、Main 方法一键运行

java 复制代码

public class Demo {
    public static void main(String[] args) throws Exception {
        TmallSearchReq req = new TmallSearchReq();
        req.setKey("你的key");
        req.setSecret("你的secret");
        req.setQ("空气净化器");
        req.setPage(1);
        req.setPageSize(20);
        req.setSort("sale_desc");   // 销量降序
        req.setFilter("tmall");     // 仅天猫

        JSONObject result = TmallSearchService.search(req);
        JSONArray list = result.getJSONArray("item");
        list.forEach(o -> {
            JSONObject l = (JSONObject) o;
            System.out.println(
                l.getString("num_iid") + "\t" +
                l.getString("title") + "\t" +
                l.getBigDecimal("price") + "\t" +
                l.getInteger("sales"));
        });
    }
}

控制台输出（示例）：

复制代码

723971306902	iPhone15 液态硅胶手机壳	28.8	3200
...

八、频率 & 限额

版本	日调用量	频率	备注
免费	100/IP	1 qps	足够测试
基础	10 k	5 qps	59 元/月
高级	100 k	20 qps	可谈折扣

超出返回 429，需做指数退避重试。

九、常见异常对照

返回码	含义	解决
400	参数为空	检查 q、key、secret
403	IP 未在白名单	控制台绑定出口 IP
429	频率超限	降速或升级套餐
5003	关键词无结果	换词或去掉价格区间

十、小结

天猫「关键词搜索」官方不对外开放，只能用第三方聚合接口。
万邦 item_search_tmall 字段齐全、接入简单，Java 示例 30 行即可跑通。
生产环境务必「本地缓存 + 限流 + 重试」，避免额度浪费。

如遇任何疑问或有进一步的需求，请随时与我私信或者评论联系。