邮编区域互查分页与 maxResult/allNum 实战：大结果集怎么翻页
邮编查询邮编区域互查ShowAPI免费接口API教程 # 邮编区域互查分页与 maxResult/allNum 实战：大结果集怎么翻页
> 邮编区域互查（apiCode=1917）· 免费接口 · POST/GET · JSON · 初级~中级开发者 · 约 8 分钟
## 核心要点
- 分页参数 `page`（页码），每页最大 `maxResult` 条（实测返回 20）。
- 返回 `allNum`（总条数）、`allPages`（总页数）、`currentPage`（当前页）帮你控制翻页。
- 接入点3 文档标注「分页最大 50 页」，超范围按接口约束处理。
- 一个邮编/地区可能命中多条（如多个街道），翻页取全是常见需求。
## Why：结果不止一页时要翻完
做地址全量校对、批量导出时，一个查询可能返回几十条。不翻页就会漏数据。本文讲清分页字段含义与翻页循环写法。
## What：接口速览
| 项 | 说明 |
|----|------|
| 分页参数 | `page`（页码，非必填，默认 1） |
| 每页上限 | `maxResult`（实测 20） |
| 总量字段 | `allNum`（总条数）、`allPages`（总页数） |
| 接入点3 限制 | 文档标注分页最大 50 页 |
## How：翻页循环（Python）
```python
import requests, time
def fetch_all(app_key, code):
all_items, page = [], 1
while True:
r = requests.post("https://route.showapi.com/1917-1",
params={"appKey": app_key, "code": code, "page": page}, timeout=10)
b = r.json().get("showapi_res_body", {})
if b.get("ret_code") != 0:
break
items = b.get("contentlist", [])
if not items:
break
all_items.extend(items)
if page >= b.get("allPages", 1):
break
page += 1
time.sleep(0.2) # 免费接口频次有限，适当限速
return all_items
print(fetch_all("YOUR_APPKEY", "362504"))
```
### cURL（指定页码）
```bash
curl -X POST "https://route.showapi.com/1917-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
--data-urlencode "code=362504" --data-urlencode "page=2"
```
### Node.js（fetch）
```javascript
let page = 1, all = [];
while (true) {
const res = await fetch(`https://route.showapi.com/1917-1?appKey=YOUR_APPKEY`,
{ method: "POST", body: new URLSearchParams({ code: "362504", page: String(page) }),
signal: AbortSignal.timeout(10000) });
const b = (await res.json()).showapi_res_body;
if (b.ret_code !== 0 || !b.contentlist?.length) break;
all.push(...b.contentlist);
if (page >= b.allPages) break;
page++;
}
```
## 返回示例与解析
```json
{ "showapi_res_body": { "ret_code": 0, "contentlist": [ ... ], "maxResult": 20, "allNum": 10, "allPages": 1, "currentPage": 1 } }
```
| 字段 | 含义 |
|------|------|
| `page` | 请求页码 |
| `maxResult` | 每页最大条数（20） |
| `allNum` | 满足条件的总条数 |
| `allPages` | 总页数 |
| `currentPage` | 当前页 |
## 进阶/边界
- **以 `allPages` 为终止条件**：循环到 `page >= allPages` 停止，避免多翻。
- **限速**：免费接口有档位限制，翻页间加少量 sleep，失败时做指数退避。
- **接入点3 上限**：分页最大 50 页，超过按接口约束处理。
- **空页即停**：`contentlist` 为空时直接结束。
## FAQ
**Q1：每页最多多少条？**
实测 `maxResult` 为 20。
**Q2：怎么知道有多少页？**
看返回 `allPages`；总量看 `allNum`。
**Q3：翻页会触发限流吗？**
免费接口有档位限制，建议加限速与退避。
**Q4：接入点3 分页有上限吗？**
文档标注最大 50 页。
**Q5：`allNum` 很大但列表为空？**
见《接入点3 实战》的免费档位实测差异说明。
## 相关能力 / 下一步阅读
- [邮编区域互查·查询详细地区邮编（接入点3）实战](https://www.showapi.com/guides/postcode-detail-query-1917)
- [免费接口如何设计缓存策略](https://www.showapi.com/guides/postcode-cache-1917)
- [邮编区域互查错误码排查](https://www.showapi.com/guides/postcode-error-codes-1917)
- **本系列共 12 篇**：查看[邮编区域互查指南总目录](https://www.showapi.com/guides/postcode-guides-1917)
