新京报作为国内主流权威媒体，其热榜数据聚焦时政热点、社会民生、财经科技等核心领域，兼具时效性与公信力。item_search 热榜接口是批量获取平台实时热榜、分类热榜及热点关联数据的核心入口，支持按热榜类型、时间范围、热度排序等条件筛选，广泛应用于舆情监测、热点追踪、资讯聚合、数据研究等场景。
本攻略结合新京报热榜数据特性（热点更新快、分类维度细、数据结构化强、版权规范严格），从接口认知、前置准备、实操落地、调试优化到进阶技巧，全方位拆解对接流程，兼顾入门易用性与生产级稳定性，帮助开发者快速实现高效对接。
核心功能：通过 item_search 接口获取新京报全品类热榜数据，支持 “全站热榜 + 分类热榜” 双维度查询，返回热榜排名、标题、热度值、发布时间、关联话题等核心信息，可进一步联动 item_get 接口获取内容详情；
平台特性：热榜数据实时更新（1-5 分钟刷新一次），分类覆盖时政、社会、财经、科技、文化、娱乐、体育等领域，热度值基于阅读量、互动量（评论 / 转发 / 点赞）、传播范围综合计算，权威性与参考性强；
典型应用：
舆情监测：实时追踪社会热点、政策动态，快速捕获公众关注焦点；
热点追踪：搭建热点聚合平台，展示新京报官方热榜及关联内容；
数据研究：分析热点传播规律、公众关注偏好，支撑学术或商业研究；
内容运营：为资讯平台、新媒体账号提供热点选题参考，提升内容时效性。
注：热榜类型 hot_type 支持的取值（以官方文档为准）：
热榜核心信息：排名（rank，热榜实时排名，1 为 TOP1）、热度值（hot_value，平台综合计算的热度分数，数值越高热度越高）、热度等级（hot_level，如 “爆”“热”“新”，用于快速识别热点强度）、热榜标签（hot_tag，如 “实时热点”“今日 TOP3”“政策解读”）；
内容基础信息：内容 ID（item_id，可关联item_get接口获取详情）、标题（title，含副标题，简洁呈现热点核心）、摘要（summary，热点核心事件提炼，部分热榜返回）、详情页 URL（detail_url）、来源（source，如 “新京报”“新京报贝壳财经”“新京报我们视频”）、所属栏目（column，如 “时政要闻”“社会热点”）、内容类型（type：news/report/video/comment，热榜支持多类型内容）；
时间与传播数据：发布时间（pub_time，精确到秒，实时热榜聚焦近期内容）、更新时间（update_time，热榜排名更新时间）、互动数据（interact_data：评论量 comment_count、转发量 share_count、点赞量 like_count、收藏量 collect_count）、阅读量（read_count，公开数据 / 企业版精准数据）；
关联信息：话题标签（tags，如 “两会热点”“民生政策”“科技创新”，助力热点分类）、核心关键词（keywords，平台算法标注的热点核心词）、关联内容 ID（related_item_ids，同事件关联的其他热榜内容 ID）、话题链接（topic_url，热点所属话题聚合页 URL，企业版可用）；
扩展信息：原创标识（is_original，true/false）、是否置顶（is_top，热榜置顶内容标记）、舆情风险提示（risk_tip，敏感热点关联提示，企业版舆情场景专属）、首发媒体（first_pub_source，多来源转载时的首发机构）。
调用频率：机构版 10 次 / 分钟，企业版 50-200 次 / 分钟（实时热榜建议降低调用频率，避免触发风控）；
数据缓存：实时热榜缓存 1-5 分钟，今日 / 7 日热榜缓存 30 分钟 - 1 小时，企业版支持refresh=1强制刷新（需申请权限）；
权限差异：
内容限制：部分敏感热点（如涉密、重大突发事件未公开信息）仅企业版完成专项备案后可见；
版权说明：热榜数据（标题、排名、热度值等）可用于自身合规业务场景（如舆情监测、资讯展示），禁止擅自篡改排名、热度值或商业化售卖，引用需标注来源 “新京报热榜”。
访问新京报开放平台，完成账号注册：
进入 “应用管理”，创建应用，填写应用名称、用途（需明确 “使用 item_search 接口获取新京报热榜数据”）；
申请 “热榜数据查询（item_search）” 接口权限，审核通过后，在应用详情页获取 appkey 和 secret（务必保密，避免硬编码到代码）；
下载平台提供的热榜类型字典、字段说明文档和版权使用指南（确认hot_type取值、字段含义、使用规范）。
接口采用 HTTPS 协议，支持所有主流开发语言：Python、Java、PHP、Go、Node.js 等，无框架限制，推荐使用 Python（数据处理、批量对接效率高，适配热榜实时性需求）。
热榜类型选择：根据业务场景确定hot_type（如舆情监测聚焦 “politics+society”，科技资讯平台聚焦 “tech”），企业版可使用二级分类提升精准度；
时间范围适配：实时热点追踪用 “realtime”，每日热点汇总用 “today”，长期趋势分析用 “7days/30days”；
字段筛选：仅保留业务必需字段（如热点展示需 “rank、title、hot_value、pub_time”，关联详情需 “item_id”），减少数据传输量；
异常场景预设：热榜无数据、频率超限、权限不足、网络波动等场景，需设计降级方案（如返回历史缓存热榜、提示 “热点加载中”）。
拼接除 sign 外的所有请求参数（必填 + 可选）；
按平台规则生成签名（sign），确保请求合法性；
发送 POST 请求（推荐，参数传输更安全，符合媒体平台数据规范）；
接收响应数据，解析 JSON 格式结果；
热榜数据标准化处理（排序验证、字段映射、关联准备）；
按需联动item_get接口获取内容详情；
异常处理（签名错误、频率超限、权限不足等）。
新京报热榜接口签名规则与item_get一致，签名错误是最常见的调用失败原因，生成步骤严格遵循以下规则：
按参数名ASCII 升序排序所有请求参数（不含sign字段）；
将排序后的参数拼接为 “key1=value1&key2=value2&...” 格式（中文 / 特殊字符需 URL 编码）；
在拼接字符串末尾追加 &secret=你的secret；
对拼接后的字符串进行MD5 加密（32 位大写），结果即为sign。
假设请求参数：
排序后参数：appkey、hot_type、page_no、page_size、time_range、timestamp；
拼接字符串；
pip install requests pandas apscheduler # requests：网络请求；pandas：数据整理；apscheduler：定时任务（实时热榜用）
import requests
import hashlib
import time
import json
import pandas as pd
from urllib.parse import urlencode
from typing import Dict, List, Optional
import logging
from apscheduler.schedulers.blocking import BlockingScheduler
# 配置日志（记录接口调用、错误信息，便于合规追溯）
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s",
handlers=[logging.FileHandler("bjnews_hot_search.log"), logging.StreamHandler()]
)
# 接口核心配置（替换为自己的密钥和接口地址）
APP_KEY = "你的appkey"
SECRET = "你的secret"
API_URL = "https://open.bjnews.com.cn/api/item_search/hotlist" # 新京报热榜接口正式地址
SAVE_PATH = "新京报热榜数据.xlsx" # 热榜数据保存路径
CACHE_KEY = "bjnews_hotlist_cache" # Redis缓存键（如需缓存可启用）
def generate_sign(params: Dict) -> str:
"""生成接口签名（严格按平台规则实现，核心函数）"""
# 1. 按参数名ASCII升序排序（排除sign字段）
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 2. 拼接参数字符串（urlencode自动处理中文、特殊字符）
param_str = urlencode(sorted_params, encoding="utf-8") + f"&secret={SECRET}"
# 3. MD5加密（32位大写）
md5 = hashlib.md5()
md5.update(param_str.encode("utf-8"))
return md5.hexdigest().upper()
def get_hotlist(
hot_type: str = "all",
time_range: str = "realtime",
sort_type: str = "hot",
page_no: int = 1,
page_size: int = 20,
fields: str = "rank,title,hot_value,hot_level,item_id,pub_time,tags,source,interact_data,detail_url"
) -> Dict:
"""
调用item_search接口获取新京报热榜数据
:param hot_type: 热榜类型（多类型用逗号分隔）
:param time_range: 时间范围
:param sort_type: 排序方式
:param page_no: 页码
:param page_size: 每页条数
:param fields: 需返回的字段
:return: 标准化后的热榜数据字典
"""
# 1. 构建基础参数（必填项）
params = {
"appkey": APP_KEY,
"hot_type": hot_type,
"time_range": time_range,
"sort_type": sort_type,
"page_no": page_no,
"page_size": page_size,
"fields": fields,
"timestamp": int(time.time() * 1000)
}
# 2. 生成签名
params["sign"] = generate_sign(params)
try:
# 3. 发送POST请求（HTTPS协议，超时10秒，符合媒体平台安全要求）
response = requests.post(
url=API_URL,
data=json.dumps(params),
headers={"Content-Type": "application/json"},
timeout=10,
verify=True
)
response.raise_for_status() # 抛出HTTP请求异常（如404、500）
result = response.json()
# 4. 处理响应
if result.get("code") == 200:
raw_data = result.get("data", {})
hotlist = raw_data.get("hot_list", [])
total = raw_data.get("total", 0) # 热榜总条数
page_total = raw_data.get("page_total", 1) # 总页码
# 标准化热榜数据（突出热榜核心字段，适配业务展示/分析）
standard_hotlist = []
for hot in hotlist:
# 解析互动数据
interact_data = hot.get("interact_data", {})
# 标准化时间格式
pub_time = hot.get("pub_time", 0)
pub_time_str = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(pub_time/1000)) if pub_time else ""
standard_hot = {
"请求时间": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()),
"热榜类型": hot_type,
"时间范围": time_range,
"排名": hot.get("rank", 0),
"热度值": hot.get("hot_value", 0),
"热度等级": hot.get("hot_level", ""),
"热榜标签": ",".join(hot.get("hot_tag", [])),
"标题": hot.get("title", ""),
"内容ID": hot.get("item_id", ""),
"来源": hot.get("source", "新京报"),
"发布时间": pub_time_str,
"话题标签": ",".join(hot.get("tags", [])),
"评论量": interact_data.get("comment_count", 0),
"转发量": interact_data.get("share_count", 0),
"点赞量": interact_data.get("like_count", 0),
"阅读量": hot.get("read_count", 0),
"详情页URL": hot.get("detail_url", ""),
"是否原创": "是" if hot.get("is_original", False) else "否",
"是否置顶": "是" if hot.get("is_top", False) else "否"
}
standard_hotlist.append(standard_hot)
return {
"success": True,
"data": standard_hotlist,
"total": total,
"page_no": page_no,
"page_total": page_total,
"error_msg": ""
}
else:
error_msg = result.get("msg", "接口调用失败")
error_code = result.get("code")
logging.error(f"接口返回错误：code={error_code}, msg={error_msg}")
return {
"success": False,
"data": [],
"total": 0,
"page_no": page_no,
"page_total": 0,
"error_code": error_code,
"error_msg": error_msg
}
except requests.exceptions.RequestException as e:
logging.error(f"网络异常：{str(e)}")
return {
"success": False,
"data": [],
"total": 0,
"page_no": page_no,
"page_total": 0,
"error_code": -2,
"error_msg": f"网络异常：{str(e)}"
}
except Exception as e:
logging.error(f"数据处理异常：{str(e)}")
return {
"success": False,
"data": [],
"total": 0,
"page_no": page_no,
"page_total": 0,
"error_code": -3,
"error_msg": f"处理异常：{str(e)}"
}
def batch_get_hotlist(hot_type: str = "all", time_range: str = "realtime") -> List[Dict]:
"""
批量获取热榜多页数据（自动遍历所有页码）
:param hot_type: 热榜类型
:param time_range: 时间范围
:return: 所有页码的热榜数据列表
"""
all_hotlist = []
page_no = 1
while True:
logging.info(f"正在获取热榜（类型：{hot_type}，时间范围：{time_range}）第{page_no}页数据")
result = get_hotlist(hot_type=hot_type, time_range=time_range, page_no=page_no)
if not result["success"]:
logging.error(f"第{page_no}页热榜获取失败：{result['error_msg']}")
break
page_hotlist = result["data"]
if not page_hotlist:
logging.info(f"第{page_no}页无热榜数据，批量获取结束")
break
all_hotlist.extend(page_hotlist)
logging.info(f"第{page_no}页热榜获取成功，新增{len(page_hotlist)}条数据")
# 达到总页码，停止遍历
if page_no >= result["page_total"]:
break
page_no += 1
# 控制调用频率（机构版10次/分钟，间隔6秒；企业版50次/分钟，间隔1秒）
time.sleep(6)
return all_hotlist
def save_hotlist(hotlist: List[Dict], save_path: str = SAVE_PATH):
"""将热榜数据保存为Excel文件（便于归档/分析）"""
if not hotlist:
logging.warning("无热榜数据可保存")
return
df = pd.DataFrame(hotlist)
# 筛选热榜常用字段，优化Excel可读性
columns = [
"请求时间", "热榜类型", "时间范围", "排名", "热度值", "热度等级", "热榜标签",
"标题", "内容ID", "来源", "发布时间", "话题标签", "评论量", "转发量", "点赞量",
"阅读量", "详情页URL", "是否原创", "是否置顶"
]
df = df[columns].drop_duplicates(subset=["内容ID", "请求时间"]) # 去重（避免重复保存同一内容同一时间的热榜数据）
# 增量保存（避免覆盖历史热榜数据）
try:
history_df = pd.read_excel(save_path, engine="openpyxl")
df = pd.concat([history_df, df], ignore_index=True)
except FileNotFoundError:
pass
df.to_excel(save_path, index=False, engine="openpyxl")
logging.info(f"热榜数据已归档至：{save_path}（累计{len(df)}条数据）")
def sync_hotlist定时任务():
"""定时同步热榜数据（实时热榜场景用，如每5分钟拉取一次）"""
logging.info("=== 开始执行热榜定时同步任务 ===")
# 同步全站实时热榜
realtime_hotlist = batch_get_hotlist(hot_type="all", time_range="realtime")
# 同步今日时政+社会热榜
today_politics_society = batch_get_hotlist(hot_type="politics,society", time_range="today")
# 合并数据并保存
all_data = realtime_hotlist + today_politics_society
save_hotlist(all_data)
logging.info("=== 热榜定时同步任务执行完成 ===")
# 调用示例（支持单页/批量/定时获取）
if __name__ == "__main__":
# 模式1：获取单页热榜数据（全站实时热榜第1页）
single_page_hotlist = get_hotlist(hot_type="all", time_range="realtime", page_no=1)
if single_page_hotlist["success"]:
print("="*80)
print(f"全站实时热榜第1页（共{len(single_page_hotlist['data'])}条数据）")
print("="*80)
for hot in single_page_hotlist["data"][:5]: # 打印前5条热榜
print(f"排名：{hot['排名']:2d} | 热度值：{hot['热度值']:6d} | 热度等级：{hot['热度等级']:2s}")
print(f"标题：{hot['标题']}")
print(f"来源：{hot['来源']} | 发布时间：{hot['发布时间']}")
print(f"互动：评论{hot['评论量']} | 转发{hot['转发量']} | 点赞{hot['点赞量']}")
print(f"详情URL：{hot['详情页URL']}")
print("-"*80)
else:
print(f"单页热榜获取失败：{single_page_hotlist['error_msg']}（错误码：{single_page_hotlist.get('error_code')}）")
# 模式2：批量获取多页热榜数据（今日财经热榜所有页码）
# batch_hotlist = batch_get_hotlist(hot_type="finance", time_range="today")
# save_hotlist(batch_hotlist)
# 模式3：启动定时任务（每5分钟同步一次热榜，实时场景用）
# scheduler = BlockingScheduler()
# scheduler.add_job(sync_hotlist定时任务, 'interval', minutes=5) # 每5分钟执行一次
# logging.info("热榜定时同步任务已启动，每5分钟执行一次...")
# try:
# scheduler.start()
# except (KeyboardInterrupt, SystemExit):
# logging.info("热榜定时同步任务已停止")手动拼接参数：在 Postman 中创建 POST 请求，填写appkey、hot_type、time_range、timestamp等必填项；
生成签名：按签名规则手动计算sign（可用在线 MD5 工具验证，输入拼接后的字符串）；
配置请求头：设置Content-Type: application/json，将参数以 JSON 格式传入请求体；
发送请求：点击发送，查看响应结果；
验证结果：
若返回 200 且数据完整：接口正常，可对接代码；
若返回 401（签名无效）：检查参数排序、secret 是否正确、时间戳是否过期；
若返回 403（权限不足）：确认认证类型（机构 / 企业）是否符合要求，是否申请了二级分类、精准热度值等高级权限；
若返回 404（接口不存在）：核对 API_URL 是否正确，确认item_search接口已申请开通；
若返回 429（频率超限）：降低调用频率；
若返回 400（参数错误）：核对hot_type、time_range、page_size等参数值是否合法（如hot_type是否在支持列表中）；
若返回 500（服务器异常）：记录日志，稍后重试；
若返回 601（敏感热榜无权限）：企业版需完成专项备案，机构版无法访问；
若返回 701（版权授权不足）：补充签署版权使用协议，明确热榜数据使用场景。
热榜缓存：用 Redis 缓存热榜数据（实时热榜缓存 5 分钟，今日 / 7 日热榜缓存 30 分钟），避免重复请求，提升响应速度；
缓存穿透防护：对无数据的热榜（如小众分类 + 实时范围），缓存空结果（有效期 10 分钟），避免频繁无效请求；
增量更新：定时拉取时仅保存新增热榜数据（按item_id+请求时间去重），减少存储压力。
定时拉取频率适配：实时热榜按平台缓存周期设置拉取频率（如平台缓存 5 分钟，定时任务每 5 分钟执行一次），避免无效刷新；
热点预警：基于hot_value阈值（如热度值≥10000）触发预警，快速捕获爆点热点；
关联详情预加载：对 TOP10 热榜内容，提前调用item_get接口获取详情并缓存，提升用户访问体验。
异常重试机制：
密钥与权限安全：
定期轮换secret（每 3 个月更新 1 次），在新京报开放平台操作；
生产环境将appkey和secret存储在环境变量或配置中心（如 Nacos），避免硬编码；
配置 IP 白名单（开发者平台设置），仅允许业务服务器调用接口，防止密钥泄露后被滥用。
日志与监控：
详细记录每次请求的参数、签名、响应结果、错误信息，以及热榜数据量、更新频率，便于问题追溯；
配置日志告警（如通过邮件 / 钉钉推送高频错误、频率超限、权限不足提示），实时监控接口状态；
监控热榜数据质量（如连续 3 次无数据、热度值异常、排名重复），及时触发告警。
敏感热点识别：利用tags（话题标签）和risk_tip（舆情风险提示）字段，筛选涉敏热点（如 “政策争议”“社会矛盾”），标记风险并告警；
热点追踪：按item_id关联历史热榜数据，分析热点从出现到消退的生命周期（热度值变化、排名变化）；
多维度统计：按hot_type（分类）、hot_level（热度等级）统计热点分布，生成舆情简报。
热榜展示优化：按rank（排名）降序展示，突出hot_level（热度等级）和hot_tag（热榜标签），提升视觉辨识度；
分类导航：基于hot_type构建热榜分类导航（如 “时政热榜”“科技热榜”），支持用户按需切换；
关联推荐：利用tags（话题标签）和related_item_ids（关联内容 ID），为热点内容推荐同话题其他热榜，提升用户停留时长。
热榜数据归档：按 “请求时间 + 热榜类型 + 时间范围” 分类存储热榜数据，建立热点数据库，支持按时间、分类、热度值检索；
趋势分析：提取hot_value和pub_time，绘制热点热度趋势曲线，分析不同领域热点的传播规律；
关键词挖掘：对tags和keywords字段进行词频统计，识别特定时期的公众关注焦点（如月度 / 季度热点关键词）。
密钥是否保密（未硬编码、未提交到代码仓库，用环境变量 / 配置中心存储）；
异常处理是否完整（覆盖 401/403/404/429/500/601/701 等所有常见错误码）；
频率控制是否到位（调用频率未超过平台配额，批量 / 定时获取有合理间隔）；
权限与版权是否合规（认证类型与字段 / 功能需求一致，已签署版权使用协议）；
数据处理是否规范（热榜数据去重、时间格式标准化、字段映射正确）；
日志是否完善（记录请求参数、响应结果、错误信息、热榜数据量，便于追溯）；
HTTPS 是否启用（生产环境必须用 HTTPS，防止参数泄露和篡改）；
缓存策略是否生效（热榜缓存、穿透防护已实现，提升响应速度）；
敏感热榜处理是否合规（已备案或避免抓取，数据使用符合保密要求）；
实时性是否达标（定时拉取频率适配平台缓存周期，热点更新及时）。
新京报 item_search 热榜接口对接的核心是 “签名合法 + 权限合规 + 场景适配 + 实时性优化”：
入门阶段：重点掌握签名生成规则和基础请求流程，用 Postman 快速验证，再通过 Python 代码实现单页 / 批量热榜获取；
进阶阶段：通过异步并发、缓存策略提升效率，通过敏感热点识别、趋势分析适配舆情监测、数据研究等场景需求；
避坑关键：重视签名生成（最高频错误）、权限与版权申请（合规核心）、频率控制（平台限制严格）、实时性适配（热榜核心特性），尤其是新京报热榜的时效性和权威性，需严格遵守数据使用规范。
若对接过程中遇到问题，可通过新京报开放平台的 “工单系统” 或技术支持邮箱咨询，需提供以下信息：
完整请求参数（含 sign，隐藏 secret）；
响应错误码和错误信息；
调用时间戳；
热榜类型和时间范围（便于平台定位问题）；
业务场景说明（如舆情监测 / 热点聚合，帮助平台精准排查）。
按照本攻略操作，即可快速实现从 “零基础” 到 “生产级稳定对接”，高效获取新京报权威热榜数据，支撑舆情监测、热点追踪、数据研究等核心业务场景
