京东的 item_get_app 接口是用于获取商品原始详情数据的核心接口，与普通的 item_get 接口相比，它返回的数据更贴近京东 APP 端展示的原始结构，包含更丰富的字段和细节信息。这些原始数据对于深度电商分析、竞品监控、价格追踪等场景具有重要价值。
一、接口核心特性分析
1. 接口功能与定位
2. 认证机制
3. 核心参数与响应结构
请求参数
响应核心字段
二、Python 脚本实现
以下是调用京东 item_get_app 接口的完整 Python 实现，包含令牌获取、接口调用、数据解析等功能：
import requests
import time
import json
import logging
import hashlib
from typing import Dict, Optional, List
from requests.exceptions import RequestException
# 配置日志
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s"
)
class JDItemGetAppAPI:
def __init__(self, appkey: str, appsecret: str):
"""
初始化京东商品详情原数据API客户端
:param appkey: 京东开放平台appkey
:param appsecret: 京东开放平台appsecret
"""
self.appkey = appkey
self.appsecret = appsecret
self.base_url = "https://api.jd.com"
self.access_token = None
self.token_expires_at = 0 # token过期时间戳
self.session = requests.Session()
self.session.headers.update({
"Content-Type": "application/json",
"User-Agent": "JDApp;android;9.5.4;android 10;scale/3.0" # 模拟京东APP请求头
})
def _get_access_token(self) -> Optional[str]:
"""获取访问令牌"""
# 检查token是否有效
if self.access_token and self.token_expires_at > time.time() + 60:
return self.access_token
logging.info("获取新的access_token")
url = f"{self.base_url}/oauth2/token"
params = {
"grant_type": "client_credentials",
"appkey": self.appkey,
"appsecret": self.appsecret
}
try:
response = self.session.get(url, params=params, timeout=10)
response.raise_for_status()
result = response.json()
if "access_token" in result:
self.access_token = result["access_token"]
self.token_expires_at = time.time() + result.get("expires_in", 86400) # 默认为24小时
return self.access_token
else:
logging.error(f"获取access_token失败: {result.get('error_description', '未知错误')}")
return None
except RequestException as e:
logging.error(f"获取access_token请求异常: {str(e)}")
return None
def get_item_raw_data(self,
sku_id: str,
platform: str = "android",
area: str = "1_72_2799_0", # 默认地区编码：北京
fields: Optional[str] = None) -> Optional[Dict]:
"""
获取商品原始详情数据
:param sku_id: 商品SKU ID
:param platform: 平台类型
:param area: 地区编码
:param fields: 需要返回的字段
:return: 商品原始数据
"""
# 验证参数
valid_platforms = ["android", "ios"]
if platform not in valid_platforms:
logging.error(f"无效的平台类型: {platform}，支持: {valid_platforms}")
return None
# 获取有效的access_token
if not self._get_access_token():
return None
url = f"{self.base_url}/item/get_app"
# 构建请求参数
params = {
"sku_id": sku_id,
"access_token": self.access_token,
"platform": platform,
"area": area,
"timestamp": int(time.time() * 1000) # 时间戳，毫秒级
}
# 添加字段筛选
if fields:
params["fields"] = fields
# 生成签名（部分接口需要）
params["sign"] = self._generate_sign(params)
try:
response = self.session.get(url, params=params, timeout=20)
response.raise_for_status()
result = response.json()
# 检查响应状态
if result.get("code") == 200:
# 格式化原始数据
return self._process_raw_data(result.get("data", {}))
else:
logging.error(f"获取商品数据失败: {result.get('message', '未知错误')} (错误码: {result.get('code')})")
return None
except RequestException as e:
logging.error(f"获取商品数据请求异常: {str(e)}")
return None
except json.JSONDecodeError:
logging.error(f"商品数据响应解析失败: {response.text[:200]}...")
return None
def _generate_sign(self, params: Dict) -> str:
"""生成签名（部分京东接口需要）"""
# 按参数名排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 拼接参数
sign_str = self.appsecret
for k, v in sorted_params:
if k != "sign":
sign_str += f"{k}{v}"
sign_str += self.appsecret
# SHA256加密
return hashlib.sha256(sign_str.encode()).hexdigest().upper()
def _process_raw_data(self, raw_data: Dict) -> Dict:
"""处理原始数据，提取关键信息并格式化"""
# 基础信息提取
base_info = {
"sku_id": raw_data.get("skuId"),
"spu_id": raw_data.get("spuId"),
"item_id": raw_data.get("itemId"),
"title": raw_data.get("skuName"),
"sub_title": raw_data.get("skuSubName"),
"brand": {
"id": raw_data.get("brandId"),
"name": raw_data.get("brandName")
},
"category": {
"cid1": raw_data.get("cid1"),
"cid2": raw_data.get("cid2"),
"cid3": raw_data.get("cid3"),
"name1": raw_data.get("cateName1"),
"name2": raw_data.get("cateName2"),
"name3": raw_data.get("cateName3")
},
"url": f"https://item.jd.com/{raw_data.get('skuId')}.html" if raw_data.get('skuId') else None
}
# 价格信息提取
price_info = {
"jd_price": self._safe_float(raw_data.get("jdPrice", {}).get("p")), # 京东价
"market_price": self._safe_float(raw_data.get("marketPrice", {}).get("p")), # 市场价
"vip_price": self._safe_float(raw_data.get("vipPrice", {}).get("p")), # 会员价
"plus_price": self._safe_float(raw_data.get("plusPrice", {}).get("p")), # PLUS会员价
"promotion_price": self._safe_float(raw_data.get("promotionPrice", {}).get("p")), # 促销价
"price_history": raw_data.get("priceHistory"), # 价格历史
"price_tags": raw_data.get("priceTags", []) # 价格标签
}
# 库存信息提取
stock_info = {
"stock_num": self._safe_int(raw_data.get("stock", {}).get("stockNum")), # 库存数量
"stock_state": raw_data.get("stock", {}).get("stockState"), # 库存状态
"stock_state_name": raw_data.get("stock", {}).get("stockStateName"), # 库存状态名称
"limit_buy": self._safe_int(raw_data.get("limitBuy")), # 限购数量
"area_stock": raw_data.get("areaStock") # 区域库存信息
}
# 规格信息提取
sku_info = {
"total_sku": self._safe_int(raw_data.get("totalSku")), # 总规格数量
"sku_list": self._format_sku_list(raw_data.get("skuList", [])), # 规格列表
"spec_list": self._format_spec_list(raw_data.get("specList", [])) # 规格参数
}
# 促销信息提取
promotion_info = {
"promotions": raw_data.get("promotion", {}).get("promotionList", []), # 促销活动列表
"coupons": raw_data.get("couponList", []), # 优惠券列表
"gift_list": raw_data.get("giftList", []), # 赠品列表
"seckill_info": raw_data.get("seckillInfo") # 秒杀信息
}
# 图片信息提取
image_info = {
"main_images": self._extract_images(raw_data.get("mainImgList", [])), # 主图列表
"detail_images": self._extract_images(raw_data.get("detailImgList", [])), # 详情图列表
"video_url": raw_data.get("videoInfo", {}).get("videoUrl") # 视频URL
}
# 服务信息提取
service_info = {
"after_sale_service": raw_data.get("afterSaleService"), # 售后服务
"delivery_service": raw_data.get("deliveryService"), # 配送服务
"install_service": raw_data.get("installService"), # 安装服务
"warranty": raw_data.get("warranty") # 保修信息
}
return {
"base_info": base_info,
"price_info": price_info,
"stock_info": stock_info,
"sku_info": sku_info,
"promotion_info": promotion_info,
"image_info": image_info,
"service_info": service_info,
"raw_data": raw_data # 保留原始数据
}
def _safe_float(self, value) -> float:
"""安全转换为float"""
try:
return float(value) if value is not None else 0.0
except (ValueError, TypeError):
return 0.0
def _safe_int(self, value) -> int:
"""安全转换为int"""
try:
return int(value) if value is not None else 0
except (ValueError, TypeError):
return 0
def _format_sku_list(self, sku_list: List[Dict]) -> List[Dict]:
"""格式化SKU列表"""
formatted = []
for sku in sku_list:
formatted.append({
"sku_id": sku.get("skuId"),
"name": sku.get("name"),
"price": self._safe_float(sku.get("jdPrice", {}).get("p")),
"stock_num": self._safe_int(sku.get("stockNum")),
"specs": sku.get("specs"),
"image_url": sku.get("imgUrl"),
"status": sku.get("status")
})
return formatted
def _format_spec_list(self, spec_list: List[Dict]) -> List[Dict]:
"""格式化规格参数列表"""
formatted = []
for spec in spec_list:
formatted.append({
"name": spec.get("name"),
"values": [
{
"name": val.get("name"),
"image_url": val.get("imgUrl"),
"selected": val.get("selected", False)
} for val in spec.get("valueList", [])
]
})
return formatted
def _extract_images(self, image_list: List[Dict]) -> List[str]:
"""提取图片URL列表"""
images = []
for img in image_list:
if isinstance(img, dict):
url = img.get("url")
if url:
images.append(url)
elif isinstance(img, str):
images.append(img)
return images
def compare_prices(self, current_data: Dict, previous_data: Dict) -> Dict:
"""比较两个时间点的价格差异"""
if not current_data or not previous_data:
return {}
price_changes = {}
price_types = ["jd_price", "market_price", "vip_price", "plus_price", "promotion_price"]
for price_type in price_types:
current = current_data["price_info"][price_type]
previous = previous_data["price_info"][price_type]
if current != previous:
change = current - previous
change_percent = (change / previous) * 100 if previous != 0 else 0
price_changes[price_type] = {
"current": current,
"previous": previous,
"change": round(change, 2),
"change_percent": round(change_percent, 2)
}
return {
"has_change": len(price_changes) > 0,
"changes": price_changes,
"compared_at": time.strftime("%Y-%m-%d %H:%M:%S")
}
# 示例调用
if __name__ == "__main__":
# 替换为实际的appkey和appsecret（从京东开放平台获取）
APPKEY = "your_appkey"
APPSECRET = "your_appsecret"
# 替换为目标商品SKU ID
SKU_ID = "100012345678"
# 初始化API客户端
api = JDItemGetAppAPI(APPKEY, APPSECRET)
# 获取商品原始数据
item_data = api.get_item_raw_data(
sku_id=SKU_ID,
platform="android",
area="1_72_2799_0" # 北京地区编码
# fields="skuId,skuName,jdPrice,stock" # 可选，指定需要的字段
)
if item_data:
print(f"=== 京东商品详情 (SKU: {SKU_ID}) ===")
print(f"商品名称: {item_data['base_info']['title']}")
print(f"品牌: {item_data['base_info']['brand']['name']}")
print(f"分类: {item_data['base_info']['category']['name1']} > {item_data['base_info']['category']['name2']} > {item_data['base_info']['category']['name3']}")
print(f"京东价: {item_data['price_info']['jd_price']}元")
if item_data['price_info']['promotion_price'] and item_data['price_info']['promotion_price'] < item_data['price_info']['jd_price']:
print(f"促销价: {item_data['price_info']['promotion_price']}元")
if item_data['price_info']['vip_price'] and item_data['price_info']['vip_price'] < item_data['price_info']['jd_price']:
print(f"会员价: {item_data['price_info']['vip_price']}元")
print(f"库存状态: {item_data['stock_info']['stock_state_name']}")
print(f"规格数量: {item_data['sku_info']['total_sku']}")
print(f"主图数量: {len(item_data['image_info']['main_images'])}")
print(f"促销活动数量: {len(item_data['promotion_info']['promotions'])}")
# 打印前3个规格信息
if item_data['sku_info']['sku_list']:
print("\n规格信息:")
for i, sku in enumerate(item_data['sku_info']['sku_list'][:3], 1):
print(f" {i}. {sku['name']}: {sku['price']}元 (库存: {sku['stock_num']})")
# 打印主要促销活动
if item_data['promotion_info']['promotions']:
print("\n促销活动:")
for i, promo in enumerate(item_data['promotion_info']['promotions'][:3], 1):
print(f" {i}. {promo.get('title')}")