Skip to content
ZGI Services

Earthquakes

Earthquake events from the USGS catalog in a time window of at most 31 days, optionally filtered by minimum magnitude and a circle around a point, with time, magnitude, place, coordinates, depth and tsunami flag (up to 200 events per call).
Endpoint POST /v1/earthquake-queries
Scope earthquake:query
MCP tool earthquake
Usage units events

Usage units appear in execution.usage.units for reconciliation and billing.

Request fields

Section titled “Request fields”
Field Type Required Description
invocation_id string yes The market’s invocation id: one execution per id and operation, so a retry with the same id is rejected instead of charged twice. 1-128 characters of A-Z a-z 0-9 . _ : -.
provider string yes Provider that serves the request; choose by the coverage described for this tool. One of: usgs
end_time string yes Window end, RFC 3339 timestamp after start_time and at most 31 days later.
start_time string yes Window start, RFC 3339 timestamp such as 2024-01-01T00:00:00Z; must not be in the future.
latitude number no Optional circle center latitude, -90 to 90; latitude, longitude and radius_km must be set together.
longitude number no Optional circle center longitude, -180 to 180; latitude, longitude and radius_km must be set together.
max_results integer no Number of events to return, 1-200; default 50.
min_magnitude number no Optional minimum magnitude, -1 to 10.
radius_km number no Optional circle radius in kilometers, above 0 and at most 20001.6; latitude, longitude and radius_km must be set together.

Providers

Section titled “Providers”
Provider Region Source Limits
usgs US USGS earthquake catalog max_results: 200, max_window_days: 31, timeout_seconds: 30

Example

Section titled “Example”
终端窗口
curl -sS https://services.zgi.im/v1/earthquake-queries \
  -H "Authorization: Bearer $ZGI_SERVICES_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"invocation_id": "docs-1791778521-earthquake", "provider": "usgs", "start_time": "2026-10-01T00:00:00Z", "end_time": "2026-10-10T00:00:00Z", "min_magnitude": 5, "max_results": 2}'

Response

Section titled “Response”

A real response, with lists cut to two items and long text shortened.

{
  "code": 0,
  "message": "success",
  "data": {
    "execution": {
      "id": "exe_01a12e529e7b7e20b4a720035d89ea42",
      "invocation_id": "docs-1791778521-earthquake",
      "capability": "earthquake",
      "operation": "earthquake.query",
      "provider": "usgs",
      "outcome": "succeeded",
      "error_category": null,
      "error_code": null,
      "usage": {
        "provider_requests": 1,
        "units": [
          {
            "name": "events",
            "value": 2,
            "source": "measured"
          }
        ]
      },
      "upstream_ref": null,
      "request_id": "req_7278bd84a77ced9d025064b3",
      "started_at": "2026-10-12T04:15:28.891923377Z",
      "finished_at": "2026-10-12T04:15:28.988018613Z",
      "duration_ms": 96
    },
    "result": {
      "events": [
        {
          "id": "us6000u1ay",
          "time": "2026-10-09T23:12:37.79Z",
          "magnitude": 5.4,
          "magnitude_type": "mb",
          "place": "9 km SSE of Los Asientos, Panama",
          "latitude": 7.4366,
          "longitude": -80.0968,
          "depth_km": 10,
          "tsunami_flag": false,
          "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us6000u1ay"
        },
        {
          "id": "us6000u1ax",
          "time": "2026-10-09T23:10:02.875Z",
          "magnitude": 5,
          "magnitude_type": "mb",
          "place": "8 km ESE of La Tronosa, Panama",
          "latitude": 7.3962,
          "longitude": -80.5284,
          "depth_km": 10,
          "tsunami_flag": false,
          "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us6000u1ax"
        }
      ],
      "source": {
        "name": "USGS Earthquake Hazards Program",
        "license": "US public domain",
        "url": "https://earthquake.usgs.gov"
      }
    }
  }
}