关键词：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 依赖
<!-- 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 ...八、频率 & 限额
| 版本 | 日调用量 | 频率 | 备注 |
|---|---|---|---|
| 免费 | 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 行即可跑通。生产环境务必「本地缓存 + 限流 + 重试」，避免额度浪费。
如遇任何疑问或有进一步的需求，请随时与我私信或者评论联系。
