地区新闻接口返回字段全解：pagebean 与 contentlist 一文读懂

# 地区新闻接口返回字段全解：pagebean 与 contentlist 一文读懂 > 接口/接入点：地区新闻接口（apiCode 170）· 根据地区查询新闻（170-47）｜免费 · POST/GET · 返回 JSON · 适用人群：已接入或准备接入的开发者 · 阅读时间：约 6 分钟 ## 核心要点 - 所有业务数据都包在 `showapi_res_body` 内；新闻列表在 `pagebean.contentlist`。 - 分页四件套：`allNum`(总记录数)、`allPages`(总页数)、`currentPage`(当前页)、`maxResult`(每页 20 条)。 - 每条新闻含 `title`/`link`/`pubDate`/`source`/`desc`/`areaId`/`areaName`/`imageurls`，其中 `imageurls` 真实类型为数组。 ## Why：为什么要把字段吃透 字段错了，前端就乱了：`imageurls` 当成字符串拼接会报错、分页算错会重复或漏拉数据、`ret_code` 判断漏了会把失败当成功。本文把官方返回结构逐字段讲清，建议你把它当"字典"收藏，写代码时对照。 ## What：接口速览 | 项 | 值 | |------|------| | 接口地址 | `https://route.showapi.com/170-47?appKey={your_appKey}` | | 返回格式 | JSON（系统级封装 + 业务级 `showapi_res_body`） | | 分页单位 | 每页 `maxResult` = 20 条 | | 业务成功判定 | `showapi_res_body.ret_code == 0` 且系统级 `showapi_res_code == 0` | ## How：字段拆解 ### 系统级字段（每个 ShowAPI 接口都有） | 字段 | 类型 | 说明 | |------|------|------| | `showapi_res_code` | Number | 系统级状态码，0 成功 | | `showapi_res_error` | String | 系统级错误信息，成功时为空 | | `showapi_res_id` | String | 本次请求唯一 ID，便于排查 | | `showapi_res_body` | Object | 业务数据封装，下文所有字段都在这里 | ### 业务级字段（`showapi_res_body` 内） | 字段 | 类型 | 说明 | |------|------|------| | `ret_code` | String | 业务状态码，`0` 为成功，其他为失败（文档未枚举具体值） | | `pagebean` | Object | 分页容器，见下表 | ### `pagebean` 分页结构 | 字段 | 类型 | 说明 | |------|------|------| | `allNum` | Number | 所有记录数 | | `allPages` | Number | 所有页数 | | `currentPage` | Number | 当前页 | | `maxResult` | Number | 每页最大记录数（固定 20） | | `contentlist` | Array | 新闻条目数组 | ### `contentlist` 单条结构 | 字段 | 类型 | 说明 | |------|------|------| | `title` | String | 新闻标题 | | `link` | String | 新闻详情链接 | | `pubDate` | String | 发布时间，格式 `YYYY-MM-DD HH:mm:ss` | | `source` | String | 来源网站（如「新华网」「新浪黑龙江」） | | `desc` | String | 新闻简要描述，可能为空串 | | `areaId` | String | 地区 ID（稳定，建议缓存后用于精确查询） | | `areaName` | String | 地区名称 | | `imageurls` | **Array** | 图片列表（注意：文档参数表标为 String，真实返回是数组，可能为空 `[]`） | ## 返回示例与解析 ```json { "showapi_res_code": 0, "showapi_res_error": "", "showapi_res_id": "ce135f6739294c63be0c021b76b6fbff", "showapi_res_body": { "pagebean": { "allNum": 1640, "allPages": 82, "currentPage": 1, "maxResult": 20, "contentlist": [ { "title": "望奎要求全县中小学做好汛期安全", "link": "http://hlj.sina.com.cn/sh/m/2015-06-18/084856487.html", "pubDate": "2015-06-18 05:38:21", "source": "新浪黑龙江", "desc": "", "areaId": "55818af8085b7bc0c73836d5", "areaName": "黑龙江", "imageurls": [] } ] }, "ret_code": 0 } } ``` **解析要点**： - 判成功：`showapi_res_code == 0` 且 `ret_code == 0`。 - 取列表：`body["pagebean"]["contentlist"]`。 - 图片：`item["imageurls"]` 当作数组处理（即便为空也安全遍历）。 ## 进阶 / 边界 - `desc` 可能为空串 `""`，前端展示需做空值兜底（如显示「暂无摘要」）。 - `imageurls` 多数情况下为空数组，不要假设一定有图，展示前先判 `length`。 - `areaId` 是稳定标识，适合缓存映射后用于「按 ID 精确查询」（见 areaId/areaName 篇）。 ## FAQ **Q：ret_code 和 showapi_res_code 有什么区别？** A：前者是业务级（本接口内是否查到/成功），后者是系统级（请求本身是否通畅）。两者都应判 0 才算成功。 **Q：imageurls 文档写的是 String，我按字符串处理报错怎么办？** A：以真实返回为准——它是数组。本文已标注该文档不一致，按数组遍历即可。 **Q：allPages 很大（如 82 页）需要全拉吗？** A：通常不需要。按业务取前几页足够；若需全量，配合分页与缓存策略篇控制频率。 ## 相关能力与下一步阅读 - [地区新闻接口：按地区/标题查新闻的参数使用指南](https://www.showapi.com/guides/region-news-query-by-area-170) - [地区新闻接口 imageurls 字段处理：空数组与展示避坑](https://www.showapi.com/guides/region-news-imageurls-170) - **本系列共 12 篇**：查看[地区新闻接口（apiCode 170）官方指南总目录](https://www.showapi.com/guides/region-news-guides-170)