一、适用场景与业务价值全球地震速报API为开发者提供了结构化的地震事件数据适用于以下场景地震速报播报集成到新闻系统或社交媒体机器人自动发布地震消息。防灾监控大屏实时显示近期地震分布、震级变化辅助应急响应。科研数据采集批量获取历史地震事件用于地震学分析或机器学习预测。个人开发工具如天气应用、旅行安全提醒等嵌入地震信息。通过该API开发者无需自行爬取多源数据即可获得标准化、低延迟的地震数据大幅降低开发维护复杂度。二、接口能力边界2.1 数据来源与更新频率汇聚全球主要地震监测机构如USGS、EMSC等的数据每分钟更新一次网关缓存60秒。因此API返回的数据最大延迟约1分钟满足大部分实时监控需求。2.2 查询维度时间范围period参数支持hour1小时、day1天、week7天、month30天。震级档位level参数支持all全部、significant显著地震、4.5M4.5、2.5M2.5、1.0M1.0。额外过滤min_magnitude可设置最小震级数值0为不过滤进一步缩窄范围。排序与条数order支持time最新在前或magnitude震级降序limit控制返回条数1-500。2.3 返回数据单元每个地震事件包含震级、深度、经纬度、发生时间、烈度、海啸提示、警报级别、地点描述等结构化信息。地名为国际标准英文描述覆盖全球含中国境内较大地震。2.4 性能限制API QPS上限为10次/秒建议单次查询使用合理参数如limit100避免频繁小请求。超出限制会返回429状态码。三、鉴权与请求参数3.1 认证方式采用Bearer Token认证在HTTP Header中传递Authorization: Bearer 你的API Key同时兼容X-API-Key头部可任选一种以文档为准。请确保API Key具有访问该接口的权限。3.2 请求体字段详解请求方法POST请求体为JSON对象字段如下参数名类型必填说明可选值periodstring否时间范围hour / day / week / monthlevelstring否震级档位all / significant / 4.5 / 2.5 / 1.0min_magnitudenumber否最小震级过滤0不过滤0 ~ 10orderstring否排序方式time / magnitudelimitnumber否返回条数上限1-5001 ~ 500注意所有参数均为可选但建议至少指定period和level以获取有意义的数据。若不传参可能返回默认范围数据需参考文档确认。四、cURL接入示例以下命令查询最近1天内所有震级≥4.5的地震按时间排序返回100条curl -sS \ -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {period: day, level: all, min_magnitude: 4.5, order: time, limit: 100} \ https://v1.apizero.cn/api/earthquake请将YOUR_API_KEY替换为真实密钥。成功返回HTTP 200响应体为JSON。五、返回值深度解读成功响应的结构如下基于素材中的示例{ code: 0, msg: 成功, request_id: abc123, data: { earthquakes: [ { id: us7000abcd, magnitude: 6.5, magnitude_type: mww, depth_km: 42.3, time: 2026-07-01 09:12:30, timestamp: 1782877783910, latitude: 5.62, longitude: 125.11, place: 34 km WSW of Sarangani, Philippines, event_type: 地震, intensity_mmi: 5.2, alert: green, tsunami: false, felt: 49, significance: 650, status: 人工复核 } ], summary: { count: 100, total: 240, generated_at: 2026-07-01 12:45:33, period: day, level: all, max_magnitude: 6.5 } } }5.1 顶层字段code0表示成功非0表示错误。msg结果描述。request_id请求唯一标识可用于排查。data核心数据容器。5.2 data.earthquakes数组每个地震对象字段说明字段类型含义idstring事件唯一ID如USGS事件编号magnitudenumber震级值magnitude_typestring震级类型如mww矩震级, ml里氏震级depth_kmnumber震源深度千米timestring事件发生时间时间格式可能为UTC或本地以文档为准timestampnumber时间戳毫秒latitude/longitudenumber经纬度placestring地点英文描述event_typestring事件类型通常为地震intensity_mminumber修正麦加利烈度估计值alertstring警报级别green/yellow/orange/redtsunamibool是否可能引发海啸feltnumber被感知报告数significancenumber地震显著性评分USGS指标statusstring数据状态如人工复核、自动处理5.3 data.summary对象count实际返回的地震条数。total满足查询条件的总事件数可能大于count用于分页参考。generated_at响应生成时间。period/level实际使用的查询参数。max_magnitude查询结果中最大震级。六、常见错误与排查HTTP状态码错误场景处理建议401认证失败检查Authorization头格式和API Key是否有效400请求参数错误如JSON格式错误、字段类型不符验证JSON有效性确保period和level在枚举值内429请求频率超限QPS超过10降低请求频率添加指数退避重试500服务端内部错误稍后重试或联系技术支持另外若code不为0msg字段会提供具体错误描述。建议在应用层统一检查code而非仅依赖HTTP状态码。七、工程化注意事项7.1 缓存策略API网关缓存60秒业务侧无需额外缓存。但如果需要更实时的数据可以每30秒轮询一次注意控制QPS。推荐使用定时任务如cron或schedule每1分钟执行一次查询避免无效高频调用。7.2 数据时效性地震事件发生到API可查询存在数分钟延迟这是全球数据汇集的正常现象。对于速报场景可接受该延迟。如需历史数据可通过调整period参数获取更长时间范围注意limit上限500。7.3 多语言地名处理place字段为英文描述若需中文展示可集成地名翻译API或本地映射表。对于中国境内地震可能出现拼音或英文需根据业务需求做转换。7.4 错误重试与退避网络抖动或服务临时不可达时应实现重试机制。推荐使用指数退避策略首次失败等待1秒第二次2秒第三次4秒最多重试3次。避免同时大量重试导致雪崩。7.5 分页与全量获取单次limit最大500如果需获取更多事件如total2000可通过调整时间窗口如每小时查询一次或震级档位分片拉取。注意API限制建议分批次、错峰请求。7.6 数据一致性返回的summary.total是满足查询条件的总事件数但不同参数组合下该值可能变化。应以earthquakes数组为准并结合min_magnitude过滤保证数据一致性。八、Python代码集成示例以下是一个简单的Python封装包含错误处理和基本使用import requests import time class EarthquakeAPI: def __init__(self, api_key): self.base_url https://v1.apizero.cn/api/earthquake self.headers { Authorization: fBearer {api_key}, Content-Type: application/json } def query(self, periodday, levelall, min_magnitude0, ordertime, limit100): payload { period: period, level: level, min_magnitude: min_magnitude, order: order, limit: limit } try: resp requests.post(self.base_url, jsonpayload, headersself.headers, timeout10) resp.raise_for_status() data resp.json() if data.get(code) 0: return data[data] else: raise Exception(fAPI returned error: {data.get(msg)}) except requests.exceptions.RequestException as e: raise Exception(fNetwork error: {e}) # 使用示例 if __name__ __main__: client EarthquakeAPI(YOUR_API_KEY) result client.query(periodhour, level2.5, min_magnitude3.0, limit10) for eq in result[earthquakes]: print(fM{eq[magnitude]} at {eq[place]} - {eq[time]})注意生产环境中建议增加重试机制、日志记录及配置管理。九、参考文档全球地震速报API文档原始Markdown文档以上文档可能包含更多参数细节和更新说明请以实际内容为准。