京东商品列表API技术解析与落地应用（含标准 JSON 示例）

摘要 ：在电商 ERP 开发、跨平台选品、竞品价格监控、类目数据分析业务中，经常需要通过关键词批量获取京东平台商品摘要数据。jd.item_search京东商品列表 API 支持关键词检索、类目筛选、价格区间过滤、分页排序，返回商品标题、售价、销量、主图、店铺等摘要信息。本文从接口概述、请求入参、返回字段解析、标准 JSON 样例、业务处理流程、开发踩坑、落地场景完整讲解，适合电商后端、数据采集、ERP 系统开发者参考。

一、接口概述

jd.item_search 京东商品列表搜索接口，作为京东商品批量检索入口，输入关键词或者类目 ID 获取京东 POP 自营混合的商品摘要集合。

jd.item_search 京东商品列表搜索接口，作为商品批量检索入口，输入关键词或类目 ID 获取淘宝、京东商品摘要集合。

• 接口标识：taobao.item_search （淘宝商品列表API，taobaoapi2014前往体验）
• 请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）
• 接口版本：2.0

接口能力覆盖

1. 商品基础元数据：标题、售卖价、划线价、销量
2. 基础素材：商品主图 CDN 地址
3. 店铺信息：店铺 ID、店铺名称，区分自营 / POP 店铺
4. 辅助标记：广告商品标识、类目信息、发货地、自营标识

二、核心请求入参

参数	类型	必填	说明
q	string	是	搜索关键词
cat	int	否	类目 ID，限定类目下检索
page	int	是	页码，起始为 1
page_size	int	否	单页返回条数，受接口最大限制
sort	string	否	排序规则：综合、销量、价格升序、价格降序
start_price	float	否	价格筛选‑最低价格
end_price	float	否	价格筛选‑最高价格

三、返回数据结构解析

顶层响应结构

字段	类型	说明
code	int	0调用成功；非 0 代表异常错误码
message	string	提示信息，成功返回ok，失败返回错误描述
data	object	搜索业务主体对象

data 对象字段

字段	类型	说明
total	int	搜索预估总商品数量，仅做参考，不可直接作为分页循环依据
page	int	当前请求页码
page_size	int	每页返回商品条数
page_count	int	预估总页数；接口存在翻页深度限制，该字段仅供参考
item_list	arrayobject	商品摘要数组，核心数据集

item_list 单条商品对象字段

字段	类型	说明
num_iid	bigint	京东商品 ID，调用商品详情接口入参
title	string	商品完整标题
price	float	商品促销售卖价格
original_price	float	划线原价，无则返回 0
pic_url	string	商品主图 CDN 地址
sales	int	商品近 30 天销量
shop_id	bigint	店铺 ID
seller_nick	string	店铺名称
is_jd_self	boolean	true = 京东自营，false=POP 第三方店铺
cat_id	int	类目 ID
cat_name	string	类目完整名称
location	string	发货地，例：北京
item_url	string	商品 H5 链接
is_ad	boolean	是否广告推广商品，true 为付费广告，数据分析建议过滤

四、标准 JSON 返回示例

{
    "code": 0,
    "message": "ok",
    "data": {
        "total": 28600,
        "page": 1,
        "page_size": 20,
        "page_count": 1430,
        "item_list": [
            {
                "num_iid": 100089654721,
                "title":"2026夏季纯棉短袖T恤男女宽松百搭上衣",
                "price":69.90,
                "original_price":129.00,
                "pic_url":"https://img14.360buyimg.com/n1/demo.jpg",
                "sales":21560,
                "shop_id":1000123456,
                "seller_nick":"京东服饰自营店",
                "is_jd_self":true,
                "cat_id":1319,
                "cat_name":"服饰>T恤",
                "location":"北京",
                "item_url":"https://item.jd.com/100089654721.html",
                "is_ad":false
            }
        ]
    }
}

五、完整业务处理流程

1. 传入关键词、页码、价格区间等参数调用jd.item_search；
2. 判断顶层code状态码，捕获接口调用异常；
3. 读取data.item_list商品摘要数组；数组为空直接终止分页，不要依赖 total、page_count 做循环条件；
4. 业务按需过滤广告商品is_ad=true；
5. 将商品摘要存入候选商品池，保存num_iid，用于后续详情接口调用；
6. 异步任务批量调用京东商品详情接口，补齐 SKU、图集、参数、详情 HTML；
7. 图片资源下载转存自有对象存储，处理京东 CDN 防盗链 403 问题；
8. 清洗数据后入库，供给选品、铺货、竞品监控业务模块。

六、开发高频踩坑总结

1. 分页深度限制 京东搜索接口存在最大翻页上限，total、page_count只是预估值。禁止根据总页数循环分页，业务以 item_list 为空作为终止条件。
2. 自营与 POP 店铺区分 is_jd_self字段区分自营店铺与第三方 POP 店铺，做选品、竞品统计业务经常需要做店铺类型过滤。自营商品物流、售后规则和 POP 店铺差异较大。
3. 广告商品干扰数据 is_ad=true为付费推广商品，做类目价格、销量统计时建议过滤，避免统计结果失真。
4. 图片防盗链 京东 CDN 图片自带防盗链，直接对外展示会 403 裂图，业务系统需要下载图片转存自有存储。
5. 接口限流管控 多关键词批量搜索极易触发限流；大批量任务接入任务队列，控制 QPS，增加休眠、指数退避重试。
6. 下架商品兼容 搜索结果会混入已下架商品，列表接口无法识别商品真实状态；入库后建议搭配详情接口二次校验商品有效性。
7. 接口能力边界 列表只拿到摘要，不要尝试用列表接口做商品刊登；完整 SKU、参数、详情内容必须依赖jd.item_get。

七、Python 简易调用伪代码

def fetch_jd_item_search(keyword, page=1):
    resp = call_jd_item_search_api(q=keyword, page=page, page_size=20)
    if resp.get("code") != 0:
        print("接口调用失败", resp.get("message"))
        return []
    item_list = resp.get("data", {}).get("item_list", [])
    save_candidate_goods(item_list)
    return item_list

# 调用示例
goods_list = fetch_jd_item_search("夏季纯棉T恤", page=1)

八、落地业务场景

1. ERP 跨平台铺货系统：批量获取京东候选商品池，用于选品采集
2. 竞品价格监控：定时抓取关键词商品快照，跟踪价格销量变化
3. 电商数据分析：类目商品价格、销量分布统计，区分自营 / POP 做对比分析
4. 货源溯源业务：配合图像检索接口，批量检索同款商品
5. CPS 导购分销业务：批量获取商品基础信息做初步筛选

九、总结

jd.item_search京东商品列表 API，是京东商品数据采集的检索入口，主要获取商品摘要数据集。开发难点不在于简单接口调用，而在于分页边界处理、自营 / POP 店铺识别、限流重试、图片防盗链处理。同时要明确接口能力边界，必须搭配商品详情 API 拿到完整商品数据。处理好以上工程细节，接口可以稳定支撑选品、竞品监控、ERP 铺货、CPS 导购等电商业务系统。