USGS API 全指南：基于 database-lookup 技能构建地震与水文数据的可复现查询

USGS API 全指南基于 database-lookup 技能构建地震与水文数据的可复现查询【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本指南以 scientific-agent-skills 仓库中 database-lookup 技能的 USGS 参考文档 为核心系统讲解美国地质调查局USGS两大公开数据服务——地震危害计划Earthquake Hazards Program与水资源服务Water Services——的完整 API 接入方法。你将掌握全部端点、参数语义、响应结构、速率限制与分页策略并学会按照该技能定义的检索契约—计数先行—来源可审计工作流把一次普通查询变成可被 Agent 与人类复核的确定性检索。USGS 数据服务概览两大公开 API 与访问前提USGS 在 database-lookup 技能中属于地球与环境科学Earth Environmental Sciences域官方描述为覆盖Earthquakes地震与 Water data水文数据两大主题。整个技能目录共收录 78 个公共数据库每个数据库在references/下拥有一份自包含的参考文件usgs.md即为其中一份规定端点、参数、示例调用与注意事项。与技能中许多需要免费注册 API Key 的数据库如 FRED、BEA、NOAA不同USGS 的两套服务有一个显著特点无需任何认证地震 API 与水服务 API 均完全公开不需要 API Key无严格的按用户速率限制但 USGS 官方要求自动化查询方自觉限制请求频率避免过载服务结果集有硬上限地震 API 拒绝返回超过 20,000 个事件的请求必须通过分页或收窄条件解决水文服务则提示大查询可能超时。这意味着 USGS 非常适合作为 Agent 在无需配置凭据前提下即可确定性检索的科学数据源也正因如此它被收录在无需 Key 的公开数据层中。调用前仍建议阅读技能的 数据库选择指南确认 USGS 是否为当前问题的权威来源。Part A地震危害计划Earthquake Hazards Program基础信息Base URLhttps://earthquake.usgs.gov/fdsnws/event/1认证无需任何认证与 API Key速率限制无按用户文档化限制但官方要求限制自动化查询频率返回超过 20,000 个事件的大结果集会直接被拒绝需分页或收窄查询该服务遵循 FDSNWSFederation of Digital Seismograph Networks Web Services事件规范是查询全球地震目录的标准入口。核心端点一查询地震事件/queryGET /query是主要端点返回匹配搜索条件的地震事件。其参数体系可分为时间过滤、空间过滤圆形/矩形、震级与深度过滤、结果控制四组参数类型必填默认值说明formatstring否quakeml输出格式geojson、csv、quakeml、text、kml。需要 JSON 时用geojsonstarttimestring否(当前时间 - 30 天)ISO8601 日期如2024-01-01endtimestring否(当前时间)ISO8601 日期minmagnitudefloat否-最小震级如4.5maxmagnitudefloat否-最大震级mindepthfloat否-最小深度kmmaxdepthfloat否-最大深度kmlatitudefloat否-圆形搜索中心纬度-90 到 90longitudefloat否-圆形搜索中心经度-180 到 180maxradiuskmfloat否-圆形搜索最大半径km需配合 lat/lonminlatitudefloat否-矩形包围盒南边界maxlatitudefloat否-矩形包围盒北边界minlongitudefloat否-矩形包围盒西边界maxlongitudefloat否-矩形包围盒东边界limitint否-返回的最大事件数上限 20000offsetint否1分页偏移从 1 开始orderbystring否time排序方式time、time-asc、magnitude、magnitude-ascalertlevelstring否-PAGER 警报级别green、yellow、orange、redeventtypestring否-事件类型如earthquake、quarry blast示例——查询某区域 2024 年 5.0 级以上显著地震按震级排序https://earthquake.usgs.gov/fdsnws/event/1/query?formatgeojsonstarttime2024-01-01endtime2024-12-31minmagnitude5.0minlatitude30maxlatitude45minlongitude-125maxlongitude-110orderbymagnitudeGeoJSON 响应结构{ type: FeatureCollection, metadata: { generated: 1700000000000, url: https://earthquake.usgs.gov/fdsnws/event/1/query?..., title: USGS Earthquakes, status: 200, api: 1.14.1, count: 42 }, features: [ { type: Feature, properties: { mag: 6.2, place: 15 km NNE of Ridgecrest, CA, time: 1700000000000, updated: 1700100000000, tz: null, url: https://earthquake.usgs.gov/earthquakes/eventpage/ci00000001, detail: https://earthquake.usgs.gov/fdsnws/event/1/query?eventidci00000001formatgeojson, felt: 1500, cdi: 7.1, mmi: 6.5, alert: yellow, status: reviewed, tsunami: 0, sig: 800, net: ci, code: 00000001, type: earthquake, title: M 6.2 - 15 km NNE of Ridgecrest, CA }, geometry: { type: Point, coordinates: [-117.5, 35.8, 10.5] }, id: ci00000001 } ] }必须牢记的坐标约定geometry.coordinates的顺序是[经度 longitude, 纬度 latitude, 深度 depth_km]——经度在前这与日常经纬书写习惯相反是所有下游空间分析如圆形 vs 矩形过滤选择中最容易出错的点。properties中的字段值得逐一解读以便做本地过滤sig显著性分数、cdi社区烈度、mmi修正麦加利烈度、felt感受到的人数、alertPAGER 警报色、tsunami海啸标志、statusreviewed/automatic等审查状态。其中alert与tsunami这类字段如需参与分析需在 检索契约 中明确它们属于服务端过滤还是本地过滤。核心端点二单事件详情/query?eventidGET /query?eventid{EVENTID}formatgeojson返回单个事件的详细信息包括矩张量moment tensor、震源机制focal mechanism与附近城市nearby cities。通常流程是先从批量/query或实时 feed 中拿到事件id如ci00000001再据此请求详情用于震后灾害评估、机理研究等深度场景。核心端点三事件计数/countGET /count/count接受与/query完全相同的参数但只返回匹配事件的数量。这是 database-lookup 技能计数先行原则的直接落地在拉取全量数据前先用 count 估算结果规模判断是否需要分页、是否需要收窄条件从而避免触发 20,000 条上限被拒绝。示例——统计 2024 年 4.5 级以上事件数量https://earthquake.usgs.gov/fdsnws/event/1/count?starttime2024-01-01endtime2024-12-31minmagnitude4.5核心端点四实时预构建 Feed无需参数USGS 提供按时间窗预构建的 GeoJSON Feed分别以每分钟 / 5 分钟 / 15 分钟 / 每小时频率更新https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/significant_month.geojson https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/4.5_week.geojson https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_day.geojson https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson命名模式为{significance}_{timeperiod}.geojson其中significance显著性阈值significant、4.5、2.5、1.0、alltimeperiod时间窗hour、day、week、month这类 feed 参数为零、响应轻量适合 Agent 做实时监测型任务如过去 24 小时全球 2.5 级以上地震也适合作为科学工作流中的触发源。Part B水资源服务Water Services基础信息Base URLhttps://waterservices.usgs.gov/nwis认证无需任何认证与 API Key速率限制无严格按用户限制但 USGS 建议限制自动化请求大型查询可能超时NWISNational Water Information System覆盖全美水文监测站的实时与历史数据是水文、环境与灾害研究中不可替代的权威来源。端点一瞬时值实时数据/iv/GET /iv/返回监测站最近一次传感器读数通常为 15 分钟间隔。参数类型必填默认值说明formatstring否wmljson、xml、wml,1.1、wml,2.0、rdb。需要 JSON 时用jsonsitesstring条件必填-逗号分隔的 USGS 站点编号如01646500stateCdstring条件必填-两位州代码如NYhucstring条件必填-水文单元代码Hydrologic Unit CodebBoxstring条件必填-包围盒west,south,east,north十进制经纬度countyCdstring条件必填-5 位 FIPS 县代码parameterCdstring否00060参数代码。00060流量00065水位gage height00010水温periodstring否-ISO8601 时长如P7D过去 7 天startDTstring否-起始日期时间ISO8601endDTstring否-结束日期时间ISO8601siteTypestring否-站点类型ST河流 stream、GW地下水 groundwater、LK湖泊 lakesiteStatusstring否allactive、inactive、all关键约束sites、stateCd、huc、bBox、countyCd这五个定位参数中至少必须提供一个否则请求无效。在设计检索契约时应把站点空间选择与参数选择parameterCd拆成两个维度避免把站点过滤与变量过滤混为一谈。示例——查询某站点过去 1 天的实时流量https://waterservices.usgs.gov/nwis/iv/?formatjsonsites01646500parameterCd00060periodP1DJSON 响应节选{ name: ns1:timeSeriesResponseType, declaredType: org.cuahsi.waterml.TimeSeriesResponseType, value: { timeSeries: [ { sourceInfo: { siteName: Potomac River near Wash, DC Little Falls Pump Sta, siteCode: [{value: 01646500, agencyCode: USGS}], geoLocation: { geogLocation: {latitude: 38.94977778, longitude: -77.12763889} } }, variable: { variableCode: [{value: 00060}], variableName: Streamflow, ft#179;/s, unit: {unitCode: ft3/s} }, values: [ { value: [ {value: 5280, dateTime: 2024-01-15T00:00:00.000-05:00}, {value: 5310, dateTime: 2024-01-15T00:15:00.000-05:00} ] } ] } ] } }注意该 JSON 是类 WaterML 的冗长嵌套结构name/declaredType/value.timeSeries[]变量名中的#179;是 HTML 实体编码的立方符号ft³/s。参考文档明确建议对于表格化数据rdb制表符分隔格式比 JSON 更简洁易解析。端点二日值历史聚合/dv/GET /dv/返回每日统计值均值、最大值、最小值定位参数与/iv/相同。参数类型说明statCdstring统计代码00001最大值00002最小值00003均值00006总和。默认00003示例——查询某站点 2023 年全年日均流量https://waterservices.usgs.gov/nwis/dv/?formatjsonsites01646500parameterCd00060statCd00003startDT2023-01-01endDT2023-12-31日值端点适合构建时间序列数据集如年度径流分析、干旱评估也是 dataset 构建场景中最常用的人口。结合技能的完整性协议此类全量获取应先估算数据量必要时使用官方批量下载渠道。端点三站点信息/site/GET /site/返回监测站元数据站点名、经纬度、机构代码、数据类型等定位参数同上。示例——弗吉尼亚州当前活跃的河流站点https://waterservices.usgs.gov/nwis/site/?formatrdbstateCdVAsiteTypeSTsiteStatusactivehasDataTypeCdiv注意该例同时使用了hasDataTypeCdiv来限定具有实时instantaneous数据的站点。站点元数据查询是水文检索工作流的前置步骤在查询流量数据前往往需要先通过/site/确认站点编号、站点类型与数据可用性这与 database-lookup 技能先解析标识符、再查询目标数据的通用流程完全一致。端点四预计算统计/stat/GET /stat/返回基于日值预计算的统计量百分位数、均值、中位数用于将当前状况与历史常态对比。示例——查询某站点的日统计百分位数https://waterservices.usgs.gov/nwis/stat/?formatrdbsites01646500parameterCd00060statReportTypedailystatTypeCdmean,p05,p25,p50,p75,p95该端点一次请求即可拿到均值与 p05/p25/p50/p75/p95 五个百分位非常适合当前流量处于历史什么分位这类水情异常判定任务且无需自行下载多年历史数据本地计算。常用参数代码表parameterCd无论是/iv/、/dv/还是/stat/parameterCd都是核心维度。以下是文档给出的常用代码代码说明00060流量/径流Discharge/streamflowft3/s00065水位Gage heightft00010水温Water temperature°C00045降水量Precipitationin00400pH00300溶解氧Dissolved oxygenmg/L00095电导率Specific conductanceuS/cm72019地下水位低于地表深度Groundwater level depthft单位是本表的隐含字段流量以 ft³/s、水温以 °C、降水以英寸计。在检索契约中必须记录单位避免把不同量纲的数据混入同一分析。实战要点把 USGS 查询纳入可审计的检索工作流从发请求升级为确定性检索database-lookup 技能将数据库查询定义为七步工作流定义检索契约 → 选择权威数据库 → 阅读参考文件 → 规划过滤语义 → 有界地发起 API 调用 → 将外部响应视为不可信数据 → 返回可审计结果。落实到 USGS 场景定义契约明确目标实体地震事件/水文时间序列、时间范围、空间范围、需要的字段、以及是定向查询还是穷尽式数据集构建。若空间或时间约束缺失且影响结果正确性应主动澄清而非猜测。过滤语义拆分区分服务端过滤如minmagnitude、starttime、bBox由 API 在返回前应用与本地过滤如sig显著性阈值需取回后在本地判定。USGS 返回的status、alert等字段若涉及敏感结论应记录其过滤依据。有界调用大规模检索前先用/count地震估算规模超过 10,000 条记录、100 次 API 调用或 API 文档的批量使用指引时应先征得用户确认。分页与对账地震 API 使用offset从 1 开始与limit配合做偏移分页USGS 被 SKILL.md 明确列为 Offset/Limit 分页模式数据库之一。逐页记录请求页码、返回条数、累计条数最终将期望总数、服务端返回总数、本地过滤后总数做对账计数不一致时必须显式报错而非给出貌似合理的结果。不可信数据处理API 返回的任何描述性文本都属于第三方内容不得将原始响应直接拼入后续 shell/Python 命令需要提取字段时先抽取并重新校验该字段再用于下一步。返回溯源信息最终答复应包含目标、范围、访问日期、所用数据库、端点、参数、标识符转换、计数对账、本地过滤与警告。水文站编号是天然标识符地表水通常 8 位地下水通常 15 位无需额外转换。速率限制与错误恢复USGS 无强制 Key 认证但技能层面对速率敏感 API 的总原则是限速串行。遇到 HTTP 429/503 限流错误时应短暂等待后重试一次。若请求失败或返回空结果按顺序排查检查站点编号/事件 ID 格式 → 换用替代标识符如用stateCd代替sites→ 参考选择指南的备选数据库如地质/水文类任务可考虑 NOAA 或 EPA→ 明确告知用户哪个数据库失败、错误是什么、改用了什么。常见陷阱与权威提示参考文档在 Notes 中汇总了三条最易踩坑的事实也是 Agent 检索时的高频错误来源地震坐标顺序[lon, lat, depth]——经度在前与常见lat, lon习惯相反水文 JSON 的冗长结构WaterML 式嵌套导致字段层级深、存在 HTML 实体表格化数据优先选rdb格式站点编号位数差异地表水站点通常 8 位如01646500地下水站点通常 15 位编号位数本身是判断站点类型的线索。此外还有两条贯穿全文的硬性约束地震查询结果超过 20,000 条会被拒绝务必limitoffset分页或先用/count预检两套 API 均免费、公开、无需认证因而可以安全地作为 Agent 默认的科学数据源无需处理凭据泄露风险。小结USGS 地震与水文 API 是无需密钥即可访问的权威科学数据源。地震侧通过/query、/count与预构建 Feed 覆盖查询—预检—实时监控三个层次水文侧通过/iv/、/dv/、/site/、/stat/覆盖实时—历史—元数据—统计对比四个层次。将参考文档的完整参数体系与 database-lookup 技能的检索契约、计数先行、分页对账、来源可审计方法论结合即可把这些公开端点转化为可复现、可核查、可被下游科学分析直接消费的确定性检索结果。需要进一步细化检索规则时可继续阅读技能的 检索契约与审计清单 与 数据库选择指南。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考