信息速览
ComCat 最容易被误解的地方，是把它当成一个可以下载的文件。它不是。它是一个事件库加一套接口：一条地震记录由几十家台网各自上报的参数拼成，谁先到谁先占位，谁更权威谁被标为首选，事后还能被更完整的解覆盖掉。
结果是一份会自己改写的目录。同一个 eventid，今天的震级可能和昨天不一样，今天的 ShakeMap 可能已经是第四版。做灾损触发、做余震统计、做训练集切片的人，都得先接受这一点，再决定要不要用它。
这篇先拆结构与口径，再谈边界：哪些数拿得到，哪些数根本拿不到，以及拿不到为什么不等于接口做得差。
| 项目 | 数值 | 依据 |
|---|---|---|
| 全名 | ANSS 综合地震目录 / Comprehensive Earthquake Catalog | 官方页标题与正文 |
| 维护方 | USGS 地震灾害计划，国家地震信息中心（NEIC）执行 | 官方页 |
| 服务版本 | FDSN Event Web Service 2.8.2 | /version 端点 |
| 最早事件 | 1568-01-01，美国康涅狄格州 | 按时间升序查询 |
| 事件主键 | eventid（台网代码 + 台网内编号） |
接口文档 |
| 产品主键 | （source, type, code, updateTime）四元组 | Products 页原文 |
| 目录代码 | 机器清单 62 个，人工页面列出约 30 个 | /catalogs 与 Catalogs 页 |
| 产品类型 | 机器清单 61 种 | /application.json |
| 输出格式 | GeoJSON / QuakeML / CSV / KML / 纯文本 | 接口文档 |
| 单次上限 | 两万条（超出返回 400） | 接口文档与报错原文 |
| 访问门槛 | 无需注册、无需密钥 | 直接调用即返回数据 |
| 许可 | 页面未给 SPDX，页脚指向 USGS 政策页 | 页面通读 |
§1 速览：它是什么，不是什么
§1.1 一句话定义
ComCat 是一个以事件为单位的索引：它不保存波形，保存的是「某年某月某时某地发生了一次地震」这件事，以及各机构对这件事给出的参数、解释与后果估计。
这个区别决定了一切。波形是原始观测，目录是对观测的解释；解释会变，观测不会。所以 ComCat 的版本号从来不是给数据用的，是给服务端代码用的——今天返回的 2.8.2，跟三年前返回的 2.x 之间，字段可能加了、行为可能改了，而数据本身每天都在动。
§1.2 它凭什么值得单独写一条
地震目录不止 ComCat 一家。ISC 有全球目录，EMSC 有欧地中海目录，中国地震台网中心有国内目录，日本气象厅有日本目录。ComCat 的位置特殊在四点同时成立：
第一，它把别人的目录也收进来了。ComCat 不是「USGS 自己的目录」，而是「一个把 ISC-GEM、GCMT、各区域台网、各国火山观测站的信息汇集到同一事件下的容器」。同一个 2024 年能登半岛地震，在 ComCat 里是 us6000m0xl，但它同时挂着 pt24001001（太平洋海啸预警中心）与 at00s6kml3（国家海啸预警中心）两个编号，ids 字段里三个编号并列。
第二，它带产品层。绝大多数目录只给时间、位置、震级三件事。ComCat 在同一条事件下还挂着震动图、经济损失估计、公众烈度上报、有限断层模型、滑坡敏感性——这些是独立生成、独立版本化、独立首选的文件集合。
第三，它开放得彻底。没有注册、没有密钥、没有每日配额公告，一个 curl 就能拿到全球任意时段的数据。这在国家级数据中心里并不常见。
第四，它准实时。自动系统的结果在分钟级入库，人工复核在小时到天级跟进。这让它既是一个历史档案，也是一条正在写入的流。
§1.3 三十秒决策卡：你的处境，它能帮你什么
| 你的处境 | 它能帮你什么 |
|---|---|
| 要做震后灾损初筛，需要在半小时内知道哪里可能出事 | 自动事件加 PAGER 警报级别，事件后十几分钟就有第一版 |
| 要研究某个区域的长期地震活动性 | 一百多年的目录一次拉完，但要先想清楚检测能力的变化 |
| 要做地震动预测模型的训练集 | 事件加 ShakeMap 产品的台站观测，是少见的「预测值与观测值同源」组合 |
| 要做灾害社会学或保险触发研究 | DYFI 的公众烈度上报与 PAGER 的经济暴露估计，是现成的社会响应变量 |
| 要找一条「事件型数据怎么版本化」的工程范例 | 四元组产品主键加首选权重，是一套可以直接抄的设计 |
| 要波形做波形本身的处理 | 给不了，得去 IRIS/EarthScope 的 SAGE 档案 |
§1.4 不适合谁
如果需求是波形信号处理——滤波、拾取、反演震源时间函数——ComCat 一条波形都没有。它连台站元数据都不保存，那部分在 FDSN Station 服务里。
如果需求是秒级地震预警，ComCat 太慢。它的自动结果虽在分钟级，但预警需要的是台站触发后数秒内的估计，那属于 ShakeAlert 一类系统的领域。
如果需求是统一震级的时间序列，它会让你很痛苦。41 种震级代码混在一列里，1900 年前用 mint（基于烈度反推）与 mfa，1900 年后逐渐换成 mb、ms，1970 年代后 mww 才成为大震的默认。把这一列当作一条连续曲线是错的。
如果需求是中国境内的精细目录，ComCat 对中国大陆的收录密度远低于中国地震台网中心，小震缺失严重。跨国比较可以用它，国内研究不该用它当主源。
§2 一条事件记录是怎么长出来的
§2.1 四层结构，从事件往下走
ComCat 的数据模型是树，不是表。理解它的顺序应该是自上而下四层：
| 层 | 是什么 | 谁产生 | 稳定吗 |
|---|---|---|---|
| 事件（event） | 一次物理地震的容器 | ComCat 的关联逻辑 | 稳定，eventid 基本不变 |
| 首选项（preferred origin / magnitude） | 该事件当前最可信的一组参数 | 由首选权重决定 | 会变 |
| 产品（product） | 某一机构某一时刻的某一类产物 | 各台网与 NEIC 流水线 | 只增不改，旧版降级 |
| 附件（contents） | 产品内部的具体文件 | 同产品 | 随产品版本变 |
第一次用的人常在第三层和第四层之间迷路：他们以为 products.shakemap 是一个文件，其实它是一个数组，数组里每个元素都是一次完整的重算，各自带一套附件。能登半岛那次事件，13 类产品合计挂出 198 个附件文件；整个 detail 文档 74 KB。
§2.2 贯穿案例：一条触发流水线
后面几章会反复回到同一个场景，先说清楚它是谁。
再保险公司里有一类岗位，做的是「参数化巨灾债券的触发判定」：合同约定，若某地发生超过某震级的地震，且位置落在约定半径内，债券即触发赔付。判定的输入只有一个——发生了什么、多大、在哪。输出是一个布尔值，但背后挂着几亿美元的现金流。
把这个判定自动化的小系统，姑且叫它 Trigger-One。它的工作是：震后持续轮询 ComCat，把新事件按合同条款比对，命中就立刻发告警，同时在内部账本上留一条不可否认的记录。
这个场景之所以适合当贯穿案例，是因为它把 ComCat 的每一个结构性特征都变成了业务后果：震级被改写会让触发判反；事件被删除会让告警悬空；产品版本更替会让「当时依据的是什么」无法复述；编号合并会让同一次地震被算两次。
§2.3 主键：为什么不能拿「时间 + 位置 + 震级」当键
新手最容易做的事，是把 (time, lat, lon, mag) 四舍五入后当主键去重。这在 ComCat 上会立刻出事。
原因是同一物理地震在目录里可能短暂地存在多个事件，也可能一个事件带着多个台网的编号。能登那次事件的 sources 字段是 ,pt,at,us,，ids 是 ,pt24001001,at00s6kml3,us6000m0xl,——三个编号，一个事件。而如果某个台网先独立上报、随后才被关联，短时间内就会出现两个事件描述同一次震动，最终合并时保留其中一个 eventid，另一个变为别名。
所以正确的键只有一个：eventid。ids 字段是它的补集，用来回答「这次地震还叫过什么名字」。
对 Trigger-One 来说，这意味着账本必须按 eventid 记，不能按「时间戳哈希」记；否则合并发生的那一刻，同一笔赔付会被记两次账。
§2.4 一张事件卡片的逐项解剖
拿 2024 年 1 月 1 日的能登半岛地震，看 query?eventid=us6000m0xl 返回什么。
| 字段 | 值 | 使用时要留意什么 |
|---|---|---|
mag / magType |
7.5 / mww |
mww 是矩震级，大震首选；中小震常是 mb 或 ml |
place |
2024 Noto Peninsula, Japan Earthquake | 这是地名串，含逗号，直接切 CSV 会错列 |
time |
1704093009476 | 毫秒时间戳，不是秒 |
geometry.coordinates |
[137.271, 37.4874, 10] | 顺序是经度、纬度、深度 |
status |
reviewed | 已复核。自动事件这里是 automatic |
alert |
red | PAGER 五级中的最高级，缺失表示没有 PAGER 产品 |
sig |
2376 | 显著性分值，派生量，随产品更新而变 |
tsunami |
1 | 表示「可能引发海啸」，不是「已引发」 |
felt / cdi |
422 / 8.9 | 公众上报数与其最大社区烈度 |
mmi |
8.793 | ShakeMap 的最大修正麦卡利烈度 |
nst / gap / rms |
282 / 36 / 0.55 | 定位质量三件套：台站数、方位角空隙、残差 |
ids |
,pt24001001,at00s6kml3,us6000m0xl, | 逗号串，两端都有逗号，切分后会产生空串 |
最后一行值得单独说：ids 与 sources 的格式是「逗号分隔且首尾都带逗号」。用 split(",") 会得到三个空串加三个真值，新手极容易在这里数错事件数。
§2.5 产品层：61 种类型，但常用的只有八种
application.json 列出的产品类型有 61 个。这个清单里有几项明显不是给人看的——比如 1903 Tonga Earthquake、Impact、trump-shakemap 这类字符串，是历史遗留与测试数据的产物。把 61 当成「有 61 种产品可用」会高估。
真正稳定可用的是这几类：
| 产品类型 | 内容 | 覆盖 |
|---|---|---|
origin |
震源参数（时间、位置、深度、定位质量） | 几乎全事件 |
phase-data |
参与定位的震相到时 | 多数经复核的事件 |
moment-tensor |
矩张量解，含双力偶机制 | 中强震 |
focal-mechanism |
初动解或矩张量导出的震源机制 | 中强震 |
shakemap |
震动图，含峰值加速度与烈度的栅格与等值线 | 有感以上、有人口暴露的事件 |
losspager |
经济损失与人员伤亡的概率估计 | 同上 |
dyfi |
公众烈度上报的汇总与插值 | 有公众参与的事件 |
finite-fault |
有限断层破裂模型 | 大地震 |
数量上有一条可以自行验证的分界：1900 年以来 M≥4.5 的事件里，带 ShakeMap 产品的有两万三千余条。这个比例说明 ShakeMap 并非「每个事件都有」，它依赖人口暴露与影响评估的必要性。
对 Trigger-One 来说，产品层的第一用途不是取数，而是取证据链：告警发出时依据的是哪个 source、哪个 code、哪个 updateTime 的 origin。这三项不记，半年后复盘时无法证明当时看到的是 7.5 还是 7.3。
§2.6 同一事件的三份 origin：字段是按来源长的
把能登事件的 origin 数组摊开，会看到三份并列的参数，来自三个不同的台网：
| 来源 | 代码 | 复核状态 | 方位角空隙 | 最近台站距离 | 参与定位震相数 |
|---|---|---|---|---|---|
us |
us6000m0xl | reviewed | 36° | 0.957° | 284 |
at |
at00s6kml3 | 字段缺失 | 约 39.6° | 1.212° | 229 |
pt |
pt24001001 | 字段缺失 | 字段缺失 | 字段缺失 | 字段缺失 |
三份参数描述同一次地震，但完整度差别极大：us 那份有完整的质量指标，pt 那份连方位角空隙都没有。这不是数据错误，而是产品模型的设计——origin 的 properties 是一个自由字典，每个台网按自己的处理流程往里填，缺的字段就真的不存在，不会补成空串或零。
对使用者有三个直接后果。
第一，不能按固定 schema 解析产品属性。任何写死「读 azimuthal-gap」的代码，遇到 pt 的产品会抛异常。稳健的写法是逐字段 .get() 并允许 None。
第二，质量指标只在同源产品之间可比。us 的 36° 与 at 的 39.6° 看似可以比较，但两者的台站集合、震相选择、定位算法都不同，差值不代表谁更准。
第三，默认查询只会给你首选那一份。上面这三份能同时看到，是因为用了 eventid 查询——官方文档写明，指定 eventid 会隐含打开 includeallorigins 与 includeallmagnitudes。用普通的时间窗查询，每个事件只返回一个 origin，其余两份看不到。
这一条对追溯类应用是决定性的。Trigger-One 的复盘要求「当时看到哪一份」，而时间窗查询根本不给这个信息，只有按 eventid 回查才能拿到全量。
§3 身份层：编号、代码与谁说了算
身份层要回答的问题只有一个：这东西到底是哪一个。在地震目录里，这个问题比在多数数据集里更难，因为「同一个东西」有三套编号方式同时在跑。
§3.1 三套编号：事件、产品、目录
| 编号对象 | 形式 | 例子 | 作用 |
|---|---|---|---|
| 事件 | 台网代码 + 台网内序号 | us6000m0xl |
全世界唯一指向一次物理地震 |
| 产品 | 四元组 | (us, origin, us6000m0xl, 1710020297040) |
指向某机构某次计算 |
| 目录 | 两字母代码 | us、gcmt、iscgem、ci |
指向数据来源的编纂体系 |
三者不是层级关系，是三种正交的视角。一次事件可以有多个产品，每个产品属于某个来源；一次事件也可能同时被多个目录收录，此时 catalog=us 与 catalog=iscgem 两次查询会返回同一次地震的两个不同参数版本。
这正是 ComCat 最有价值也最容易踩坑的地方：它允许你按目录切片，而不同目录的参数不可混用。
§3.2 62 个目录代码，其中一半不能用
/catalogs 端点返回 62 个代码。人工维护的 Catalogs 页面只列了约 30 个，并给出每个的来源与覆盖期。
差额在哪？在机器清单里混着这些字符串：20、=c、38457511、nc73947885、nc75096636、official19631013051759_30、us7000kg6v、wa22。它们看起来像测试遗留或单事件调试入口。把它们当成合法目录去遍历，会得到空结果或报错。
可靠的做法是以人工页面的清单为准，或者反过来——先用 count 探一下某个代码是否有返回，再决定要不要纳入遍历。Trigger-One 的做法更保守：只用 us（NEIC 全球目录）一个代码，把其他目录当作补充证据而非数据源。
§3.3 目录与贡献者是两个维度
除了 catalog，接口还有一个 contributor 参数。这两个词在日常语境里几乎同义，在 ComCat 里不是。
- catalog 指编纂体系：这批参数是按哪套规则整理出来的（
iscgem、gcmt、us）。 - contributor 指上报机构：这条记录是谁送进来的（
ak、ci、uu、nc、us）。
贡献者清单只有 29 个，比目录少一半，而且里面还有 admin、prod01-pdl01.cr.usgs.gov 这种明显是系统账号的条目。
官方文档写明：当 catalog 与 contributor 都不指定时，返回的是「任何目录或贡献者中最首选的信息」。这句话是理解默认行为的关键——默认查询给你的不是某一个目录，而是各目录拼出来的一个最佳猜测。
§3.4 覆盖期：一页停在 2020 年的表
ComCat 有一个「数据可用性」页面，列出每个目录代码的起止时间。这页的标题写得很清楚：目录可用性截至 2020 年 10 月 20 日。
这是一张六年前的快照。它列出的 USHIS 起始时间是 1663-02-05，但按时间升序查询全库，第一条记录是 1568-01-01 的康涅狄格事件，来源也是 ushis。也就是说这张表本身就与数据不一致。
从这张表能读到的、仍然有效的结构性事实是这些：
| 目录 | 起 | 说明 |
|---|---|---|
official |
1638-06-11 | USGS 震级工作组的历史大震汇编 |
ushis |
1663-02-05（表内） | 美国历史地震，实际早至 1568 |
cdmg |
1856-09-21 | 加州矿业地质局老目录，止于 1884 |
iscgem |
1900-07-29 | ISC-GEM 主目录，全球 1900 年后的基准 |
us |
1973-01-01 | NEIC 的 PDE 目录，全球日常运转的主干 |
gcmt |
1977-11-27 | 全球矩心矩张量，止于 2016 |
最后一行的截断值得注意：gcmt 在表里止于 2016 年，但 GCMT 项目本身仍在产出。这说明这张表记录的是「ComCat 当时同步到哪」，而不是「上游到哪」。用这张表判断某目录是否还活跃会得出错误结论。
§3.5 引用与 DOI
官方的 References 页面给出了三条主线文献：Flinn-Engdahl 地区化方案的三篇原始论文、NEIC 系统集成的 2015 年开放文件报告、以及 2017 年的 ANSS 综合目录数据发布条目。
数据本身的 DOI 是 10.5066/F7MS3QZH，解析后会落到地震检索页。这个 DOI 指向的是「这套目录」这个集合，不是某个版本快照——这跟很多数据仓库的 DOI 语义不同，引用时不能指望它锁定内容。
§4 质量层：首选、复核与删除
这一章处理的是「它可信吗」，以及一个更麻烦的问题：可信度是随时间变化的，而查询默认只给你当前状态。
§4.1 首选权重：官方给了公式，但公式算不出观测值
官方 Products 页面写得很细。一个产品在同类中被选为首选，依据是「首选权重」最大；权重由四项相加：
| 分量 | 值 | 触发条件 |
|---|---|---|
DEFAULT_PREFERRED_WEIGHT |
1 | 所有产品都有 |
SAME_SOURCE_WEIGHT |
5 | 产品来源与事件来源相同 |
AUTHORITATIVE_WEIGHT |
100 | 产品作者位于该产品的权威区域 |
AUTHORITATIVE_EVENT_WEIGHT |
50 | 产品指向一个权威事件 |
四项全满足是 156。但能登事件的返回值不是 156：origin 是 158，moment-tensor 是 218，shakemap 是 232。
差在哪，官方页面没有解释。这留下一个实用结论：不要试图用公式复现首选判定。想知道哪个是首选，看 preferredWeight 的最大值，或者干脆相信接口默认返回的那一个（默认查询返回的 properties.mag 就是首选震级）。
这个细节对 Trigger-One 有直接后果：如果系统按「自己复算权重」来判断该信哪个 origin，会在某些事件上选错版本，而错的那一版可能差 0.2 级——刚好跨过合同阈值。
§4.2 复核状态：一周里三分之一是自动的
status 只有两个值：automatic 与 reviewed。查询接口可以用 reviewstatus 参数过滤。
以 2026 年 10 月 22 日起的七天窗口为例：自动状态 673 条，已复核 1,323 条。也就是说，任何时刻去查最近一周，大约三分之一的事件还停留在机器初判阶段。
自动事件的特征不只是「可能被改」：
- 位置误差更大，深度常常被固定在某个默认值上；
- 往往没有
moment-tensor、shakemap、losspager； - 有些自动事件连
products都是空字典——查一个 2026 年 10 月 28 日的加州 M2.62 事件，status是automatic，products返回{}。
最后这条对任何按产品取数的流水线都是硬约束：不能假设「每条事件至少有 origin 产品」。
§4.3 改写：同一 eventid 的震级会变
震级改写在 ComCat 上是常态而非异常。机制是：自动系统先用少量台站给出初值，人工复核时用更多台站、更长周期、更好的方位覆盖重算，写入新的 origin，旧版降级为非首选但保留。
这就是为什么目录里同一次事件会有 3 个 origin 产品（能登那次就是 3 个），而查询默认只返一个。
对做时间序列的人，这意味着：今天拉的数据和上个月拉的同一天的数据，不会完全相同。任何需要复现的研究，必须连 updateTime 一起存档，或者在拉取时加 updatedafter 参数只取增量。
§4.4 删除：不是所有事件都能查到
ComCat 支持删除事件，被删的事件在默认查询里返回 HTTP 409 Conflict。要拿到它们，必须显式加 includedeleted=true，或者用 includedeleted=only 只取已删除的。
删除的理由有多种：误检（把爆破判成地震）、重复（两个自动系统各报一次，合并后删掉一个）、数据质量不合格。官方另设了一个「已删除地震」的浏览页面，说明这不是边角功能，而是常规运维。
对 Trigger-One，这一条决定了一个设计：已发出的告警不能因为事件被删就自动撤销。业务上必须有人工确认环节，否则会出现「系统说触发了、账本上却查无此事」的对账僵局。
§4.5 震级口径：41 种代码，没有换算表
application.json 里的 magnitudetypes 有 41 个取值。常用的几个：
| 代码 | 含义 | 典型用途 |
|---|---|---|
mww |
W 相矩震级 | 中大震首选，全球标准 |
mwc |
矩心矩张量震级 | GCMT 产品 |
mwr |
区域矩震级 | 区域台网大震 |
mb |
短周期体波震级 | 中震，历史序列长 |
ms 或 ms_20 |
面波震级 | 老目录主力 |
ml |
地方震级 | 区域小震 |
md |
持续时间震级 | 台网密集区小震 |
mint / mfa |
由烈度反推 | 1900 年前历史地震 |
mint 与 mfa 的存在说明一件事：历史地震的「震级」不是测出来的，是从文字记载的破坏程度反推的。1615 年多米尼加南岸那次 7.5 级，代码是 mint；1693 年西西里那次 7.4 级，代码是 mfa。这两个数和 2024 年能登的 7.5 不是同一种量。
把它们放进同一条曲线做趋势分析，等于把三种尺子的读数求平均。
§4.6 完整性：1900 年是一条硬分界
| 时段 | 记录来源 | 深度字段 | 可比的量 |
|---|---|---|---|
| 1568–1899 | 文献回溯（ushis、eqh、official） |
普遍缺失 | 只能比「有没有大震」 |
| 1900–1972 | ISC-GEM 等国际汇编 | 部分有 | 可与 ISC 交叉校验 |
| 1973–1990 | NEIC PDE 日常运转 | 多数有 | 全球 M≥4.5 大致完整 |
| 1991–现在 | 叠加区域台网自动处理 | 完整 | 小震密度大幅上升 |
第三行到第四行的跳变最容易被误读成「地震变多了」。真实原因是台网密度与自动处理能力的提升，把原本测不到的小震测出来了。任何跨越 1990 年的频次分析都必须先做检测能力校正，而 ComCat 本身不提供这个校正。
§4.7 修订在数据里留下的痕迹
ComCat 不提供「变更日志」接口，但修订不是无形的——它会在三个地方留下痕迹。
第一处是 updated。每条事件有一个 updated 时间戳，等于该事件下所有产品 updateTime 的最大值。它能回答「这条记录最后一次动是什么时候」，但回答不了「动了什么」。
第二处是产品的多版本共存。同一 (source, type, code) 下如果有两条 updateTime 不同的记录，那就是一次修订；默认只返回权重最高的那条，其余要在 eventid 查询里才看得到。
第三处是 evaluation-status。origin 产品内部有这个字段，取值 reviewed 表示人工确认过。它比事件级的 status 更细：一个事件的 status 是 reviewed，指的是它的首选 origin 经过了复核，不代表它下面每一个产品都复核过。
三处合起来能做一件有用的事：还原某条记录在某个时间点的样子。方法是以目标时刻为界，取所有早于它的产品版本，再按权重选出当期首选。这套回溯逻辑官方没有提供接口，得自己实现，libcomcat 里有部分封装。
对做长期监测的系统，这套逻辑不是可选项。没有它，「上周的报表为什么和这周的对不上」这个问题永远答不了，而这个问题在任何一个需要向外部解释的系统里都会被问到。
§5 工具层：怎么取、怎么翻页、怎么不被打断
§5.1 三条路径，用途不重叠
| 路径 | 端点 | 适合 | 不适合 |
|---|---|---|---|
| 网页检索 | earthquake.usgs.gov/earthquakes/search/ |
一次性查、看地图、导小表 | 批量、脚本化 |
| 实时 feed | /earthquakes/feed/v1.0/summary/*.geojson |
轮询最新事件 | 历史回溯 |
| FDSN 服务 | /fdsnws/event/1/query |
任意时段与条件的批量取数 | 超大数据量的单次请求 |
官方在接口文档里专门写了一句：自动化应用做实时展示时应优先用 feed，因为它在性能和可用性上更好。这句话有实际意义——feed 是静态文件，走 CDN；FDSN 是数据库查询，会超时。
§5.2 先看懂默认值，再写第一行代码
接口文档的参数表里藏着三个默认值，每一个都能让新手的第一份数据出错：
| 参数 | 默认 | 后果 |
|---|---|---|
starttime |
当前时间减 30 天 | 不带参数的查询只给最近一个月 |
format |
quakeml |
不带 format 拿到的是 XML，不是 GeoJSON |
orderby |
time（降序） |
想按时间正序必须显式写 time-asc |
第一条最坑。直接调 count?format=text 得到一个四位数——那是最近 30 天的全部事件数，不是全库。想拿全库必须显式给 starttime。
§5.3 20,000 是硬上限，翻页是软上限
limit 的合法区间是 1 到两万，超出直接报错。原话是：
Bad limit value "20001". Valid values are 0 <= limit <= 20000
但 offset 在文档里写的是「Integer [1,∞)」，没有上界。实际测下来：
| offset | 结果 |
|---|---|
| 20,000 | 200，正常返回 |
| 20,001 | 200，正常返回 |
| 50,000 | 503 |
| 100,000 | 503 |
所以「只能取前两万条」是错的，正确说法是「单次两万条，翻页可以更深，但深到几万条之后服务端会撑不住」。想稳定拿几十万条，唯一的办法是把时间段切细，让每个窗口的结果都远小于两万。
§5.4 全库总数：不是算不出，是聚合撑不住
不带震级下限、不限起始时间的 count 请求，返回的不是数字，而是：
Error 503: Service Unavailable
SQLSTATE[HY000]: General error: 1114 The table '/rdsdbdata/tmp/#sql164_1b865b2d_3e84' is full
服务端的临时表被这个聚合撑爆了。换更早的起始时间、或不设震级下限，结果一样；有一次直接返回 504 网关超时。
这不是配额限制，也不是两万条上限的延伸——count 方法压根不返回事件列表。它是数据库层面的资源边界。结论是：ComCat 的全库总量在公开接口上不可得，只能用带约束的口径去逼近。
加一个震级下限就立刻可行：M≥5 且 1900 年起，count 一秒返回六位数。加 eventtype 也行，采石场爆破能单独数出来。
§5.5 三个可直接运行的查询
第一段，先确认默认值陷阱。
#-- 不带参数:服务默认只查最近 30 天,返回一个四位数
curl -s "https://earthquake.usgs.gov/fdsnws/event/1/count?format=text"
#-- 显式给起点与震级下限:这才是历史口径
curl -s "https://earthquake.usgs.gov/fdsnws/event/1/count?format=text&starttime=1900-01-01&minmagnitude=5"
第二段，按时间窗口分页，绕开两万条的限制。
#-- 依赖 requests;按年切片,保证每个窗口都远小于单次上限
import requests
BASE = "https://earthquake.usgs.gov/fdsnws/event/1/query"
def fetch_window(start, end, minmag=4.5, page=20000):
rows, offset = [], 1
while True:
r = requests.get(BASE, params={
"format": "geojson", "starttime": start, "endtime": end,
"minmagnitude": minmag, "limit": page,
"offset": offset, "orderby": "time-asc"}, timeout=180)
r.raise_for_status()
got = r.json()["features"]
rows.extend(got)
if len(got) < page:
return rows
offset += page
one_year = fetch_window("2024-01-01", "2025-01-01")
print(len(one_year), one_year[0]["id"], one_year[0]["properties"]["magType"])
第三段，取单事件的完整产品树与证据链。
#-- 单事件 detail:产品字典 + 每个产品的首选权重与附件清单
import requests
ev = requests.get(BASE, params={"format": "geojson",
"eventid": "us6000m0xl"}, timeout=60).json()
p = ev["properties"]
print(p["mag"], p["magType"], p["status"], p.get("alert"))
for ptype, versions in sorted(p["products"].items()):
top = max(versions, key=lambda v: v["preferredWeight"])
print(ptype, len(versions), top["source"], top["updateTime"], len(top["contents"]))
输出的每一行都是一条可审计的记录：这一类的当前首选是哪个来源、什么时候算的、带几个附件。Trigger-One 的账本就存这几列。
§5.6 官方客户端
USGS 自己维护了一个 Python 客户端 libcomcat（在 code.usgs.gov 上），封装了检索、产品下载、以及历史版本追溯。它对「取某个事件某一时刻的参数」这类需求支持得比手写 curl 好，但引入了额外依赖，且版本更新节奏与接口不一致。做长期运行的服务，直接用 requests 更可控；做一次性分析，libcomcat 省事。
§5.7 feed 是十六格矩阵，不是四个文件
实时 feed 的路径规则是「震级档 × 时间窗」。震级档四档：all、2.5、4.5、significant；时间窗四档：hour、day、week、month。四乘四，十六个静态文件，全部返回 200：
#-- 十六格全部可用;轮询时按需挑一格,不要一上来就拉 all_month
for m in all 2.5 4.5 significant; do
for w in hour day week month; do
code=$(curl -s -o /dev/null -w "%{http_code}" \
"https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/${m}_${w}.geojson")
echo "${m}_${w} ${code}"
done
done
同一批 feed 还有 ATOM、KML、CSV 等格式变体，以及按板块边界划分的区域子集。选格子的经验：做告警轮询用 4.5_hour 或 2.5_day，做周报汇总用 significant_week，做地图展示才用 all_day。
all_month 是一个容易被误用的格子：它是四个震级档里唯一会把全球所有微小事件都塞进来的一个，条目数在万级以上，单次请求的体积比 4.5_month 大一个量级，而其中绝大多数事件对任何下游分析都没有意义。
feed 与 FDSN 还有一个语义差别：feed 是按时间窗滚动的快照文件，同一时刻多次请求返回的内容会因为新事件插入而整体位移；FDSN 是按条件查询的数据库结果，同样的参数在同样时刻返回同样的集合。做增量同步时，feed 适合触发，FDSN 适合补数。
§5.8 五种返回码，五种处置方式
把出错情况当成「重试就好」是最常见的工程事故。ComCat 返回的五类错误码对应完全不同的原因：
| 状态码 | 触发条件 | 该做什么 |
|---|---|---|
| 400 | 参数非法，如 limit=20001 |
改参数，重试无用 |
| 404 | eventid 不存在 |
检查编号拼写；也可能是事件已被删除 |
| 409 | 事件已删除，且未加 includedeleted |
决定是要跳过还是显式取回 |
| 503 | 数据库临时表溢出，常见于无约束的大范围聚合 | 缩小时间窗或加震级下限，退避重试 |
| 504 | 网关超时，常见于长时段无震级约束的统计 | 同上，且要考虑拆成多段 |
三者的处置逻辑必须分开写。把 400 当 503 去重试，会把一个永远不会成功的请求重试到天亮；把 409 当 404 忽略，会静默丢掉一条本该被记录的事件删除。
Trigger-One 的一处真实设计取舍来自 409：它把「收到 409」当作一条需要人工确认的待办，而不是一条错误。理由是删除本身携带信息——系统曾被自动判为地震的东西，被专家判定为爆破，这恰恰是模型值得学的样本。
§6 规模与边界：能数的数和数不出的数
§6.1 六种问法，六个答案
同一个目录，换一种问法就换一个数。下表全部来自 count 端点的直接返回，查询时间为 2026 年 10 月 29 日。
| 问法 | 返回 |
|---|---|
| 1900 年起，M≥5 | 107,560 |
| 1900 年起，M≥6 | 14,546 |
| 1900 年起，M≥7 | 1,620 |
| 1900 年起，M≥8 | 100 |
| 1970 年起，M≥4.5 | 296,997 |
| 2000 年起，M≥4.5 | 188,248 |
这六个数的用途不是「说明它有多大」，而是说明**「有多大」这个问题本身不成立**。目录的规模是一个随阈值单调变化的函数，不是一个属性。
顺带可以得到一条有用的经验：M≥8 全时段只有三位数，这意味着任何以「巨震」为研究对象的模型，样本量都在百这个量级上，交叉验证的方差会很大。
§6.2 它不只是地震
| 事件类型 | 1900 年起计数 |
|---|---|
quarry blast（采石场爆破） |
73,431 |
explosion（爆炸） |
35,520 |
这两行是这份目录最容易被忽略的边界。七万多次爆破混在地震目录里，绝大多数来自美国境内的区域台网——它们是小震级、浅源、波形上与天然地震可区分但自动系统常常误判的事件。
做任何「地震频次」的统计，第一件事就是加 eventtype=earthquake。官方的参数说明也专门提示了这一句。
反过来，如果研究对象是「人类活动引发的地震信号」，这两类反而是现成的负样本库。
§6.3 实时流的规模
feed 与 FDSN 是两套东西，规模也不同。四个常用 feed 在同一时刻的条目数：
| feed | 条目 | 时间窗 |
|---|---|---|
all_week |
1,862 | 全部震级，近 7 天 |
2.5_day |
46 | M≥2.5，近 1 天 |
4.5_month |
746 | M≥4.5，近 30 天 |
significant_month |
19 | 显著事件，近 30 天 |
all_week 的 1,862 条与前面 count 得到的「最近 30 天四位数」是同一量级的两个侧面：全球全部震级的日均事件数在两百到三百之间，其中绝大多数永远不会进入任何人的视野。
§6.4 单事件的体积
一个信息完整的大震事件，detail 文档 74 KB，13 类产品合计 198 个附件。附件本身不是这个量级——ShakeMap 的栅格、PAGER 的 PDF、DYFI 的 GeoJSON 加起来可以是几十 MB。
这意味着「把全库下载下来」不是一个可讨论的方案：不是接口不给，是体积与请求数都不现实。可行的做法是按需切片——先拉事件列表（轻），再按需拉产品（重）。
§6.5 事件的时间下界
第一条记录是 1568 年 1 月 1 日，美国康涅狄格州，M4.9，来源 ushis。这个日期只有年，没有月日——历史地震的时间精度就是这样。
更有意思的是 1627 年那条：地点「Near Essex, Massachusetts」，type 是 not existing。这是一个明确标记为「不存在」的占位记录，用来保留文献中出现过但被判定为误记的条目。
not existing 这个类型的存在，说明这份目录的设计目标不只是「记录发生过什么」，还包括「记录被否定过什么」。做数据清洗时把它过滤掉很容易，但知道它为什么在那里，能避免把「目录里有这条」误当成「这件事发生过」。
§6.6 时间的精度是分层的，而字段格式看不出来
time 字段统一是毫秒时间戳，格式上完全一致。但格式一致不等于精度一致。
| 事件 | 时间字段读出来 | 实际精度 |
|---|---|---|
| 2024 能登 | 2024-01-01T07:10:09.476 | 毫秒 |
| 1615 多米尼加南岸 | 1615-09-08T03:00:00.000 | 名义值，03:00 不是测出来的 |
| 1663 拉马尔拜 | 1663-02-05T22:30:00.000 | 名义值，来自文献记述 |
| 1568 康涅狄格 | 1568-01-01T00:00:00.000 | 只有年，月日都是占位的 1 月 1 日 |
最后一行是这份目录里最容易被误算的地方：1568 那条的月日是 01-01，那是「不知道月日」的填充值，不是「1 月 1 日发生」。如果按「年内第几天」做季节性分析，这类事件会全部堆在第一天，造出一个虚假的年初高峰。
同样的坑在历史地震里普遍存在：时分秒常被填成整点或半点，因为文献只说「夜间」「午后」。把这些时刻当作真实观测时间去做潮汐触发、日月引潮力这类需要精确到分钟的研究，结论必然是噪声。
一条可以写进流程的判断规则：time 的精度随年代递减，1900 年前一律按「日期级」使用，1960 年前按「小时级」使用，之后才可信到秒。这条规则没有官方文档背书，是从数据本身的形态反推的，但它比任何「字段统一即精度统一」的假设都可靠。
§7 评价框架：它不该按什么标准被评价
§7.0 阅读本节前需要知道的一件事
ComCat 不是数据集，是基础设施。用「数据集」的尺子量它，会得出「没有划分、没有标签、没有去重、字段不齐」的结论；用「API」的尺子量它，会得出「版本混乱、字段可选、行为随事件而变」的结论。两种结论都成立，但都没有解释为什么全球的地震研究、灾害评估与保险定价都绕不开它。
正确的尺子只有一个：作为一份持续运转的权威记录，它的可追溯性够不够强。可追溯性的意思是：任何一条结论，能不能顺着记录回到「谁在什么时候用什么数据算出这个数」。
按这把尺子量，ComCat 做得非常好的一点是四元组主键加 updateTime：任何时候的数据都能被精确定位到某一机构某一次计算。做得不够的是另一面：它不告诉你这次计算用了哪些台站、为什么改、改了多少——那部分在 phase-data 产品里，但要自己啃。
§7.1 三种常见的评价错位
| 错位 | 表现 | 应该怎么想 |
|---|---|---|
| 拿静态数据集的完整性标准套它 | 抱怨「没有统一的总条数」「没有版本快照」 | 它的设计目标是持续更新，快照要靠调用方自己存 |
| 拿机器学习基准的标签标准套它 | 抱怨「没有类别标签」「没有 train/test」 | 它不是基准，是原始素材；划分是你的建模决策 |
| 拿商业数据库的 SLA 套它 | 抱怨深度翻页 503 | 它是公共品，服务端资源有限，取数策略要适配 |
§7.2 DAIMS 二十四项逐条对照
用数据质量评估框架的二十四项检查点，把它的成熟度摊开。
| # | 检查项 | 状态 | 说明 |
|---|---|---|---|
| 1 | 宽格式 | ⚠️ | GeoJSON 嵌套四层，拍平要自己写；CSV 是扁平的但只有 22 列 |
| 2 | 唯一标识 | ✅ | eventid 稳定，别名记在 ids |
| 3 | 特殊字符 | ⚠️ | place 含逗号，CSV 已加引号但正则切分会错 |
| 4 | 重复行 | ❌ | 同一地震可短暂对应多个事件；合并后别名仍留在 ids 里 |
| 5 | 缺失编码 | ⚠️ | 空值即空串或 null，无统一 NA 标记；早期深度缺失 |
| 6 | 标签标识 | ❌ | 无分类标签体系，eventtype 是事件性质而非任务标签 |
| 7 | 罕见类分组 | ⚠️ | M≥8 全时段三位数，长尾极陡 |
| 8 | 偏倚评估 | ❌ | 检测能力随年代与区域剧变，官方无量化说明 |
| 9 | 数据字典 | ⚠️ | 参数文档完整，字段语义散落在多个页面 |
| 10 | 信息性缺失解释 | ⚠️ | 缺深度不解释；not existing 类事件无字段说明 |
| 11 | 设备记录 | ❌ | 台站元数据不在 ComCat，需另取 StationXML |
| 12 | 共线性 | ⚠️ | sig 与 mag、cdi 与 mmi 高度相关，无官方说明 |
| 13 | 编码映射 | ⚠️ | 41 种震级代码无换算表 |
| 14 | 时间戳处理 | ✅ | 全 UTC，毫秒整数或 ISO8601，无歧义 |
| 15 | 划分建议 | ❌ | 无；时间切分是事实标准但无官方协议 |
| 16 | 泄漏讨论 | ❌ | 无；但按时间切分是硬约束，未来信息不可能进训练 |
| 17 | 标签分布 | ❌ | 无标签，不适用 |
| 18 | 测量偏倚 | ⚠️ | automatic 与 reviewed 分层明显，需分开处理 |
| 19 | 外部验证建议 | ⚠️ | 可与 ISC、EMSC 交叉，官方未给对照方案 |
| 20 | 版本记录 | ✅ | 四元组加 updateTime，这一项做得比多数数据集好 |
| 21 | 预处理脚本 | ⚠️ | 有官方客户端 libcomcat，但无端到端处理脚本 |
| 22 | 合规要求 | ⚠️ | 无 SPDX；上游贡献方条款不统一 |
| 23 | 多模态对齐 | ❌ | 产品附件格式各异，无对齐清单 |
| 24 | 去标识化 | ✅ | 无个人数据；DYFI 上报已匿名 |
DAIMS 评分：10 / 24。按 ✅ 计 1 分、⚠️ 计 0.5 分、❌ 计 0 分，四个满项、十二个半分项、八个零分项。
怎么读这个分数：它比一份整理好的科研数据集低，原因几乎全部落在「不面向建模」这一侧——没有标签、没有划分、没有扁平表。满分项恰好落在「基础设施」该做好的地方：唯一标识、时间戳、版本记录、去标识化。这个分布不是缺陷，是定位。
§7.3 逐条局限
| 局限 | 具体表现 | 后果 |
|---|---|---|
| 全库总量不可得 | 无约束 count 返回 503 | 无法做「覆盖率」类指标 |
| 单次两万条 | limit 上限 |
大时段必须切片，请求数上升 |
| 深翻页不稳 | offset 五万以上 503 | 不能靠单一查询遍历全库 |
| 震级口径混杂 | 41 种代码 | 跨年代序列不可直接比较 |
| 早期深度缺失 | 1900 年前普遍无深度 | 深度相关分析只能截断到 1970 年代后 |
| 产品覆盖不均 | ShakeMap 只在部分事件上 | 按产品统计会引入选择偏倚 |
| 目录代码含垃圾 | 62 个中约一半非真实目录 | 遍历会报错或返回空 |
| 可用性页过期 | 停在 2020-10-20 | 不能用来判断当前覆盖 |
§7.4 外部验证与泛化
ComCat 的交叉验证对象是其他全球目录。可做的对照有三类：
| 对照对象 | 能验证什么 | 注意 |
|---|---|---|
| ISC-GEM | 1900–2010 的全球完整性 | ComCat 里已含 ISC-GEM，不算完全独立 |
| GCMT | 中大震的矩震级与机制 | GCMT 在 ComCat 内的同步止于 2016 |
| EMSC | 欧地中海区域的小震完整性 | 区域目录，震级下限不同 |
第三条要特别小心：区域目录与全球目录的震级下限不同，直接合并会造出「某地区小震突然变多」的假象。这类假象在文献里有个专门的名字，叫报告假象。
§7.5 用对了是什么样子
反面清单容易写，正面清单更有用。一份用对了 ComCat 的研究，通常具备四个特征，且都能在方法部分被验证。
第一，查询参数被完整写出。起止时间、震级下限、是否限定 eventtype、是否只看 reviewed、取数日期——五项缺一项，别人就无法复现。这不是形式主义：同一组参数在不同日期跑，结果能差出百分之几。
第二，震级口径被声明。要么只用一种 magType，要么说明混合口径的处理方式（例如「统一取首选震级，并报告各年代的 magType 构成」）。直接说「M≥6 的事件」而不说震级怎么来的，在跨年代研究里是不可接受的。
第三，检测能力被显式处理。做频次分析时，要么把时间窗截断到 1970 年代之后，要么用 mb 完整度阈值随年代变化的曲线做校正。不做这一步的结论，本质上是在测量台网扩张而不是地壳活动。
第四，快照可复现。要么存了原始返回，要么存了 updateTime 与查询 URL。只存一个 CSV 而不存来源，半年后无法判断那批数字对应哪一版参数。
四条都不难做到，但四条同时做到的研究并不多。差别往往不在能力，在于有没有意识到这份数据是活的。
§8 生态位：目录、波形与震害产品
§8.1 三个层次，三种数据
地震学数据大体分三层，ComCat 站在最上面一层。
第三层 影响与决策 ComCat 的 losspager / shakemap / dyfi 产品
第二层 事件目录 ComCat 的主体：时间、位置、震级、机制
第一层 波形与台站 IRIS/EarthScope SAGE 的 miniSEED 与 StationXML
往上走，数据量小、解释多、更新快；往下走，数据量大、解释少、一旦写入就不再变。ComCat 的所有质量问题的根源都在「它站在解释层」：解释会变，所以它会变。
§8.2 与波形档案的分工
ComCat 回答「发生了什么」，SAGE 回答「地面怎么动的」。做震源反演、做台站响应校正、做机器学习波形分类，必须去 SAGE；做事件筛选、做时间窗划定、做标签生成，先来 ComCat 拿事件列表，再去 SAGE 取对应时窗的波形。
这个组合是地震学机器学习的标准起手式：目录给标签与时间锚点，波形给输入。两者的键不对齐——ComCat 用 eventid，SAGE 用 (network, station, channel, starttime)——所以中间必然有一层「按事件时刻与震中距挑台站」的胶水代码。
§8.3 与库内其他事件目录的类比
本库已有的 ucdp（武装冲突事件，41.8 万条）在结构上与 ComCat 惊人地相似：都是以「事件」为单位、都带地理坐标、都有一组随时间修订的属性、都由多源汇编而成。
| 维度 | ComCat | UCDP |
|---|---|---|
| 事件单元 | 地震 | 有组织暴力冲突 |
| 时间跨度 | 1568 至今 | 1946 至今 |
| 修订机制 | 产品版本化，四元组 | 年度版本重发 |
| 死亡/损失字段 | PAGER 的概率估计 | 直接计数 |
| 地理精度 | 震中一个点 | 村庄级一个点 |
差别在于修订的粒度：UCDP 一年发一版，ComCat 一天改几十次。做两者的联合分析时，时间对齐的概念完全不同——一个是「版本时间」，一个是「事件时间」。
另两个可类比的条目是 world-bank-open-data（国家级统计，与地震的「点」形成尺度互补）和 gbif（物种出现的点位记录，同样面临「采样努力不均」的偏倚）。aqs 则是另一种对照：它也是监测网络产出的连续观测，但观测单元是站点而非事件。
§8.4 它靠什么活着
一个跑了二十多年、每天被全球数千个脚本轮询的服务，为什么没有在预算削减中消失？
第一层是法定职能。ANSS 是美国国会授权的全国地震监测系统，ComCat 是它的对外产出，不是可选产品。
第二层是下游依赖的刚性。海啸预警、ShakeAlert、联邦灾害宣告、再保险触发、全球地震快速响应——这些流程的输入都指向同一个端点。换掉它意味着同时改几十个系统。
第三层是它自己不产生解释负担。ComCat 只做汇总与索引，各目录的解释责任仍归各目录。这个设计让它能容纳互相矛盾的结果而不必裁决——它只需要标出哪个是首选。
三层叠加的结果：它不会因为「不够现代」被替换，只会被增量包裹。
§8.5 与四个相近系统的分工
ComCat 常被与四个系统混为一谈，它们的边界值得单独划清。
| 系统 | 它做什么 | 与 ComCat 的关系 |
|---|---|---|
| ShakeAlert | 秒级地震预警，台站触发即刻推送 | 下游不同：ShakeAlert 服务的是「震动到来前的几秒」，ComCat 服务的是「之后发生了什么」 |
| GCMT | 全球大震的矩心矩张量解 | 上游：GCMT 的解被导入 ComCat 作为 moment-tensor 产品，但在 ComCat 内的同步止于 2016 |
| ISC / ISC-GEM | 全球地震的权威汇编 | 上游：ISC-GEM 构成 ComCat 1900–2010 的骨干部分 |
| EMSC | 欧地中海区域的快速目录 | 平行：覆盖范围重叠但层级不同，EMSC 更偏区域快速响应 |
这张表说明一件容易被忽略的事：ComCat 的「权威性」是借来的。它自己不测定震级，也不自己反演矩张量；它做的是汇总、关联、定首选。理解了这一点，就不会奇怪为什么同一次地震在不同目录里的参数会不一样——ComCat 只是把差异摆在一起，并标出它认为该信哪个。
对跨国研究，这个结构带来一个实用建议：用 ComCat 做事件发现，用原始目录做参数引用。发现某年某地有一次大震，ComCat 最快；要引用震源机制的具体数值，回到 GCMT 的原始文献更稳。
§9 使用指引：三条路径与一份最小实现
§9.1 三种角色，三条路
| 角色 | 路径 | 关键动作 |
|---|---|---|
| 做单次分析 | 网页检索导 CSV | 注意 22 列里 id 在第 12 位 |
| 做实时监控 | 轮询 feed | 用 4.5_month 或 2.5_day，别用 FDSN 轮询 |
| 做批量研究 | FDSN 按窗口切片 | 显式给 starttime、orderby=time-asc、limit |
§9.2 在流水线中的位置
台网观测 → 定位与震级测定 → 事件入库（ComCat 从这里开始）
↓ 触发产品生成
ShakeMap / PAGER / DYFI / 有限断层
↓ 你的取数
事件列表（轻） → 按需取产品（重）
↓
建模 / 触发判定 / 统计
这张图说明一个常见误用：把 ComCat 当作「已经清洗好的训练表」。它不是。它上游是台站，下游才是你的表，中间那一层拍平、去重、震级统一、时间切分，全要自己写。
§9.3 一份最小可跑的取数脚本
下面这段不依赖任何地震学库，只用 requests。它做三件事：按窗口拉事件、按 eventid 去重、把结果拍平成一张表。
#-- 输出一张可直接进 pandas 的扁平表;窗口按年切,避免触发单次上限
import csv
import requests
BASE = "https://earthquake.usgs.gov/fdsnws/event/1/query"
COLS = ["id", "time", "lat", "lon", "depth", "mag", "magType",
"status", "place", "nst", "gap", "rms"]
def pull(start, end, minmag=5.0):
r = requests.get(BASE, params={
"format": "geojson", "starttime": start, "endtime": end,
"minmagnitude": minmag, "eventtype": "earthquake",
"orderby": "time-asc", "limit": 20000}, timeout=180)
r.raise_for_status()
return r.json()["features"]
seen, rows = set(), []
for year in range(2015, 2025):
for f in pull(f"{year}-01-01", f"{year+1}-01-01"):
eid = f["id"]
if eid in seen:
continue
seen.add(eid)
p = f["properties"]
lon, lat, dep = f["geometry"]["coordinates"]
rows.append([eid, p["time"], lat, lon, dep, p["mag"], p["magType"],
p["status"], p["place"], p["nst"], p["gap"], p["rms"]])
with open("comcat_m5.csv", "w", newline="", encoding="utf-8") as fh:
w = csv.writer(fh)
w.writerow(COLS)
w.writerows(rows)
print(len(rows))
三个细节值得注意。第一，eventtype=earthquake 必须显式加，否则爆破会混进来。第二，seen 集合做的是跨窗口去重，因为按年切窗会在边界上产生重叠事件。第三，depth 可能是 None，直接写进 CSV 会变成空串，读回来时会被推断成 NaN——这是好事，但要知道它来自缺失而非零深度。
§9.4 评估时最少要报的四件事
| 要报的 | 为什么 | 怎么报 |
|---|---|---|
| 震级下限与时间窗 | 规模完全由这两个参数决定 | 写明 minmagnitude 与起止日期 |
| 是否含非地震事件 | 爆破会让「地震数」虚高数万 | 写明是否加了 eventtype=earthquake |
| 快照时间 | 同一查询隔月跑结果不同 | 写明确切的取数日期 |
| 是否只用已复核事件 | 自动事件的比例约三分之一 | 写明是否加了 reviewstatus=reviewed |
§9.5 给 Trigger-One 的一条建议
如果只记一件事：把 updateTime 存进账本，而不只是存震级。
理由是震级会被改写，而合同判定的合法性依赖于「当时看到的是什么」。存了 updateTime，半年后的审计可以精确复现「2024 年 1 月 1 日 16 时 10 分，系统依据 us 的 origin 产品第 1710020297040 版，判定 M7.5，触发」。不存，就只能说「系统当时判了 7.5」，无法证明。
§9.6 产品附件里到底有什么
contents 是一个「路径 → URL」的字典。同一个事件下，不同产品的附件形态差别很大，取数前值得先认一遍。
| 产品 | 典型附件 | 用途 |
|---|---|---|
origin |
quakeml.xml、contents.xml |
完整的震源参数与震相到时，机器可读 |
moment-tensor |
quakeml.xml |
矩张量六分量、双力偶解、标量地震矩 |
shakemap |
download/grid.xml、coverage_pgv_high_res.covjson、download/rupture.json、download/info.json |
网格化的地面运动与烈度，是定量风险评估的主输入 |
losspager |
json/cities.json、json/exposures.json、json/alerts.json、onepager.pdf |
城市级影响估计与经济暴露，适合做区域汇总 |
dyfi |
dyfi_geo_1km.geojson、dyfi_geo_10km.geojson、cdi_geo.txt |
公众上报的烈度点，分辨率分一公里与十公里两档 |
finite-fault |
rupture.json 等 |
破裂面的滑动分布 |
三处容易踩的地方。
其一，shakemap 的网格有两套坐标约定。grid.xml 是经纬度规则格网，coverage_*.covjson 是 CoverageJSON 格式，两者的索引顺序不同，混用会把行当列。
其二，losspager 的 exposures.json 是概率不是确定值。它给出的是「在若干损失档位上的概率」，直接取最大值当结论会把分布压成一个点。
其三，dyfi 的烈度点是自愿上报，不是均匀采样。人口稠密区、网络活跃区的点会显著偏多，用它算区域平均烈度会系统性偏高。这个偏倚官方在 DYFI 的说明页里承认过，但产品 JSON 本身不带权重字段。
Trigger-One 只用 losspager 的一个字段：alertlevel。理由很简单——概率分布不适合做布尔判定，而警报级别是官方已经做完的一次降维。这是个典型的取舍：能用官方已经降维的结论，就不要自己重新降维。
§10 AI 使用声明
| 项目 | 内容 |
|---|---|
| 数据性质 | 公开的地球物理观测与解释记录，非个人数据 |
| 建议用途 | 事件检索、时空切片、灾害建模的输入层、事件型数据版本化的工程范例 |
| 不建议用途 | 作为统一震级的连续时间序列、作为地震预测的标签源、直接作为训练表使用 |
| 伦理注意 | 灾损与伤亡字段是概率估计而非事实，公开引用时须标注为估计值 |
| 引用要求 | 引用 2017 年 ANSS 综合目录条目与所使用产品对应的机构文献 |
| 版本锁定 | 服务无数据版本号；复现须记录取数日期与查询参数 |
| 页面状态 | 已发布，最后核对 2026-10-29 |
常见误读
| 常见说法 | 实际情况 | 证据 |
|---|---|---|
| 「ComCat 一共有一千多万条地震」 | 官方不给总数，无约束 count 直接 503 | count?format=text 返回 SQLSTATE 1114 临时表溢出 |
| 「单次最多两万条，所以只能取前两万」 | 两万是 limit 上限，offset 可以更深 |
offset=20,001 返回 200，offset=50,000 返回 503 |
| 「不带参数就是查全库」 | 默认只查最近 30 天 | 接口文档：starttime 默认 NOW-30 days |
| 「目录里全是地震」 | 46 种事件类型，含爆破、爆炸、矿井坍塌、声爆 | 1900 年起采石场爆破七万余条 |
| 「最早的地震是 1615 年那次」 | 最早是 1568 年美国康涅狄格 M4.9 | orderby=time-asc 查询首条 |
| 「震级是测出来的，不会变」 | 自动初判会被复核改写，同一 eventid 可有多个 origin | 能登事件 detail 内 origin 产品 3 个 |
| 「历史地震震级与今天同尺度」 | 1900 年前多为 mint/mfa，由烈度反推 |
magType 字段与 41 种代码清单 |
| 「首选权重可以按官方公式复算」 | 四项之和为 156，实际首选权重 158/218/232 | Noto 事件各产品的 preferredWeight |
| 「62 个目录代码都能用」 | 约一半是测试遗留，如 20、=c、nc73947885 |
/catalogs 与 Catalogs 页人工清单对照 |
| 「数据可用性页可以查当前覆盖」 | 该页停在 2020-10-20，且 ushis 起始年与数据不符 |
页面标题写「as of October 20, 2020」 |
| 「许可写着公有领域，可以随便商用」 | 页面未给 SPDX，且混有 GCMT、ISC-GEM、各国台网记录 | ComCat 各页通读 + Contributors 清单 |
| 「删除的事件不存在了」 | 加 includedeleted 可取，默认返回 409 |
接口文档 includedeleted 参数说明 |
附录 A 参数速查
| 参数 | 取值 | 常用场景 |
|---|---|---|
starttime / endtime |
ISO8601 | 必给，否则默认 30 天 |
minmagnitude / maxmagnitude |
数值 | 控制规模的主要手段 |
eventtype |
46 种 | 排除爆破必给 earthquake |
catalog / contributor |
目录码 / 贡献者码 | 按来源切片 |
reviewstatus |
automatic/reviewed/all |
只要高置信事件时用 reviewed |
producttype |
产品类型名 | 只要带 ShakeMap 的事件 |
alertlevel / minalertlevel |
green 至 red | PAGER 级别过滤 |
minsig / maxsig |
整数 | 显著性阈值 |
minfelt |
整数 | DYFI 上报数下限 |
limit / offset |
1–20000 / ≥1 | 分页 |
orderby |
time/time-asc/magnitude/magnitude-asc |
正序需显式指定 |
includedeleted |
true/false/only | 取已删除事件 |
nodata |
204/404 | 无结果时的返回码 |
format |
geojson/csv/xml/quakeml/kml/text | 默认 quakeml |
附录 B 术语表
| 术语 | 含义 |
|---|---|
| ComCat | ANSS 综合地震目录，本文主角 |
| ANSS | 美国全国地震台网系统，ComCat 的上级计划 |
| NEIC | 国家地震信息中心，USGS 内部执行全球目录的机构 |
| FDSN | 国际地震数字台网联合会，其 Web Service 规范被多数数据中心采用 |
| QuakeML | 地震学领域的 XML 交换格式 |
| origin | 震源参数产品：时间、位置、深度及其误差 |
| 矩张量 | 描述震源破裂机制的数学表示，含双力偶分量 |
| ShakeMap | 震动图产品，给出地面运动与烈度的空间分布 |
| PAGER | 地震影响快速评估系统，输出经济损失与伤亡概率 |
| DYFI | 「Did You Feel It」，公众烈度上报的汇总产品 |
| 首选权重 | 同类产品中决定谁被标为首选的合成分值 |
| 报告假象 | 因监测能力变化而非真实活动变化造成的频次起伏 |
| 检测能力 | 某时期某区域能测到的最小震级，随时间与台网密度变化 |
附录 C 引用与许可
引用建议同时给出数据发布条目与所使用产品的机构文献：
- U.S. Geological Survey, 2017, Advanced National Seismic System (ANSS) Comprehensive Catalog of Earthquake Events and Products（References 页所列）
- Guy, M., Patton, J., Fee, J., et al., 2015, National Earthquake Information Center systems overview and integration: USGS Open-File Report 2015–1120, 25 p.
- Flinn, E.A., Engdahl, E.R., Hill, A.R., 1974, Seismic and geographical regionalization: BSSA, v. 64, p. 771–993.
许可方面有三点需要分清。ComCat 的页面与服务文档都没有给出 SPDX 标识，页脚只指向 usgs.gov 的政策页，该页在本次核对时无法访问，因此这里不写具体条款名。目录内混有 GCMT（拉蒙特-多尔蒂地球观测所）、ISC-GEM 以及各国区域台网的记录，这些上游目录的条款由各自声明，ComCat 未做统一。产品的 PDF 与图片附件可能另有版权声明，取用前应逐个查看。
编辑说明
核验时间 2026-10-29。方法：直接调用 FDSN Event Web Service 的 count、query、catalogs、contributors、application.json、version 六个端点取数；读取 ComCat 的 Overview、Access Data、Data Availability、Products、Catalogs、Contributors、References 七个页面；读取接口文档页的完整参数表；解析一个真实大震事件（us6000m0xl）的 detail GeoJSON 全文，逐项核对产品结构、首选权重与附件数量。所有计数均为当日返回值，会随目录增长变化。
未覆盖的部分：未下载任何产品附件本体，因此 ShakeMap 栅格、PAGER 报告、DYFI 原始上报的实际内容与体积未核；未做逐事件的产品覆盖率统计；未与 ISC、EMSC 做逐条比对，因此「ComCat 相对其他目录的完整性」只有定性判断。usgs.gov 域在本环境返回 403（CloudFront 拦截）与 405，政策页原文未读到，许可部分按「官方未给 SPDX」记录，未替官方补写条款。
与候选调研底稿不符处，已在正文中更正，主要有五处：其一，底稿称「全目录总量超出 API 单次 20,000 上限，无法 count」，实际 20,000 是 limit 上限，count 失败的原因是服务端临时表溢出（503），两者是不同机制；其二，底稿称最早为 1615 年多米尼加事件，实际最早为 1568 年美国康涅狄格事件，1615 年那条确实存在但排在其后；其三，底稿的 107,558 与 296,992 两个计数已随目录增长变为 107,560 与 296,997；其四，底稿未提及 1900 年以来 M≥6/7/8 的口径，也未提及非地震事件占比；其五，底稿称「许可：公有领域」，实际页面无任何许可声明，且目录含多机构贡献记录，不能以 USGS 单一身份概括。
相关数据集导航
以下为站内 AI-Ready 数据集百科中与本词条共享多个主题标签的相关数据集，按相关度降序排列：
- wpp — 共享标签：公共卫生与流行病学 / 全球健康 / 时序数据 / 公共卫生统计
- mswep-v3 — 共享标签：公共卫生与流行病学 / 全球健康 / 时序数据 / 公共卫生统计
- who-gho — 共享标签：公共卫生与流行病学 / 全球健康 / 时序数据 / 公共卫生统计
- our-world-in-data — 共享标签：公共卫生与流行病学 / 全球健康 / 时序数据
- human-mortality-database — 共享标签：公共卫生与流行病学 / 全球健康 / 公共卫生统计
- ghcn-daily — 共享标签：公共卫生与流行病学 / 全球健康 / 时序数据
- cmip6-esgf — 共享标签：公共卫生与流行病学 / 全球健康 / 时序数据
- hfa-europe — 共享标签：公共卫生与流行病学 / 时序数据 / 公共卫生统计
- ghdx — 共享标签：公共卫生与流行病学 / 全球健康 / 公共卫生统计
- gbd-results — 共享标签：公共卫生与流行病学 / 全球健康 / 公共卫生统计
导航说明：本章节由全站统一标签体系自动计算生成（标签重合度算法），双向可达；点击链接可跳转至对应数据集词条。
