query_external_catalog¶

Science¶

Entries from the session's frozen USGS and EMSC bulletin snapshot, near a time window (at most 7 days) and an area (circle or bounding box). The caller may restrict sources and a minimum magnitude. Live feeds are a later level; this tool never leaves the snapshot pinned at session mint.

snapshot_stale warns when the snapshot predates the window's end by more than 30 days. Presence of a published event near the origin is strong positive context. Absence is weak: international agencies have their own magnitude and region thresholds, usually above a small local catalogue.

Returned magnitudes and event types are the agency's, not a recompute.

References¶

U.S. Geological Survey. ANSS Comprehensive Earthquake Catalog (ComCat). https://earthquake.usgs.gov/data/comcat/
European-Mediterranean Seismological Centre. https://www.emsc-csem.org/

Contract¶

Generated from the live registry (ToolSpec). Field names, types and defaults come from the input and payload models; they are not hand-typed.


Group	`external`
Class	2
Tool version	`1.0.0`
Highest declared tier	F
Timeout	5 s
Budget key	`none`
`readOnlyHint`	true
`idempotentHint`	true

Input¶

Field	Type	Required	Notes
`t_from_utc`	string	yes
`t_to_utc`	string	yes
`area`	object (kind `bbox` \| `circle`)	yes	discriminated on `kind`
`min_magnitude`	number \| null	no	default `null`
`sources`	array[string ∈ {`usgs`, `emsc`}] \| null	no	default `null`

Payload¶

Field	Type	Required
`events`	array[object]	yes
`events[].source`	string	yes
`events[].source_event_id`	string	yes
`events[].origin_time_utc`	string	yes
`events[].latitude_deg`	number	yes
`events[].longitude_deg`	number	yes
`events[].depth_km`	number \| null	yes
`events[].magnitude`	number \| null	yes
`events[].magnitude_type`	string \| null	yes
`events[].event_type`	string \| null	yes
`events[].agency`	string \| null	yes
`snapshot_id`	string	yes
`snapshot_taken_utc`	string	yes
`sources_included`	array[string]	yes

Example request¶

{
  "t_from_utc": "2024-06-14T00:00:00.000Z",
  "t_to_utc": "2024-06-15T23:59:59.000Z",
  "area": {
    "kind": "circle",
    "center": {
      "kind": "catalog",
      "event_id": 1001
    },
    "radius_km": 100
  },
  "min_magnitude": 2.0,
  "sources": [
    "usgs",
    "emsc"
  ]
}

Example payload¶

{
  "events": [
    {
      "source": "emsc",
      "source_event_id": "20240615_0000123",
      "origin_time_utc": "2024-06-15T08:11:58.000Z",
      "latitude_deg": 47.2,
      "longitude_deg": 24.4,
      "depth_km": 8.0,
      "magnitude": 2.6,
      "magnitude_type": "ml",
      "event_type": null,
      "agency": "EXAMPLE"
    }
  ],
  "snapshot_id": "usgs-emsc-2024-06-01",
  "snapshot_taken_utc": "2024-06-16T03:00:00.000Z",
  "sources_included": [
    "usgs",
    "emsc"
  ]
}

What this tool does not tell you¶

What this tool does not tell you: that absence means false. EMSC has its own thresholds, typically above those of a dense local network for small events. Presence is strong positive evidence; absence is weak.

Warnings named for this tool¶

Code	When
`snapshot_stale`	the bulletin snapshot predates the window's end by more than 30 days