适用场景与调用需求全球地震速报API提供按时间范围、震级档位、震级下限、排序等维度组合查询的地震事件数据每分钟更新一次网关缓存60秒。典型使用场景包括防灾监控大屏每隔5分钟轮询当日M4.5地震更新地图标记。速报播报系统实时监测新发生地震触发推送通知。科研数据采集按周或月下载全量地震事件用于统计分析。在这些场景中开发者最关心的往往是“我能多快调多少次会不会被限流”以及“参数有没有边界超限后会怎样”本文围绕这两个问题展开。接口能力边界QPS与参数约束QPS限制10次/秒接口正式文档标注的QPSQueries Per Second为10即每秒最多允许10次请求。超出部分服务端将返回HTTP 429Too Many Requests错误并可能在响应头中附带Retry-After字段建议等待秒数。❗ 注意QPS按API Key维度统计共享于该Key下所有请求即使同时调用不同终端的接口。如果你的应用中同时调用了多个该平台接口计算总QPS时需合并。对于需要更高并发如每秒50次的场景建议使用本地缓存减少重复请求见下文工程化注意事项。或联系平台申请提升QPS素材未提供以官方文档为准。请求体参数约束请求体为JSON对象支持以下字段全部可选但有隐式范围参数名类型可选值 / 范围说明periodstringhour,day,week,month时间区间默认daylevelstringall,significant,4.5,2.5,1.0震级档位默认allmin_magnitudenumber≥ 0最小震级过滤0不过滤注意与level组合效果level决定原始数据集min_magnitude在此基础上二次过滤orderstringtime,magnitude排序方式默认timelimitnumber1–500返回地震条数上限默认可能为100需验证边界限制举例periodlevel组合可能返回空数据例如hour1.0可能没有地震事件。limit最大500超出将自动截断为500。min_magnitude如设为负数接口可能忽略或当作0处理未明确建议提交≥0的值。鉴权方式使用Authorization请求头Bearer Token模式Authorization: Bearer 你的API Key素材中给出的curl示例采用了X-API-Key头两种方式均可但请以官方文档最新说明为准。推荐使用Authorization头因为更符合HTTP标准。curl请求示例可复制验证以下示例查询过去24小时内震级≥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替换为真实Key。若使用X-API-Key头将-H Authorization: Bearer ...替换为-H X-API-Key: YOUR_API_KEY。成功响应返回JSON结构如下节选{ code: 0, data: { earthquakes: [ { id: us7000abcd, magnitude: 6.5, depth_km: 42.3, latitude: 5.62, longitude: 125.11, place: 34 km WSW of Sarangani, Philippines, time: 2026-07-01 09:12:30, tsunami: false, alert: green } ], summary: { count: 100, total: 240, max_magnitude: 6.5, period: day, level: all, generated_at: 2026-07-01 12:45:33 } }, msg: 成功, request_id: abc123 }返回值关键字段解读code: 业务状态码0表示成功非0需参考msg字段。msg: 描述信息如“参数错误”。data.earthquakes: 事件数组每个元素包含id: 唯一事件标识。magnitude: 震级浮点数如6.5。magnitude_type: 震级类型mww/mb/ml等。depth_km: 深度公里。latitude,longitude: 经纬度WGS84。place: 地名英文。time: UTC时间格式YYYY-MM-DD HH:mm:ss需注意时区转换。tsunami: 布尔值是否触发海啸预警。alert: 警报级别green, yellow, orange, red 或 null。felt: 震感报告数可能为0或空。status: 复核状态“自动”或“人工复核”。data.summary: 本次查询的汇总信息包含实际返回条数count、总匹配数total、最大震级等。常见错误与调用边界相关异常HTTP状态码业务code可能原因处理建议4001001请求体JSON格式错误或参数类型不对校验请求体合法性确保min_magnitude为数字4011002Authorization头缺失或Key无效检查Key是否过期或未正确配置4291003QPS超限每秒超过10次降低请求频率或加入本地缓存可考虑指数退避重试5009999服务器内部错误等待后重试如持续报错需反馈平台限流响应示例HTTP 429{ code: 1003, msg: Too Many Requests. Retry after 1 second., request_id: req-xyz }工程化注意事项稳定调用与边界规避1. 本地缓存策略数据每分钟更新对于轮询场景如每5秒刷新大屏不必真的每秒调API而应缓存结果并设置过期时间如30秒。使用Redis或内存缓存均可减少QPS消耗。2. 并发控制与队列化若多个任务需同时调API如同时查询不同参数建议使用信号量控制并发数不超过10与QPS对应或使用请求队列逐次发送避免瞬间超过10次/秒。3. 重试机制对于429/5xx错误采用指数退避重试初始1秒最大30秒并限制重试次数如3次。注意重试时应带上相同的request_id以帮助平台去重素材未说明可不带。4. 参数边界校验所有参数建议在前端做合法性校验如period只允许4种值避免无效请求浪费Key配额。limit使用前取Math.min(limit, 500)防止返回过多数据。min_magnitude建议限制在0~10之间。5. 响应解析容错felt、alert、tsunami等字段可能为null例如地震未引发海啸时tsunami可能为false但罕见情况下可能缺失。建议使用可选链或默认值。time为UTC字符串解析时应明确指定时区。6. 监控与告警在集成环境中记录每次API调用的响应耗时、状态码及request_id当失败率超过阈值如1%时触发告警便于快速排查。参考文档全球地震速报API文档https://apizero.cn/aidocs/earthquake原始接口规范含完整字段https://apizero.cn/aidocs/earthquake/raw.md
