地区新闻接口：5 分钟接入，从注册到第一条地区新闻
# 地区新闻接口：5 分钟接入，从注册到第一条地区新闻
> 接口/接入点：地区新闻接口 · 根据地区查询新闻（170-47）｜免费 · POST/GET · 返回 JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 5 分钟
## 核心要点
- 注册后在「我的 AppKey」拿到密钥，拼到请求 URL 的 `appKey` 参数即可调用，无需复杂鉴权。
- 用「根据地区查询新闻」（接入点 47）传入 `areaName=江西` 就能拉到该地区最新新闻列表。
- 返回数据套在 `showapi_res_body.pagebean.contentlist` 里，逐条取 `title`/`source`/`pubDate`/`link` 即可渲染。
## Why：这跟我有什么关系
如果你在做地方门户、舆情监测、本地生活 App、公众号自动推送，最基础的需求就是「按时拿到某地区的新闻」。地区新闻接口把全国各省/直辖市/特别行政区的资讯聚合好了，免费、无需自己爬新闻源。5 分钟跑通第一次调用，后面只是把结果接到你的页面或库里。
## What：前置条件与接口速览
| 项 | 值 |
|------|------|
| 接口编码 | 170 |
| 本次接入点 | 根据地区查询新闻（170-47） |
| 接口地址 | `https://route.showapi.com/170-47?appKey={your_appKey}` |
| 请求方式 | POST / GET |
| 鉴权 | URL 参数 `appKey`（在 https://www.showapi.com/console#/myApp 获取） |
| 计费 | 免费（有使用档位限制，见 https://www.showapi.com/free-api） |
| 返回格式 | JSON |
| 本篇必填参数 | 无（所有业务参数均为可选） |
## How：第一步调用
### 步骤 1：获取 AppKey
登录 https://www.showapi.com → 控制台 → 我的 AppKey，复制你的密钥（形如一串字母数字）。下文用 `YOUR_APPKEY` 占位，替换即可。
### 步骤 2：发起第一次调用（以江西为例）
**Python（requests）**
```python
import requests
resp = requests.post(
"https://route.showapi.com/170-47",
params={"appKey": "YOUR_APPKEY"},
data={"areaName": "江西", "page": 1},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10,
)
data = resp.json()
if data.get("showapi_res_code") != 0:
raise RuntimeError(data.get("showapi_res_error"))
body = data["showapi_res_body"]
print("总记录数:", body["pagebean"]["allNum"], " 总页数:", body["pagebean"]["allPages"])
for item in body["pagebean"]["contentlist"]:
print(item["title"], "|", item["source"], "|", item["pubDate"])
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/170-47?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
--data-urlencode "areaName=江西" \
--data-urlencode "page=1"
```
**Node.js（fetch）**
```js
const resp = await fetch("https://route.showapi.com/170-47?appKey=YOUR_APPKEY", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ areaName: "江西", page: 1 }),
});
const data = await resp.json();
if (data.showapi_res_code !== 0) throw new Error(data.showapi_res_error);
const list = data.showapi_res_body.pagebean.contentlist;
for (const it of list) console.log(it.title, "|", it.source, "|", it.pubDate);
```
### 步骤 3：在浏览器里渲染
把 `contentlist` 渲染成列表即可：标题（可点 `link` 跳转原文）、来源 `source`、时间 `pubDate`。下一节给出一段最小 HTML+JS Demo。
```html
<!doctype html><html><head><meta charset="utf-8"><title>地区新闻 Demo</title></head>
<body><ul id="list"></ul>
<script>
fetch("https://route.showapi.com/170-47?appKey=YOUR_APPKEY", {
method:"POST", headers:{"content-type":"application/x-www-form-urlencoded"},
body:new URLSearchParams({areaName:"江西", page:1})
}).then(r=>r.json()).then(d=>{
const ul=document.getElementById("list");
d.showapi_res_body.pagebean.contentlist.forEach(it=>{
const li=document.createElement("li");
li.innerHTML=`<a href="${it.link}" target="_blank">${it.title}</a> · ${it.source} · ${it.pubDate}`;
ul.appendChild(li);
});
});
</script></body></html>
```
## 返回示例与解析
接口统一用系统级字段包裹，业务数据在 `showapi_res_body` 内：
```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://...", "pubDate": "2015-06-18 05:38:21", "source": "新浪黑龙江", "desc": "", "areaId": "55818af8085b7bc0c73836d5", "areaName": "黑龙江", "imageurls": [] }
]
},
"ret_code": 0
}
}
```
- `showapi_res_code`：系统级状态码，0 表示请求成功。
- `showapi_res_body.ret_code`：业务级状态码，0 为成功，其他为失败。
- `pagebean.contentlist`：新闻条目数组，每页最多 `maxResult`（20）条。
## 进阶 / 边界
- **不传地区参数**：`areaName`/`areaId` 都不传时返回全国混合新闻，适合做「总览」。
- **更新频率**：新闻最快每 10 分钟更新，做定时拉取时注意间隔，别高频打接口（参见免费档位与缓存篇）。
- **ret_code 非 0**：表示本次查询失败，按"其他失败"处理并参考 FAQ 篇排查，文档未枚举具体错误码。
## FAQ
**Q：接口真的免费吗？会有隐藏收费吗？**
A：文档标注为免费服务，注册后默认可调用，但「为防止滥用设有使用档次限制」，具体档位以 https://www.showapi.com/free-api 为准，本文不编造数字。
**Q：第一次调用返回空 contentlist 是失败吗？**
A：不一定。先看 `showapi_res_code` 与 `ret_code` 是否都为 0；为 0 但列表为空，说明该地区/条件当前没有命中数据，不算失败。
**Q：中文地区名需要 URL 编码吗？**
A：用 `requests`/`fetch(URLSearchParams)`/curl `--data-urlencode` 时无需手动编码，库会处理；手写裸 URL 才需要编码。
## 相关能力与下一步阅读
- [地区新闻接口返回字段全解：pagebean 与 contentlist 一文读懂](https://www.showapi.com/guides/region-news-response-fields-170)
- [地区新闻接口：按地区/标题查新闻的参数使用指南](https://www.showapi.com/guides/region-news-query-by-area-170)
- **本系列共 12 篇**：查看[地区新闻接口（apiCode 170）官方指南总目录](https://www.showapi.com/guides/region-news-guides-170)
