十万个为什么 API 分页查询：page / allPages / allNum / maxResult 详解
十万个为什么 API分页查询pageallPages免费接口 # 十万个为什么 API 分页查询：page / allPages / allNum / maxResult 详解
> 接口：十万个为什么（apiCode=1706）· 接入点：列表(1706-1) · 免费 · 请求方式：POST/GET · 返回格式：JSON · 适用人群：已接入开发者 · 阅读时间：约 6 分钟
## 核心要点
- 列表接入点的 `page` 控制翻页（非必填，默认第 1 页）；返回用 `allPages` / `allNum` / `maxResult` 描述分页规模。
- 三者关系：`allNum` 是命中总数，`maxResult` 是每页上限，`allPages = ceil(allNum / maxResult)`（实际以接口返回的 `allPages` 为准）。
- 翻页前先读 `allPages`，避免越界请求空页。
## Why：为什么要关心分页
用"地球"一搜返回 `allNum=210`、`allPages=5`、`maxResult=50`（文档示例）。如果不分页，前端一次性塞 210 条标题会很笨重；用户也更愿意"翻几页挑感兴趣的"。掌握分页参数，才能做出现代感的浏览体验。
## What：分页字段速览
| 字段 | 位置 | 类型 | 说明 |
|------|------|------|------|
| `page` | 入参 | string | 当前页，非必填，默认 "1" |
| `currentPage` | 出参 | string | 接口确认的实际当前页 |
| `allPages` | 出参 | string | 总页数 |
| `allNum` | 出参 | string | 命中总数 |
| `maxResult` | 出参 | string | 每页最大条数（示例 50） |
## How：分页实现
**步骤 1 — 取首页并读总分页**
```python
import requests, math
APP_KEY = "YOUR_APPKEY"
def fetch_page(keyword, page="1"):
r = requests.post("https://route.showapi.com/1706-1",
data={"keyword": keyword, "page": page},
params={"appKey": APP_KEY},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10).json()
body = r["showapi_res_body"]
if body.get("ret_code") != "0":
raise RuntimeError(body.get("remark"))
return body
first = fetch_page("地球")
all_pages = int(first["allPages"]) # 5
all_num = int(first["allNum"]) # 210
max_result = int(first["maxResult"]) # 50
print(f"共 {all_num} 条，{all_pages} 页，每页 {max_result} 条")
```
**步骤 2 — 遍历所有页**
```python
for p in range(1, all_pages + 1):
page_body = fetch_page("地球", str(p))
for item in page_body["contentlist"]:
print(item["id"], item["title"])
```
**步骤 3 — 前端"加载更多"**
用 `currentPage < allPages` 判断是否还有下一页，按钮触发 `page + 1`。
## 返回示例与解析
```json
{
"showapi_res_body": {
"allPages": 5, "currentPage": 1, "allNum": 210, "maxResult": 50,
"contentlist": [ {"id": "5ba48fdbc1b458bb0892f6ff", "title": "地球名片"} ]
}
}
```
- `allPages=5` 表示最多翻到第 5 页；请求超过 5 页会得到空 `contentlist`（不要当成错误）。
- `maxResult=50` 是单页上限，前端分页器以此对齐。
## 进阶 / 边界
- **不要臆造总页数**：以接口返回的 `allPages` 为准，别用 `ceil(allNum/maxResult)` 硬算（两者通常一致，但接口值是权威）。
- **空页处理**：请求 `page` 超过 `allPages` 时 `contentlist` 可能为空，前端应静默处理而非报错。
- **档位成本**：每翻一页都是一次列表调用，计入免费档位，建议对首页/热门词做缓存（见[《免费档位下：用缓存策略节省调用次数》](https://www.showapi.com/guides/why100k-free-tier-cache-1706)）。
## FAQ
**Q1：page 不传默认第几页？**
默认第 1 页（示例值为 "1"）。
**Q2：allPages 和我自己算的不一样怎么办？**
以接口返回的 `allPages` 为准。
**Q3：超过 allPages 会报错吗？**
通常不会报错，而是返回空 `contentlist`，需前端兜底。
**Q4：maxResult 能自己改大吗？**
`maxResult` 是接口返回的上限，不是入参，不能自行调大。
**Q5：分页会耗很多免费额度吗？**
每页一次列表调用，会累计；高频翻页建议缓存。
## 相关能力 / 下一步阅读
- [十万个为什么 API 返回字段全解：ret_code / contentlist / content 一文读懂](https://www.showapi.com/guides/why100k-response-fields-1706)
- [十万个为什么 API 关键词检索技巧：keyword 命中规律与避坑](https://www.showapi.com/guides/why100k-keyword-strategy-1706)
- [十万个为什么 API 免费档位下：用缓存策略节省调用次数](https://www.showapi.com/guides/why100k-free-tier-cache-1706)
- **本系列共 11 篇**：查看[十万个为什么 API 指南总目录](https://www.showapi.com/guides/why100k-guides-1706)
