免费地震信息：date 与 area 参数使用指南（含实测筛选坑）
# 免费地震信息：date 与 area 参数使用指南（含实测筛选坑）
- **接口/接入点**：免费地震信息 · 2274-1
- **是否免费**：是（注册即免费额度）
- **请求方式**：POST / GET
- **返回格式**：JSON
- **适用人群**：初次接入的开发者
- **阅读时间**：约 6 分钟
## 核心要点
- 接口只有两个可选参数：`date`（yyyyMMdd，北京时间）和 `area`（省名）。两个都是选填。
- `date` 是控制返回范围的主力参数；不传则返回「最近几条」全球记录。
- **实测 `area` 未按省名过滤**（area=云南仍返回美国地震），不要依赖它做地区筛选，应在客户端按 `location` 自行过滤。
## Why：参数用错，数据就乱
很多同学想「只查云南的地震」，于是传 `area=云南`，结果拿到一堆美国记录，以为接口坏了。本篇用实测结果讲清两个参数的真实行为，帮你少走弯路。
## What：接口速览
| 项 | 值 |
|----|----|
| 接口地址 | `https://route.showapi.com/2274-1?appKey={your_appKey}` |
| 选填参数 | `date`（String，yyyyMMdd）、`area`（String，省名） |
| 计费 | 免费（档位限制见 [免费 API 说明](https://www.showapi.com/free-api)） |
## How：参数用法
### date —— 按日期查询（推荐主力）
格式 `yyyyMMdd`，按北京时间理解。例如查 2025-01-20：
```python
import requests
APP_KEY = "YOUR_APPKEY"
r = requests.post(
"https://route.showapi.com/2274-1",
params={"appKey": APP_KEY},
data={"date": "20250120"}, # 北京时间 yyyyMMdd
timeout=10,
)
body = r.json()["showapi_res_body"]
print("ret_code:", body["ret_code"], "count:", body["count"])
```
实测：传 `date=20250120` 可返回当天全球上百条记录（count 达 167）。**不传 date** 时返回「最近几条」全球记录（实测约 5 条，均为最新时刻）。
### area —— 文档说「省名」，实测不生效（重点）
文档描述：`area` = 「要查询的地震发生的地区，可填入省名，例如：云南」。我们做了两次实测：
```bash
# 实测 1：area=台湾 + date=20250120 → 返回 167 条，含美国/四川/西藏/新疆，无台湾
curl -X POST "https://route.showapi.com/2274-1?appKey=YOUR_APPKEY" \
--data-urlencode "area=台湾" --data-urlencode "date=20250120"
# 实测 2：area=云南（无 date）→ 返回 5 条，全部是美国（加州/夏威夷/阿拉斯加），无云南
curl -X POST "https://route.showapi.com/2274-1?appKey=YOUR_APPKEY" \
--data-urlencode "area=云南"
```
结论：**当前实测 `area` 参数未按省名过滤**，返回的仍是全球/最新数据。因此本指南将其定性为「文档标注但实测可能未生效」的参数，写入文章时必须作为避坑点，不能宣称「支持按省份精确筛选」。
## 返回示例与解析
```json
{
"showapi_res_body": {
"ret_code": 0,
"count": 5,
"earthquakes": [
{"location": "科索章克申东北10 公里处", "mag": 1.37, "from": "usgs"},
{"location": "夏威夷帕哈拉东南19 公里处", "mag": 2.12, "from": "usgs"}
]
}
}
```
注意：上面 `area=云南` 的返回里 `location` 全是美国地名——这就是 area 未生效的直接证据。
## 进阶 / 边界
- **正确的「按地区筛选」做法**：用 `date` 框定时间范围 → 取回 `earthquakes[]` → 在客户端按 `location` 字符串包含「云南/四川/台湾」等关键字过滤。这样可控、可解释。
- **date 是必用参数**：要做历史统计，务必传 date；要展示「最近地震」则不传 date，但要注意返回条数有限。
- **参数个数**：仅这两个，没有分页、没有经纬度范围、没有震级下限等高级筛选参数；如需「某震级以上」，同样需在客户端按 `mag` 过滤。
## FAQ
**Q1：我不传 date 会返回什么？**
实测返回「最近几条」全球地震（约 5 条，为当前最新时刻记录）。适合做「近期地震」展示；要查特定日期务必传 `date`。
**Q2：area 传了省名为什么没过滤？**
实测 `area=台湾`、`area=云南` 都未按省名过滤，返回的是全球/最新数据。当前建议：**不要依赖 area 做地区筛选**，改用「date + 客户端按 location 过滤」。该行为以接口实际返回为准，如后续官方修复会另行说明。
**Q3：date 格式写错会怎样？**
date 应为 `yyyyMMdd` 八位纯数字（如 20250120）。格式不对可能导致 ret_code=-1 或返回空，建议调用前用正则/日期库校验。
**Q4：能不能按震级或经纬度范围筛选？**
接口未提供此类参数。只能先取回数据，再在客户端按 `mag`、`lat`、`lng` 自行过滤。
## 相关能力 / 下一步阅读
- [免费地震信息：5 分钟从注册到调通第一条地震记录](https://www.showapi.com/guides/earthquake-info-quickstart-2274)
- [免费地震信息：返回字段全解（ret_code / mag / from 一文读懂）](https://www.showapi.com/guides/earthquake-info-response-fields-2274)
- [免费地震信息：用经纬度(lat/lng)在地图上标点绘制震中分布](https://www.showapi.com/guides/earthquake-info-map-visualization-2274)
- **本系列共 14 篇**：查看[免费地震信息指南总目录](https://www.showapi.com/guides/earthquake-info-guides-2274)
