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

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

一、接口背景

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

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

二、接口速览

三、Maven 依赖

<!-- 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>

四、统一入参实体

@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）

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 示例（节选）

{ "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 方法一键运行

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 ...

八、频率 & 限额

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

九、常见异常对照

十、小结

1. 天猫「关键词搜索」官方不对外开放，只能用第三方聚合接口。

2. 万邦item_search_tmall字段齐全、接入简单，Java 示例 30 行即可跑通。

3. 生产环境务必「本地缓存 + 限流 + 重试」，避免额度浪费。

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