免费地震信息：timeLocal / timestampLocal 时区口径与跨时区处理
# 免费地震信息：timeLocal / timestampLocal 时区口径与跨时区处理
- **接口/接入点**：免费地震信息 · 2274-1
- **是否免费**：是（注册即免费额度）
- **请求方式**：POST / GET
- **返回格式**：JSON
- **适用人群**：开发者、数据分析师、跨境/跨时区应用
- **阅读时间**：约 7 分钟
## 核心要点
- 每条地震同时返回 `timeLocal`/`timestampLocal`（当地）与 `timeUTC`/`timestampUTC`（UTC）。
- 实测：`timeLocal` 实为**北京时间(UTC+8)**，并非震中当地时——美国记录里 `timeLocal` 与 `timeUTC` 相等（都按 UTC 显示）。
- 跨时区展示时，建议统一用 `timeUTC` 做基准，再按用户所在时区格式化，避免误导。
## Why：时区搞错，时间就差 8 小时
如果你的 App 面向全球用户，贸然把 `timeLocal` 当成「震中当地时」展示，美国用户会看到一条「当地时间等于 UTC」的怪数据。本文用实测证据讲清 `timeLocal` 的真实口径，并给出跨时区处理方案。
## What：接口速览
| 项 | 值 |
|----|----|
| 接口地址 | `https://route.showapi.com/2274-1?appKey={your_appKey}` |
| 相关字段 | `timeLocal`/`timestampLocal`、`timeUTC`/`timestampUTC` |
| 计费 | 免费（档位限制见 [免费 API 说明](https://www.showapi.com/free-api)） |
## How：实测证据
取 2025-01-20 的中美两条记录对比：
```json
{ "showapi_res_body": { "earthquakes": [
{ "location": "四川内江市市中区", "from": "ceic",
"timeLocal": "2025-01-20 21:59:54", "timestampLocal": 1737381594000,
"timeUTC": "2025-01-20 13:59:54", "timestampUTC": 1737352794000 },
{ "location": "加利福尼亚间歇泉西北7 公里处", "from": "usgs",
"timeLocal": "2025-01-20 15:23:01", "timestampLocal": 1737357781910,
"timeUTC": "2025-01-20 15:23:01", "timestampUTC": 1737357781910 }
] } }
```
观察：
- **中国记录（ceic）**：`timeLocal` 比 `timeUTC` 早 8 小时 → `timeLocal` = 北京时间(UTC+8)。
- **美国记录（usgs）**：`timeLocal` == `timeUTC` → 即把 UTC 直接当作「当地」，并非加州当地时（加州应为 UTC-8）。
结论：`timeLocal` 是**北京时间(UTC+8)**，是接口提供方的本地时，不是震中当地时。
### 跨时区展示建议（JavaScript）
```javascript
// 用 UTC 基准，按用户时区格式化（不依赖 timeLocal）
const ts = eq.timestampUTC; // 毫秒
const fmt = new Intl.DateTimeFormat("zh-CN", {
timeZone: "Asia/Shanghai", // 改成用户时区，如 America/Los_Angeles
dateStyle: "medium", timeStyle: "medium",
});
console.log(fmt.format(new Date(ts)));
```
## 返回示例与解析
| 字段 | 含义 | 实测口径 |
|------|------|---------|
| `timeUTC` / `timestampUTC` | UTC 时间 | 真实 UTC，跨时区基准 |
| `timeLocal` / `timestampLocal` | 「当地」时间 | **北京时间(UTC+8)**，非震中当地时 |
## 进阶 / 边界
- **永远以 `timeUTC` 为基准**：存库、计算、跨时区展示都用语 UTC，展示时再格式化到目标时区，最稳妥。
- **不要相信 `timeLocal` 是震中当地时**：美国记录会暴露它其实是 UTC，误导性强。
- **timestamp 单位**：`timestampLocal`/`timestampUTC` 均为**毫秒**级（13 位），转 `Date` 时勿当秒用。
## FAQ
**Q1：timeLocal 到底是哪个时区？**
实测为北京时间(UTC+8)。美国记录里 timeLocal 与 timeUTC 相等，说明它并非震中当地时，而是接口方的本地时（北京）。
**Q2：做全球应用该用哪个字段？**
统一用 `timeUTC`/`timestampUTC`（真实 UTC）。展示时按用户所在时区格式化，避免 8 小时偏差。
**Q3：timestamp 是秒还是毫秒？**
接口返回的是毫秒（13 位）。前端 `new Date(毫秒)` 直接用；若用秒级 API 需 ×1000。
**Q4：为什么美国地震的当地时间和 UTC 一样？**
因为接口把 UTC 直接填进了 `timeLocal`，并未换算成加州当地时(UTC-8)。这正是 timeLocal 实为「北京时间口径」的反证之一。
## 相关能力 / 下一步阅读
- [免费地震信息：返回字段全解（ret_code / mag / from 一文读懂）](https://www.showapi.com/guides/earthquake-info-response-fields-2274)
- [免费地震信息：数据来源 usgs / ceic 有什么区别？该怎么用](https://www.showapi.com/guides/earthquake-info-data-sources-2274)
- [免费地震信息：震级(mag)与烈度到底有什么区别？字段口径详解](https://www.showapi.com/guides/earthquake-info-mag-vs-intensity-2274)
- **本系列共 14 篇**：查看[免费地震信息指南总目录](https://www.showapi.com/guides/earthquake-info-guides-2274)
