免费地震信息：返回字段全解（ret_code / mag / from 一文读懂）
# 免费地震信息：返回字段全解（ret_code / mag / from 一文读懂）
- **接口/接入点**：免费地震信息 · 2274-1
- **是否免费**：是（注册即免费额度）
- **请求方式**：POST / GET
- **返回格式**：JSON
- **适用人群**：初级到中级开发者、数据分析师
- **阅读时间**：约 7 分钟
## 核心要点
- 返回分两层：系统信封 `showapi_res_*` 与业务体 `showapi_res_body`，业务数据全在 `showapi_res_body` 内。
- 业务码 `ret_code` 只有 0（找到）和 -1（没找到/出错）两种；`count` 为记录条数。
- `earthquakes[]` 每条含 10 个字段，重点记住 `mag`(震级)、`lat`/`lng`(经纬度)、`dep`(深度)、`from`(来源)。
## Why：读懂字段才能正确用数据
拿到返回后最常见的问题：「ret_code 和 showapi_res_code 到底看哪个？」「mag 是震级还是烈度？」「timeLocal 到底是哪的当地时间？」把字段口径搞错，后续展示、统计、地图标点都会出错。本篇把每一层、每个字段讲清楚。
## What：接口速览
| 项 | 值 |
|----|----|
| 接口地址 | `https://route.showapi.com/2274-1?appKey={your_appKey}` |
| 返回格式 | JSON（业务数据在 `showapi_res_body`） |
| 计费 | 免费（档位限制见 [免费 API 说明](https://www.showapi.com/free-api)） |
| 集成能力 | MCP、OpenAPI 3.0 |
## How：字段拆解
### 第一层：系统信封（每次请求都有）
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | Number | 系统状态码，0 表示请求成功（与业务是否找到无关） |
| `showapi_res_error` | String | 系统级错误信息，成功时为空 |
| `showapi_res_id` | String | 本次请求唯一标识 |
| `showapi_fee_num` | Number | 计费次数；实测取到数据时=1、无数据时=0（免费额度内） |
### 第二层：业务体 `showapi_res_body`
| 字段 | 类型 | 说明 |
|------|------|------|
| `ret_code` | Number | 业务码：**0=找到，-1=没有找到或出错** |
| `count` | Number | 找到的记录条数 |
| `remark` | String | 错误信息（ret_code=-1 时给出原因） |
| `earthquakes` | Object[] | 记录集合，每条结构见下表 |
### 第三层：每条地震 `earthquakes[]`
| 字段 | 类型 | 说明 | 备注 |
|------|------|------|------|
| `location` | String | 震源大体位置 | 如「四川内江市市中区」「加利福尼亚间歇泉西北7 公里处」 |
| `mag` | Number | 震级（magnitude） | 文档标为「烈度」，实测取值为小数，实为**震级**；详见 [震级 vs 烈度](https://www.showapi.com/guides/earthquake-info-mag-vs-intensity-2274) |
| `lat` | Number | 震源纬度（十进制） | 符合 WGS84 经纬度 |
| `lng` | Number | 震源经度（十进制） | 同上 |
| `dep` | Number | 震源深度（km） | 部分记录为 0 或小数 |
| `from` | String | 数据来源 | 实测出现 `usgs`（美国地质调查局）、`ceic`（中国地震台网） |
| `timeLocal` | String | 时间字符串 | 实测为**北京时间(UTC+8)**，非震中当地时 |
| `timestampLocal` | Number | 当地时间时间戳(ms) | 与 timeLocal 同口径，即北京时间 |
| `timeUTC` | String | UTC 时间字符串 | — |
| `timestampUTC` | Number | UTC 时间戳(ms) | — |
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"ret_code": 0,
"count": 2,
"remark": "",
"earthquakes": [
{
"location": "四川内江市市中区",
"mag": 4.4,
"lat": 29.57,
"lng": 104.88,
"dep": 10.0,
"from": "ceic",
"timeLocal": "2025-01-20 21:59:54",
"timestampLocal": 1737381594000,
"timeUTC": "2025-01-20 13:59:54",
"timestampUTC": 1737352794000
},
{
"location": "加利福尼亚间歇泉西北7 公里处",
"mag": 1.02,
"lng": -122.82,
"lat": 38.82,
"dep": 2.99,
"from": "usgs",
"timeLocal": "2025-01-20 15:23:01",
"timestampLocal": 1737357781910,
"timeUTC": "2025-01-20 15:23:01",
"timestampUTC": 1737357781910
}
]
}
}
```
观察：中国记录（ceic）`timeLocal` 比 `timeUTC` 早 8 小时（北京时间）；美国记录（usgs）两者相等。因此展示给用户时，**不要**把 `timeLocal` 当成「震中当地时」。
## 进阶 / 边界
- **两个 code 怎么看**：先看 `showapi_res_code == 0` 确认请求成功，再看 `ret_code` 判断是否有数据；`ret_code == -1` 时直接读 `remark`。
- **mag 是震级不是烈度**：文档写「烈度」是口径偏差，写代码/展示请用「震级(M?)」表述，避免误导。
- **from 不是固定值**：除文档示例 `usgs` 外，实测还有 `ceic`；不要硬编码只认 usgs。
## FAQ
**Q1：showapi_res_code 和 ret_code 有什么区别？**
`showapi_res_code` 是系统层状态（0=请求成功到达并处理），`ret_code` 是业务层状态（0=找到数据，-1=没找到/出错）。必须两层都正常才算拿到数据。
**Q2：mag 字段单位是里氏还是矩震级？**
接口只返回数值，不区分震级标度（里氏/矩震级）。它是一个无量纲标量，展示时直接写「震级 X.X」即可，不要擅自标注具体标度。
**Q3：为什么有的 dep（深度）是 0？**
部分浅源地震或数据源未给出精确深度时会为 0 或接近 0 的小数值，属正常现象，展示时建议做容错（如「浅源/未知」）。
**Q4：from 字段还可能有哪些值？**
文档示例仅 `usgs`，实测出现 `usgs` 与 `ceic`。我们未穷举全部枚举，新增来源以接口实际返回为准，建议代码用 `switch`/字典做可扩展映射。
## 相关能力 / 下一步阅读
- [免费地震信息：date 与 area 参数使用指南（含实测筛选坑）](https://www.showapi.com/guides/earthquake-info-params-guide-2274)
- [免费地震信息：震级(mag)与烈度到底有什么区别？字段口径详解](https://www.showapi.com/guides/earthquake-info-mag-vs-intensity-2274)
- [免费地震信息：数据来源 usgs / ceic 有什么区别？该怎么用](https://www.showapi.com/guides/earthquake-info-data-sources-2274)
- **本系列共 14 篇**：查看[免费地震信息指南总目录](https://www.showapi.com/guides/earthquake-info-guides-2274)
