Java 实战：调用 item_search_tmall 按关键词搜索天猫商品
关键词：Java、天猫搜索、item_search_tmall、关键词、聚合 API
一、接口背景
淘宝/天猫官方并未对外公开「关键词搜索商品」接口。
目前 GitHub 与各大云市场上出现的
目前 GitHub 与各大云市场上出现的
item_search_tmall 均属于第三方数据服务商（万邦、OneBound、凡邦等）基于「淘宝联盟+自营爬虫」二次封装的聚合 API，字段丰富、接入简单，适合「内部选品、价格监控、快速 MVP」等场景。本文以 万邦 为例，给出完整 Java 调用示例，支持分页、排序、价格区间、仅天猫过滤。
二、接口速览
| 地址 | https://api-gw.onebound.cn/taobao/item_search_tmall |
|---|---|
| 方法 | 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 依赖
xml
<!-- 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
@Datapublic 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 示例（节选）
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 方法一键运行
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 行即可跑通。 - 生产环境务必「本地缓存 + 限流 + 重试」，避免额度浪费。
