earthquake-mcp-server

Fetch a USGS pre-computed real-time earthquake feed by magnitude tier and time window. These feeds are CDN-cached by USGS and faster and more available than the query API — use them for "what's happening now" queries. "all" includes microseisms (M<1); "significant" is a USGS curation based on magnitude, felt reports, and PAGER impact estimates. "hour" returns 0–10 events typically; "month" can exceed 10,000 for the "all" tier, so results are returned a page at a time: count is the page size, totalCount the whole feed, and nextCursor the input for the following page. Each page returns limit events (default 15, at most 1,000), fewer only on the last page. The cursor is opaque and must be passed back verbatim — unlike earthquake_search_events, these feeds retain the first-read generation for up to 15 minutes, subject to capacity eviction and restart. An expired cursor requires a fresh first read. For historical or filtered queries, use earthquake_search_events instead.

{
  "type": "object",
  "properties": {
    "magnitude_tier": {
      "default": "2.5",
      "description": "Minimum magnitude threshold for the feed. \"all\" includes microseisms (M<1). \"1.0\" is M1.0+. \"2.5\" is M2.5+. \"4.5\" is M4.5+. \"significant\" is a USGS curated selection based on magnitude, felt reports, and PAGER impact estimates — not purely magnitude-based.",
      "type": "string",
      "enum": [
        "all",
        "1.0",
        "2.5",
        "4.5",
        "significant"
      ]
    },
    "time_window": {
      "default": "day",
      "description": "Time window for the feed. \"hour\" typically returns 0–10 events; \"month\" can exceed 10,000 for the \"all\" tier. Prefer \"hour\" or \"day\" for real-time status checks.",
      "type": "string",
      "enum": [
        "hour",
        "day",
        "week",
        "month"
      ]
    },
    "limit": {
      "description": "Events to return per page. Default 15; a larger value returns at most 1,000 and says so. Applies to the first page; later pages carry the page size inside the cursor and ignore limit, so set it on the first call.",
      "type": "number",
      "minimum": 1,
      "multipleOf": 1
    },
    "cursor": {
      "description": "Opaque token for the next page, taken verbatim from a previous call's nextCursor. Omit for the first page. Do not construct, parse, or edit it — it encodes a position in the feed snapshot and is rejected if malformed.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "count": {
      "type": "number",
      "description": "Number of events returned in this page, not the whole feed."
    },
    "generated_at": {
      "type": "string",
      "description": "ISO 8601 UTC timestamp when this feed was generated by USGS."
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "USGS or EMSC event identifier."
          },
          "title": {
            "type": "string",
            "description": "Event summary, e.g. \"M 6.0 - Hawaii\"."
          },
          "magnitude": {
            "description": "Preferred magnitude; null if not computed (title: \"M ?\").",
            "type": [
              "number",
              "null"
            ]
          },
          "magnitude_type": {
            "type": "string",
            "description": "Magnitude type (ml, mww, mw, mb, etc.)."
          },
          "time": {
            "type": "string",
            "description": "ISO 8601 UTC origin time."
          },
          "updated": {
            "type": "string",
            "description": "ISO 8601 UTC time this record was last updated."
          },
          "place": {
            "type": "string",
            "description": "Nearest named location."
          },
          "latitude": {
            "type": "number",
            "description": "Epicenter latitude in decimal degrees."
          },
          "longitude": {
            "type": "number",
            "description": "Epicenter longitude in decimal degrees."
          },
          "depth_km": {
            "description": "Hypocenter depth in km; null if unmeasured.",
            "type": [
              "number",
              "null"
            ]
          },
          "felt": {
            "description": "DYFI (Did You Feel It?) response count; null if no USGS reports or source has no DYFI (EMSC). Null does not mean unfelt.",
            "type": [
              "number",
              "null"
            ]
          },
          "cdi": {
            "description": "Maximum DYFI Community Decimal Intensity (0–12); null if uncomputed or unsupported (EMSC).",
            "type": [
              "number",
              "null"
            ]
          },
          "mmi": {
            "description": "Maximum ShakeMap Modified Mercalli intensity (0–12); null without a ShakeMap or for EMSC.",
            "type": [
              "number",
              "null"
            ]
          },
          "alert": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "green",
                  "yellow",
                  "orange",
                  "red"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "PAGER estimated impact; null without an assessment or for EMSC."
          },
          "tsunami": {
            "description": "USGS tsunami flag: 1 for large oceanic events, 0 otherwise; null if unpublished (EMSC). Not a warning or evidence of a tsunami; check NOAA tsunami.gov for alerts.",
            "type": [
              "number",
              "null"
            ]
          },
          "significance": {
            "description": "USGS significance (0–2000+), combining magnitude, felt reports and PAGER; null if uncomputed or for EMSC.",
            "type": [
              "number",
              "null"
            ]
          },
          "status": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "automatic",
                  "reviewed",
                  "deleted"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Review state: automatic (unverified), reviewed (analyst checked), or deleted. Null if unpublished (EMSC); such solutions remain unverified and subject to revision."
          },
          "source_catalog": {
            "description": "Solution catalog, e.g. EMSC-RTS (real-time, subject to revision). Absent for USGS.",
            "type": "string"
          },
          "auth": {
            "description": "Authoritative agency/network code (EMSC auth or USGS net); absent if unpublished.",
            "type": "string"
          },
          "event_type": {
            "description": "QuakeML classification (earthquake, quarry blast, explosion, etc.). EMSC codes decode to USGS names; unknown codes pass through verbatim. Certainty is separate. Absent if unpublished; either catalog includes non-tectonic events.",
            "type": "string"
          },
          "event_certainty": {
            "description": "EMSC classification certainty: known (asserted), suspected, unknown, or unreported. Suspected is not confirmed. Absent for USGS and unrecognized EMSC codes.",
            "type": "string",
            "enum": [
              "known",
              "suspected",
              "unknown",
              "unreported"
            ]
          },
          "event_url": {
            "description": "USGS event page URL. Present for USGS events only.",
            "type": "string"
          },
          "detail_url": {
            "description": "URL to fetch the full GeoJSON detail record. Present in USGS list responses.",
            "type": "string"
          },
          "associated_ids": {
            "description": "Other network IDs USGS lists for this event, in upstream order; earthquake_get_event accepts them. Absent when USGS lists none, and for EMSC events.",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "title",
          "magnitude",
          "magnitude_type",
          "time",
          "updated",
          "place",
          "latitude",
          "longitude",
          "depth_km",
          "felt",
          "cdi",
          "mmi",
          "alert",
          "tsunami",
          "significance",
          "status"
        ],
        "additionalProperties": false,
        "description": "A single earthquake event."
      },
      "description": "Earthquake events for this page, newest first."
    },
    "feed_url": {
      "type": "string",
      "description": "Source feed URL."
    },
    "totalCount": {
      "description": "Number of events in the whole feed, across every page.",
      "type": "number"
    },
    "truncated": {
      "description": "True when the feed holds more events than this page returned. nextCursor carries the input for the following page.",
      "type": "boolean"
    },
    "nextCursor": {
      "description": "Opaque token to pass back as the cursor input for the next page. Present only when more events remain; absent means this was the last page.",
      "type": "string"
    },
    "notice": {
      "description": "Guidance when a first-page limit was clamped to 1,000 (requested and applied values), when the feed or cursor position holds no events (a wider window, lower tier, or earthquake_search_events), or when more pages remain (paging with the cursor). Absent when none applies.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_cursor`: The feed cursor is malformed. `cursor_expired`: The retained generation expired, was evicted, or does not belong to this tenant and feed. `snapshot_too_large`: The feed exceeds retained storage capacity. `feed_unavailable`: USGS feed endpoint returns a 5xx, HTML, or is unreachable. `feed_timeout`: USGS feed endpoint did not answer before the request deadline. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_cursor",
                "cursor_expired",
                "snapshot_too_large",
                "feed_unavailable",
                "feed_timeout"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "count",
        "generated_at",
        "events",
        "feed_url"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Search USGS or independent global EMSC seismic catalogs by time, magnitude, depth, area and source-specific filters. Both include non-tectonic events; event_type="earthquake" excludes them on USGS. Circle and independently optional box edges intersect. Unsupported EMSC filters appear in ignoredFilters. Size queries with earthquake_count_events. Returns limit events per call (at most 1,000), fewer only on the last page. Continue with offset=nextOffset and unchanged filters/order. totalCount is the full match total when known; countUnavailable marks a failed count lookup, so the total is unknown. Paging can retrieve matches beyond 20,000.

{
  "type": "object",
  "properties": {
    "start_time": {
      "description": "Start of time range as ISO 8601 (e.g. \"2026-01-01\" or \"2026-05-23T00:00:00\"). A bare year expands to January 1st and an unpadded month or day is zero-padded, with date-only values resolved to midnight (T00:00:00) on both sources. Explicit time and timezone suffixes are preserved. Defaults to 30 days before end_time (or before the current time) if omitted — applied server-side so USGS and EMSC honor the same window.",
      "type": "string",
      "pattern": "^\\d{4}(-\\d{1,2}(-\\d{1,2})?)?([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "end_time": {
      "description": "End of time range as ISO 8601, in the same forms start_time accepts. Date-only values mean midnight at the start of the named day, not the whole day. Defaults to current time if omitted.",
      "type": "string",
      "pattern": "^\\d{4}(-\\d{1,2}(-\\d{1,2})?)?([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "min_magnitude": {
      "description": "Minimum magnitude (Richter or equivalent). M2.5+ is felt by some people; M5+ can cause damage; M7+ is major.",
      "type": "number",
      "minimum": -1,
      "maximum": 10
    },
    "max_magnitude": {
      "description": "Maximum magnitude.",
      "type": "number",
      "minimum": -1,
      "maximum": 10
    },
    "latitude": {
      "description": "Latitude for radius search. Requires longitude and radius_km.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "description": "Longitude for radius search. Requires latitude and radius_km.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "radius_km": {
      "description": "Search radius in kilometers from the lat/lon point. 100 km covers a metro region; 500 km covers a large country. Max 20001.6, the ceiling USGS enforces. Converted to degrees for EMSC (1° ≈ 111.2 km).",
      "type": "number",
      "minimum": 0,
      "maximum": 20001.6
    },
    "min_latitude": {
      "description": "Southern edge of a bounding-box search, in degrees. Independent of the other three box parameters — supply any of them. Must not exceed max_latitude when both are given.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "max_latitude": {
      "description": "Northern edge of a bounding-box search, in degrees.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "min_longitude": {
      "description": "Western edge of a bounding-box search, in degrees. Range extends beyond ±180 so a box can cross the antimeridian (e.g. min_longitude=170, max_longitude=190) — always keep min_longitude at or below max_longitude rather than inverting the pair.",
      "type": "number",
      "minimum": -360,
      "maximum": 360
    },
    "max_longitude": {
      "description": "Eastern edge of a bounding-box search, in degrees.",
      "type": "number",
      "minimum": -360,
      "maximum": 360
    },
    "min_depth_km": {
      "description": "Minimum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope. Shallow quakes (0–70 km) typically cause more surface damage than deep quakes (>300 km).",
      "type": "number",
      "minimum": -100,
      "maximum": 1000
    },
    "max_depth_km": {
      "description": "Maximum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope.",
      "type": "number",
      "minimum": -100,
      "maximum": 1000
    },
    "alert_level": {
      "description": "Minimum PAGER alert level. PAGER estimates economic loss and casualties. \"green\" = minimal impact; \"red\" = extreme. Only available from USGS.",
      "type": "string",
      "enum": [
        "green",
        "yellow",
        "orange",
        "red"
      ]
    },
    "min_felt": {
      "description": "Minimum number of DYFI (Did You Feel It?) reports. Use to find events with confirmed public impact. Only available from USGS.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "min_significance": {
      "description": "Minimum USGS significance score (0–2000+). Combines magnitude, felt reports, and PAGER estimates. Significant events typically score 600+. Only available from USGS.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "event_type": {
      "description": "Filter by upstream event classification, e.g. \"earthquake\" to exclude quarry blasts and explosions, or \"quarry blast\" to see only those. Matched verbatim against the USGS catalog, which accepts any string and returns zero matches for an unrecognized one. Only available from USGS.",
      "type": "string",
      "minLength": 1
    },
    "magnitude_type": {
      "description": "Magnitude type, e.g. \"mb\" or \"mww\"; both sources. Blank means omitted.",
      "type": "string"
    },
    "product_type": {
      "description": "Required product type, e.g. \"moment-tensor\"; USGS only. Blank means omitted.",
      "type": "string"
    },
    "review_status": {
      "description": "USGS review status: automatic or reviewed. Blank means omitted; unsupported by EMSC.",
      "type": "string"
    },
    "source": {
      "default": "usgs",
      "description": "USGS includes PAGER, DYFI and ShakeMap; EMSC (European-Mediterranean Seismological Centre) is an independent global catalog, with densest station coverage around Europe/Mediterranean and no such impact products. earthquake_get_event accepts IDs from either source.",
      "type": "string",
      "enum": [
        "usgs",
        "emsc"
      ]
    },
    "limit": {
      "description": "Events to return per call. Default 15; a larger value returns at most 1,000 and says so. Combine with offset to retrieve match sets larger than one call can return.",
      "type": "number",
      "minimum": 1,
      "multipleOf": 1
    },
    "offset": {
      "description": "Index of the first event to return, counting from 1 — offset=1 is the first match (both upstream APIs reject 0). Omit for the first page, then pass the nextOffset value from a capped result to fetch the next one. Ordering is set by order_by, so keep order_by, limit, and every filter identical across pages.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "order_by": {
      "default": "time",
      "description": "Sort order. \"time\" returns newest first; \"magnitude\" returns largest first.",
      "type": "string",
      "enum": [
        "time",
        "time-asc",
        "magnitude",
        "magnitude-asc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "count": {
      "type": "number",
      "description": "Number of events returned."
    },
    "source": {
      "type": "string",
      "enum": [
        "usgs",
        "emsc"
      ],
      "description": "Data source used."
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "USGS or EMSC event identifier."
          },
          "title": {
            "type": "string",
            "description": "Event summary, e.g. \"M 6.0 - Hawaii\"."
          },
          "magnitude": {
            "description": "Preferred magnitude; null if not computed (title: \"M ?\").",
            "type": [
              "number",
              "null"
            ]
          },
          "magnitude_type": {
            "type": "string",
            "description": "Magnitude type (ml, mww, mw, mb, etc.)."
          },
          "time": {
            "type": "string",
            "description": "ISO 8601 UTC origin time."
          },
          "updated": {
            "type": "string",
            "description": "ISO 8601 UTC time this record was last updated."
          },
          "place": {
            "type": "string",
            "description": "Nearest named location."
          },
          "latitude": {
            "type": "number",
            "description": "Epicenter latitude in decimal degrees."
          },
          "longitude": {
            "type": "number",
            "description": "Epicenter longitude in decimal degrees."
          },
          "depth_km": {
            "description": "Hypocenter depth in km; null if unmeasured.",
            "type": [
              "number",
              "null"
            ]
          },
          "felt": {
            "description": "DYFI (Did You Feel It?) response count; null if no USGS reports or source has no DYFI (EMSC). Null does not mean unfelt.",
            "type": [
              "number",
              "null"
            ]
          },
          "cdi": {
            "description": "Maximum DYFI Community Decimal Intensity (0–12); null if uncomputed or unsupported (EMSC).",
            "type": [
              "number",
              "null"
            ]
          },
          "mmi": {
            "description": "Maximum ShakeMap Modified Mercalli intensity (0–12); null without a ShakeMap or for EMSC.",
            "type": [
              "number",
              "null"
            ]
          },
          "alert": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "green",
                  "yellow",
                  "orange",
                  "red"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "PAGER estimated impact; null without an assessment or for EMSC."
          },
          "tsunami": {
            "description": "USGS tsunami flag: 1 for large oceanic events, 0 otherwise; null if unpublished (EMSC). Not a warning or evidence of a tsunami; check NOAA tsunami.gov for alerts.",
            "type": [
              "number",
              "null"
            ]
          },
          "significance": {
            "description": "USGS significance (0–2000+), combining magnitude, felt reports and PAGER; null if uncomputed or for EMSC.",
            "type": [
              "number",
              "null"
            ]
          },
          "status": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "automatic",
                  "reviewed",
                  "deleted"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Review state: automatic (unverified), reviewed (analyst checked), or deleted. Null if unpublished (EMSC); such solutions remain unverified and subject to revision."
          },
          "source_catalog": {
            "description": "Solution catalog, e.g. EMSC-RTS (real-time, subject to revision). Absent for USGS.",
            "type": "string"
          },
          "auth": {
            "description": "Authoritative agency/network code (EMSC auth or USGS net); absent if unpublished.",
            "type": "string"
          },
          "event_type": {
            "description": "QuakeML classification (earthquake, quarry blast, explosion, etc.). EMSC codes decode to USGS names; unknown codes pass through verbatim. Certainty is separate. Absent if unpublished; either catalog includes non-tectonic events.",
            "type": "string"
          },
          "event_certainty": {
            "description": "EMSC classification certainty: known (asserted), suspected, unknown, or unreported. Suspected is not confirmed. Absent for USGS and unrecognized EMSC codes.",
            "type": "string",
            "enum": [
              "known",
              "suspected",
              "unknown",
              "unreported"
            ]
          },
          "event_url": {
            "description": "USGS event page URL. Present for USGS events only.",
            "type": "string"
          },
          "detail_url": {
            "description": "URL to fetch the full GeoJSON detail record. Present in USGS list responses.",
            "type": "string"
          },
          "associated_ids": {
            "description": "Other network IDs USGS lists for this event, in upstream order; earthquake_get_event accepts them. Absent when USGS lists none, and for EMSC events.",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "title",
          "magnitude",
          "magnitude_type",
          "time",
          "updated",
          "place",
          "latitude",
          "longitude",
          "depth_km",
          "felt",
          "cdi",
          "mmi",
          "alert",
          "tsunami",
          "significance",
          "status"
        ],
        "additionalProperties": false,
        "description": "A single earthquake event."
      },
      "description": "Matching earthquake events."
    },
    "totalCount": {
      "description": "Full match total, inferred from a nonempty short upstream page (or empty first page), otherwise counted for full pages. Absent for empty later pages or failed counts; countUnavailable marks failures.",
      "type": "number"
    },
    "countUnavailable": {
      "description": "True if the count lookup failed; events are unaffected, totalCount unknown. Retry earthquake_count_events with identical filters. Absent if count succeeded or was unnecessary.",
      "type": "boolean"
    },
    "truncated": {
      "description": "Page filled the applied limit and more matches remain or may remain. Continue with nextOffset. Without totalCount, more events may remain but are not confirmed.",
      "type": "boolean"
    },
    "nextOffset": {
      "description": "Next 1-based offset; keep other inputs unchanged. Present if more events remain or may remain with unknown total; absent on last page.",
      "type": "number"
    },
    "notice": {
      "description": "Guidance when limit was clamped to 1,000 (requested and applied values), when results are empty (how to broaden filters), or when more pages remain (the next offset). Absent when none applies.",
      "type": "string"
    },
    "ignoredFilters": {
      "description": "USGS-only filters supplied in the input but not sent upstream because source=emsc does not support them. The result set is NOT constrained by these — re-run with source=usgs to apply them. Absent when every supplied filter was applied.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "Name of an input filter that was not applied."
      }
    },
    "queryEcho": {
      "description": "Echo of the effective parameters sent to the upstream API, including server-resolved defaults. Use to diagnose unexpected or empty results — a filter absent here was not sent upstream.",
      "type": "object",
      "properties": {
        "start_time": {
          "description": "Applied start time; defaults to 30 days before end/now.",
          "type": "string"
        },
        "end_time": {
          "description": "Applied end time; absent means upstream current-time default.",
          "type": "string"
        },
        "min_magnitude": {
          "description": "Applied minimum magnitude.",
          "type": "number"
        },
        "max_magnitude": {
          "description": "Applied maximum magnitude.",
          "type": "number"
        },
        "latitude": {
          "description": "Circle latitude, degrees.",
          "type": "number"
        },
        "longitude": {
          "description": "Circle longitude, degrees.",
          "type": "number"
        },
        "radius_km": {
          "description": "Search radius in km sent upstream (converted to degrees for EMSC).",
          "type": "number"
        },
        "min_latitude": {
          "description": "Southern bounding-box edge sent upstream, in degrees.",
          "type": "number"
        },
        "max_latitude": {
          "description": "Northern bounding-box edge sent upstream, in degrees.",
          "type": "number"
        },
        "min_longitude": {
          "description": "Western bounding-box edge sent upstream, in degrees.",
          "type": "number"
        },
        "max_longitude": {
          "description": "Eastern bounding-box edge sent upstream, in degrees.",
          "type": "number"
        },
        "min_depth_km": {
          "description": "Applied minimum depth, km.",
          "type": "number"
        },
        "max_depth_km": {
          "description": "Applied maximum depth, km.",
          "type": "number"
        },
        "alert_level": {
          "description": "Applied minimum PAGER alert; absent for EMSC.",
          "type": "string"
        },
        "min_felt": {
          "description": "Applied minimum DYFI response count; absent for EMSC.",
          "type": "number"
        },
        "min_significance": {
          "description": "Applied minimum significance; absent for EMSC.",
          "type": "number"
        },
        "event_type": {
          "description": "Applied event type; absent for EMSC.",
          "type": "string"
        },
        "magnitude_type": {
          "description": "Applied magnitude type.",
          "type": "string"
        },
        "product_type": {
          "description": "Applied required product; USGS only.",
          "type": "string"
        },
        "review_status": {
          "description": "Applied review status; USGS only.",
          "type": "string",
          "enum": [
            "automatic",
            "reviewed"
          ]
        },
        "source": {
          "type": "string",
          "enum": [
            "usgs",
            "emsc"
          ],
          "description": "Data source queried."
        },
        "limit": {
          "type": "number",
          "description": "Applied result limit sent upstream, after any clamp."
        },
        "offset": {
          "description": "1-based paging offset sent upstream. Absent when the first page was fetched.",
          "type": "number"
        },
        "order_by": {
          "type": "string",
          "description": "Sort order sent upstream."
        }
      },
      "required": [
        "source",
        "limit",
        "order_by"
      ],
      "additionalProperties": false
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_range`: Minimum magnitude or depth exceeds its maximum, or start_time is after end_time. `invalid_radius`: latitude or longitude provided without radius_km, or vice versa. `invalid_bounding_box`: min_latitude exceeds max_latitude, or min_longitude exceeds max_longitude. `source_unavailable`: Selected source API returns a 5xx or is unreachable. `source_timeout`: Selected source API did not answer before the request deadline. `upstream_rejected`: The source API rejected the query parameters and explained why in its response body. `upstream_rejected_no_reason`: The source API rejected the query but its response body carried no usable explanation. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_range",
                "invalid_radius",
                "invalid_bounding_box",
                "source_unavailable",
                "source_timeout",
                "upstream_rejected",
                "upstream_rejected_no_reason"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "count",
        "source",
        "events"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch one earthquake by event ID: a USGS ID, or an EMSC ID (an origin date and seven-digit sequence, e.g. "20190706_0000043"). Returns the same normalized event a search result carries. For a USGS event it adds a projection of the analysis products only the single-event response holds: PAGER impact alert and report link, ShakeMap peak intensity and ground motion, DYFI felt-report totals, the moment-tensor focal mechanism, landslide and liquefaction alerts, origin quality (azimuthal gap, station count, location uncertainty, depth type), and finite-fault rupture dimensions. Product groups are omitted when no projected field is available — a small automatic event typically carries only origin quality, while a large reviewed one has most of it. Opt into more with include: alternative origin solutions, magnitude solutions, phase arrivals, or the USGS aftershock forecast; a requested group that is not returned is listed in unavailable_includes. EMSC publishes none of these products, so an EMSC event has no detail and lists every requested group as not_published. Event IDs appear in the "id" field of earthquake_get_feed and earthquake_search_events results; a USGS event's associated_ids are also accepted.

{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string",
      "minLength": 1,
      "description": "USGS event ID, e.g. \"hv74966427\" or \"us6000sznj\", or EMSC event ID, e.g. \"20190706_0000043\". Found in the \"id\" field of earthquake_get_feed and earthquake_search_events results."
    },
    "include": {
      "description": "Optional groups: origins (every contributed origin solution, no extra request), magnitudes and arrivals (one shared phase-data download; every arrival of the preferred origin, nearest first), aftershock_forecast (one extra request). Omit for the default response.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "origins",
          "magnitudes",
          "arrivals",
          "aftershock_forecast"
        ]
      }
    }
  },
  "required": [
    "event_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "event": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "USGS or EMSC event identifier."
        },
        "title": {
          "type": "string",
          "description": "Event summary, e.g. \"M 6.0 - Hawaii\"."
        },
        "magnitude": {
          "description": "Preferred magnitude; null if not computed (title: \"M ?\").",
          "type": [
            "number",
            "null"
          ]
        },
        "magnitude_type": {
          "type": "string",
          "description": "Magnitude type (ml, mww, mw, mb, etc.)."
        },
        "time": {
          "type": "string",
          "description": "ISO 8601 UTC origin time."
        },
        "updated": {
          "type": "string",
          "description": "ISO 8601 UTC time this record was last updated."
        },
        "place": {
          "type": "string",
          "description": "Nearest named location."
        },
        "latitude": {
          "type": "number",
          "description": "Epicenter latitude in decimal degrees."
        },
        "longitude": {
          "type": "number",
          "description": "Epicenter longitude in decimal degrees."
        },
        "depth_km": {
          "description": "Hypocenter depth in km; null if unmeasured.",
          "type": [
            "number",
            "null"
          ]
        },
        "felt": {
          "description": "DYFI (Did You Feel It?) response count; null if no USGS reports or source has no DYFI (EMSC). Null does not mean unfelt.",
          "type": [
            "number",
            "null"
          ]
        },
        "cdi": {
          "description": "Maximum DYFI Community Decimal Intensity (0–12); null if uncomputed or unsupported (EMSC).",
          "type": [
            "number",
            "null"
          ]
        },
        "mmi": {
          "description": "Maximum ShakeMap Modified Mercalli intensity (0–12); null without a ShakeMap or for EMSC.",
          "type": [
            "number",
            "null"
          ]
        },
        "alert": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "green",
                "yellow",
                "orange",
                "red"
              ]
            },
            {
              "type": "null"
            }
          ],
          "description": "PAGER estimated impact; null without an assessment or for EMSC."
        },
        "tsunami": {
          "description": "USGS tsunami flag: 1 for large oceanic events, 0 otherwise; null if unpublished (EMSC). Not a warning or evidence of a tsunami; check NOAA tsunami.gov for alerts.",
          "type": [
            "number",
            "null"
          ]
        },
        "significance": {
          "description": "USGS significance (0–2000+), combining magnitude, felt reports and PAGER; null if uncomputed or for EMSC.",
          "type": [
            "number",
            "null"
          ]
        },
        "status": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "automatic",
                "reviewed",
                "deleted"
              ]
            },
            {
              "type": "null"
            }
          ],
          "description": "Review state: automatic (unverified), reviewed (analyst checked), or deleted. Null if unpublished (EMSC); such solutions remain unverified and subject to revision."
        },
        "source_catalog": {
          "description": "Solution catalog, e.g. EMSC-RTS (real-time, subject to revision). Absent for USGS.",
          "type": "string"
        },
        "auth": {
          "description": "Authoritative agency/network code (EMSC auth or USGS net); absent if unpublished.",
          "type": "string"
        },
        "event_type": {
          "description": "QuakeML classification (earthquake, quarry blast, explosion, etc.). EMSC codes decode to USGS names; unknown codes pass through verbatim. Certainty is separate. Absent if unpublished; either catalog includes non-tectonic events.",
          "type": "string"
        },
        "event_certainty": {
          "description": "EMSC classification certainty: known (asserted), suspected, unknown, or unreported. Suspected is not confirmed. Absent for USGS and unrecognized EMSC codes.",
          "type": "string",
          "enum": [
            "known",
            "suspected",
            "unknown",
            "unreported"
          ]
        },
        "event_url": {
          "description": "USGS event page URL. Present for USGS events only.",
          "type": "string"
        },
        "detail_url": {
          "description": "URL to fetch the full GeoJSON detail record. Present in USGS list responses.",
          "type": "string"
        },
        "associated_ids": {
          "description": "Other network IDs USGS lists for this event, in upstream order; earthquake_get_event accepts them. Absent when USGS lists none, and for EMSC events.",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "id",
        "title",
        "magnitude",
        "magnitude_type",
        "time",
        "updated",
        "place",
        "latitude",
        "longitude",
        "depth_km",
        "felt",
        "cdi",
        "mmi",
        "alert",
        "tsunami",
        "significance",
        "status"
      ],
      "additionalProperties": false,
      "description": "Full earthquake event detail."
    },
    "detail": {
      "description": "Projected USGS analysis products. Absent when no projected field is available; absence does not mean impact was zero.",
      "type": "object",
      "properties": {
        "losspager": {
          "description": "PAGER assessment; fatality/economic-loss brackets are in report_url, not this projection. Absent without projected fields.",
          "type": "object",
          "properties": {
            "alert_level": {
              "description": "PAGER impact alert level — \"green\", \"yellow\", \"orange\", or \"red\".",
              "type": "string"
            },
            "report_url": {
              "description": "URL of the PAGER one-page PDF summary of estimated impact.",
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "shakemap": {
          "description": "ShakeMap modeled ground-motion summary. Absent without projected fields.",
          "type": "object",
          "properties": {
            "code_version": {
              "description": "ShakeMap producer code version reported by USGS.",
              "type": "string"
            },
            "max_mmi": {
              "description": "Maximum modeled shaking intensity across the ShakeMap grid (Modified Mercalli).",
              "type": "number"
            },
            "max_pga": {
              "description": "Maximum modeled peak ground acceleration, in g (fraction of standard gravity).",
              "type": "number"
            },
            "max_pgv": {
              "description": "Maximum modeled peak ground velocity, in cm/s.",
              "type": "number"
            },
            "intensity_map_url": {
              "description": "URL of the rendered ShakeMap intensity map image.",
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "dyfi": {
          "description": "Felt-report summary. Absent without projected fields.",
          "type": "object",
          "properties": {
            "responses": {
              "description": "Public DYFI (Did You Feel It?) report count.",
              "type": "number"
            },
            "max_cdi": {
              "description": "Maximum Community Decimal Intensity derived from those reports (0–12 scale).",
              "type": "number"
            },
            "map_url": {
              "description": "URL of the rendered DYFI intensity map image.",
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "moment_tensor": {
          "description": "Focal mechanism; absent without projected fields.",
          "type": "object",
          "properties": {
            "scalar_moment_nm": {
              "description": "Scalar seismic moment, newton-metres.",
              "type": "number"
            },
            "derived_depth_km": {
              "description": "Moment-tensor centroid depth, km.",
              "type": "number"
            },
            "nodal_plane_1": {
              "description": "First nodal plane; either plane may be the fault.",
              "type": "object",
              "properties": {
                "strike": {
                  "type": "number",
                  "description": "Fault plane strike in degrees clockwise from north (0–360)."
                },
                "dip": {
                  "type": "number",
                  "description": "Fault plane dip in degrees from horizontal (0–90)."
                },
                "rake": {
                  "type": "number",
                  "description": "Slip direction, degrees (-180..180): ~90 reverse, ~-90 normal, ~0/180 strike-slip."
                }
              },
              "required": [
                "strike",
                "dip",
                "rake"
              ],
              "additionalProperties": false
            },
            "nodal_plane_2": {
              "description": "Auxiliary nodal plane; seismic data alone cannot distinguish the true fault.",
              "type": "object",
              "properties": {
                "strike": {
                  "type": "number",
                  "description": "Fault plane strike in degrees clockwise from north (0–360)."
                },
                "dip": {
                  "type": "number",
                  "description": "Fault plane dip in degrees from horizontal (0–90)."
                },
                "rake": {
                  "type": "number",
                  "description": "Slip direction, degrees (-180..180): ~90 reverse, ~-90 normal, ~0/180 strike-slip."
                }
              },
              "required": [
                "strike",
                "dip",
                "rake"
              ],
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        "ground_failure": {
          "description": "Secondary-hazard alert levels. Absent without projected fields.",
          "type": "object",
          "properties": {
            "landslide_alert": {
              "description": "Landslide hazard alert level — \"green\", \"yellow\", \"orange\", or \"red\".",
              "type": "string"
            },
            "liquefaction_alert": {
              "description": "Liquefaction hazard alert level — \"green\", \"yellow\", \"orange\", or \"red\".",
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "origin": {
          "description": "Location-quality metrics for the preferred origin; absent without projected fields.",
          "type": "object",
          "properties": {
            "azimuthal_gap_deg": {
              "description": "Largest station azimuthal gap, degrees; >~180 means poorly constrained location.",
              "type": "number"
            },
            "num_stations_used": {
              "description": "Number of seismic stations used in the location solution.",
              "type": "number"
            },
            "horizontal_error_km": {
              "description": "Horizontal location uncertainty in kilometers.",
              "type": "number"
            },
            "depth_error_km": {
              "description": "Depth uncertainty in kilometers.",
              "type": "number"
            },
            "depth_type": {
              "description": "How the depth was set, as published, e.g. \"from location\" or \"operator assigned\" (fixed, not solved for).",
              "type": "string"
            },
            "review_status": {
              "description": "Origin review state published by its network.",
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "finite_fault": {
          "description": "Finite-fault rupture model for large events; absent without projected fields.",
          "type": "object",
          "properties": {
            "rupture_length_km": {
              "description": "Modeled rupture length along strike, in kilometers.",
              "type": "number"
            },
            "rupture_width_km": {
              "description": "Modeled rupture width down dip, in kilometers.",
              "type": "number"
            },
            "model_url": {
              "description": "URL of the finite-fault rupture model file.",
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "origins": {
      "description": "Every origin product, preferred first. Present when requested and published.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": {
            "description": "Network that contributed this origin product.",
            "type": "string"
          },
          "event_id": {
            "description": "Contributing network's ID for the event.",
            "type": "string"
          },
          "is_preferred": {
            "type": "boolean",
            "description": "True for the origin USGS prefers (listed first)."
          },
          "time": {
            "description": "ISO 8601 UTC origin time.",
            "type": "string"
          },
          "latitude": {
            "description": "Epicenter latitude, decimal degrees.",
            "type": "number"
          },
          "longitude": {
            "description": "Epicenter longitude, decimal degrees.",
            "type": "number"
          },
          "depth_km": {
            "description": "Hypocenter depth, km.",
            "type": "number"
          },
          "depth_type": {
            "description": "How the depth was set, as published, e.g. \"from location\" or \"operator assigned\".",
            "type": "string"
          },
          "magnitude": {
            "description": "Magnitude published with this origin.",
            "type": "number"
          },
          "magnitude_type": {
            "description": "Magnitude type, e.g. mww, mb, Mi.",
            "type": "string"
          },
          "review_status": {
            "description": "Review status as published by the network.",
            "type": "string"
          },
          "evaluation_status": {
            "description": "QuakeML evaluation status, e.g. final.",
            "type": "string"
          },
          "num_stations_used": {
            "description": "Stations used in the location.",
            "type": "number"
          },
          "num_phases_used": {
            "description": "Phases used in the location.",
            "type": "number"
          },
          "azimuthal_gap_deg": {
            "description": "Largest azimuthal gap, degrees.",
            "type": "number"
          },
          "standard_error_s": {
            "description": "RMS travel-time residual, seconds.",
            "type": "number"
          },
          "minimum_distance_deg": {
            "description": "Distance to the nearest station, degrees.",
            "type": "number"
          },
          "horizontal_error_km": {
            "description": "Horizontal location uncertainty, km.",
            "type": "number"
          },
          "depth_error_km": {
            "description": "Depth uncertainty, km.",
            "type": "number"
          }
        },
        "required": [
          "is_preferred"
        ],
        "additionalProperties": false,
        "description": "One origin solution from an origin product."
      }
    },
    "magnitudes": {
      "description": "Magnitude solutions from the preferred phase-data product, in document order.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "description": "Magnitude type, e.g. Mww, mb, Ml.",
            "type": "string"
          },
          "value": {
            "description": "Magnitude value.",
            "type": "number"
          },
          "station_count": {
            "description": "Stations contributing to this magnitude.",
            "type": "number"
          },
          "evaluation_mode": {
            "description": "QuakeML evaluation mode: manual or automatic.",
            "type": "string"
          },
          "evaluation_status": {
            "description": "QuakeML evaluation status, e.g. reviewed.",
            "type": "string"
          },
          "agency": {
            "description": "Agency that computed the magnitude.",
            "type": "string"
          },
          "is_preferred": {
            "type": "boolean",
            "description": "True for the document's preferred magnitude."
          }
        },
        "required": [
          "is_preferred"
        ],
        "additionalProperties": false,
        "description": "One event-level magnitude solution."
      }
    },
    "arrivals": {
      "description": "All phase arrivals of the preferred origin, sorted by distance ascending.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "network": {
            "description": "SEED network code.",
            "type": "string"
          },
          "station": {
            "description": "SEED station code.",
            "type": "string"
          },
          "location": {
            "description": "SEED location code as published; \"\" and \"--\" both mean blank.",
            "type": "string"
          },
          "channel": {
            "description": "SEED channel code.",
            "type": "string"
          },
          "phase": {
            "description": "Phase name, e.g. P, Pn, S.",
            "type": "string"
          },
          "time": {
            "description": "ISO 8601 UTC pick time.",
            "type": "string"
          },
          "time_residual_s": {
            "description": "Travel-time residual, seconds.",
            "type": "number"
          },
          "distance_deg": {
            "description": "Epicentral distance, degrees.",
            "type": "number"
          },
          "azimuth_deg": {
            "description": "Azimuth from epicenter to station, degrees.",
            "type": "number"
          },
          "time_weight": {
            "description": "Weight of the arrival time in the location.",
            "type": "number"
          }
        },
        "additionalProperties": false,
        "description": "One phase arrival joined to its pick."
      }
    },
    "aftershock_forecast": {
      "description": "USGS Operational Aftershock Forecast; probabilities change with each update.",
      "type": "object",
      "properties": {
        "advisory_window": {
          "type": "string",
          "description": "Window USGS headlines in its advisory, e.g. \"1 Week\"."
        },
        "created": {
          "type": "string",
          "description": "ISO 8601 UTC time the forecast was issued."
        },
        "expires": {
          "type": "string",
          "description": "ISO 8601 UTC expiry of the forecast."
        },
        "next_update": {
          "description": "ISO 8601 UTC time of the next scheduled update; absent once updates stop.",
          "type": "string"
        },
        "windows": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string",
                "description": "Window label, e.g. \"1 Day\", \"1 Week\"."
              },
              "start": {
                "type": "string",
                "description": "ISO 8601 UTC window start (the forecast issue time, not now)."
              },
              "end": {
                "type": "string",
                "description": "ISO 8601 UTC window end."
              },
              "above_mainshock": {
                "description": "Chance of an aftershock as large as the mainshock; absent when unpublished.",
                "type": "object",
                "properties": {
                  "magnitude": {
                    "type": "number",
                    "description": "Mainshock magnitude."
                  },
                  "probability": {
                    "type": "number",
                    "description": "Probability (0–1) of an aftershock at or above the mainshock magnitude."
                  }
                },
                "required": [
                  "magnitude",
                  "probability"
                ],
                "additionalProperties": false
              },
              "bins": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "magnitude": {
                      "type": "number",
                      "description": "Minimum magnitude of this bin."
                    },
                    "probability": {
                      "type": "number",
                      "description": "Probability (0–1) of at least one aftershock at or above it."
                    },
                    "count_median": {
                      "description": "Median expected count.",
                      "type": "number"
                    },
                    "count_p95_min": {
                      "description": "Lower bound of the 95% count range.",
                      "type": "number"
                    },
                    "count_p95_max": {
                      "description": "Upper bound of the 95% count range.",
                      "type": "number"
                    }
                  },
                  "required": [
                    "magnitude",
                    "probability"
                  ],
                  "additionalProperties": false,
                  "description": "One magnitude bin."
                },
                "description": "Magnitude bins in upstream order."
              }
            },
            "required": [
              "label",
              "start",
              "end",
              "bins"
            ],
            "additionalProperties": false,
            "description": "One forecast window."
          },
          "description": "Forecast windows in upstream order."
        }
      },
      "required": [
        "advisory_window",
        "created",
        "expires",
        "windows"
      ],
      "additionalProperties": false
    },
    "unavailable_includes": {
      "description": "Requested groups not returned, with the reason. Absent when all were returned.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "group": {
            "type": "string",
            "enum": [
              "origins",
              "magnitudes",
              "arrivals",
              "aftershock_forecast"
            ],
            "description": "The requested group."
          },
          "reason": {
            "type": "string",
            "enum": [
              "not_published",
              "fetch_failed"
            ],
            "description": "not_published: the event has no product for it. fetch_failed: the product exists but could not be fetched or parsed."
          }
        },
        "required": [
          "group",
          "reason"
        ],
        "additionalProperties": false,
        "description": "One requested group that was not returned."
      }
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `event_deleted`: USGS reports that the requested event was deleted. `not_found`: No USGS or EMSC event matches the provided event_id. `source_unavailable`: The USGS or EMSC event API returns a 5xx, serves HTML, or is unreachable. `source_timeout`: The USGS or EMSC event API did not answer before the request deadline. Other values are possible when a failure originates below the handler.",
              "examples": [
                "event_deleted",
                "not_found",
                "source_unavailable",
                "source_timeout"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "event"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Count matches without event records, or size an earthquake_search_events query. Omitting start_time uses 30 days; pass explicit bounds for historical periods. queryEcho reports applied filters/window; ignoredFilters names unsupported EMSC inputs. Circle and independently optional box edges intersect. Both catalogs include non-tectonic events; event_type="earthquake" excludes them on USGS. exceeds_limit marks the 20,000-event single-request threshold, not a retrieval ceiling: search supports offset paging beyond it. max_allowed is 20,000 for USGS, null for EMSC.

{
  "type": "object",
  "properties": {
    "start_time": {
      "description": "Start of time range as ISO 8601 (e.g. \"2026-01-01\" or \"2026-05-23T00:00:00\"). A bare year expands to January 1st and an unpadded month or day is zero-padded, with date-only values resolved to midnight (T00:00:00) on both sources. Explicit time and timezone suffixes are preserved. Defaults to 30 days before end_time (or before the current time) if omitted — applied server-side so USGS and EMSC honor the same window.",
      "type": "string",
      "pattern": "^\\d{4}(-\\d{1,2}(-\\d{1,2})?)?([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "end_time": {
      "description": "End of time range as ISO 8601, in the same forms start_time accepts. Date-only values mean midnight at the start of the named day, not the whole day. Defaults to current time if omitted.",
      "type": "string",
      "pattern": "^\\d{4}(-\\d{1,2}(-\\d{1,2})?)?([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "min_magnitude": {
      "description": "Minimum magnitude (Richter or equivalent). M2.5+ is felt by some people; M5+ can cause damage; M7+ is major.",
      "type": "number",
      "minimum": -1,
      "maximum": 10
    },
    "max_magnitude": {
      "description": "Maximum magnitude.",
      "type": "number",
      "minimum": -1,
      "maximum": 10
    },
    "latitude": {
      "description": "Latitude for radius search. Requires longitude and radius_km.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "description": "Longitude for radius search. Requires latitude and radius_km.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "radius_km": {
      "description": "Search radius in kilometers from the lat/lon point. Max 20001.6, the ceiling USGS enforces — half the Earth's great-circle circumference. Converted to degrees for EMSC (1° ≈ 111.2 km).",
      "type": "number",
      "minimum": 0,
      "maximum": 20001.6
    },
    "min_latitude": {
      "description": "Southern edge of a bounding-box search, in degrees. Independent of the other three box parameters — supply any of them. Must not exceed max_latitude when both are given.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "max_latitude": {
      "description": "Northern edge of a bounding-box search, in degrees.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "min_longitude": {
      "description": "Western edge of a bounding-box search, in degrees. Range extends beyond ±180 so a box can cross the antimeridian (e.g. min_longitude=170, max_longitude=190) — always keep min_longitude at or below max_longitude rather than inverting the pair.",
      "type": "number",
      "minimum": -360,
      "maximum": 360
    },
    "max_longitude": {
      "description": "Eastern edge of a bounding-box search, in degrees.",
      "type": "number",
      "minimum": -360,
      "maximum": 360
    },
    "min_depth_km": {
      "description": "Minimum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope. Shallow quakes (0–70 km) typically cause more surface damage than deep quakes (>300 km).",
      "type": "number",
      "minimum": -100,
      "maximum": 1000
    },
    "max_depth_km": {
      "description": "Maximum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope.",
      "type": "number",
      "minimum": -100,
      "maximum": 1000
    },
    "alert_level": {
      "description": "Minimum PAGER alert level. PAGER estimates economic loss and casualties. \"green\" = minimal impact; \"red\" = extreme. Only available from USGS.",
      "type": "string",
      "enum": [
        "green",
        "yellow",
        "orange",
        "red"
      ]
    },
    "min_felt": {
      "description": "Minimum number of DYFI (Did You Feel It?) reports. Use to count events with confirmed public impact. Only available from USGS.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "min_significance": {
      "description": "Minimum USGS significance score (0–2000+). Combines magnitude, felt reports, and PAGER estimates. Significant events typically score 600+. Only available from USGS.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "event_type": {
      "description": "Filter by upstream event classification, e.g. \"earthquake\" to exclude quarry blasts and explosions from the count, or \"quarry blast\" to count only those. Matched verbatim against the USGS catalog, which accepts any string and returns a count of zero for an unrecognized one. Only available from USGS.",
      "type": "string",
      "minLength": 1
    },
    "magnitude_type": {
      "description": "Magnitude type, e.g. \"mb\" or \"mww\"; both sources. Blank means omitted.",
      "type": "string"
    },
    "product_type": {
      "description": "Required product type, e.g. \"moment-tensor\"; USGS only. Blank means omitted.",
      "type": "string"
    },
    "review_status": {
      "description": "USGS review status: automatic or reviewed. Blank means omitted; unsupported by EMSC.",
      "type": "string"
    },
    "source": {
      "default": "usgs",
      "description": "Data source. Both catalogs are global. \"usgs\" covers global events with PAGER, DYFI, and ShakeMap metadata. \"emsc\" is an independent global catalog operated by the European-Mediterranean Seismological Centre — use it to cross-check a count from a separate network. It has no PAGER, DYFI, or ShakeMap metadata; its station coverage is densest around Europe and the Mediterranean, so counts of small events differ most by region.",
      "type": "string",
      "enum": [
        "usgs",
        "emsc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "count": {
      "type": "number",
      "description": "Number of events matching the query."
    },
    "max_allowed": {
      "description": "Upstream single-request threshold: 20000 for USGS; null because EMSC count omits it. Offset paging can retrieve larger sets.",
      "type": [
        "number",
        "null"
      ]
    },
    "source": {
      "type": "string",
      "enum": [
        "usgs",
        "emsc"
      ],
      "description": "Data source used."
    },
    "exceeds_limit": {
      "type": "boolean",
      "description": "Count exceeds the single-request threshold (20000 for EMSC despite null max_allowed). Use search offset paging or narrower filters."
    },
    "queryEcho": {
      "description": "Echo of the effective parameters the count covers, including server-resolved defaults. Read start_time and end_time to know which window the count spans — a filter absent here was not sent upstream.",
      "type": "object",
      "properties": {
        "start_time": {
          "description": "Applied start time; defaults to 30 days before end/now.",
          "type": "string"
        },
        "end_time": {
          "description": "Applied end time; absent means upstream current-time default.",
          "type": "string"
        },
        "min_magnitude": {
          "description": "Applied minimum magnitude.",
          "type": "number"
        },
        "max_magnitude": {
          "description": "Applied maximum magnitude.",
          "type": "number"
        },
        "latitude": {
          "description": "Circle latitude, degrees.",
          "type": "number"
        },
        "longitude": {
          "description": "Circle longitude, degrees.",
          "type": "number"
        },
        "radius_km": {
          "description": "Search radius in km sent upstream (converted to degrees for EMSC).",
          "type": "number"
        },
        "min_latitude": {
          "description": "Southern bounding-box edge sent upstream, in degrees.",
          "type": "number"
        },
        "max_latitude": {
          "description": "Northern bounding-box edge sent upstream, in degrees.",
          "type": "number"
        },
        "min_longitude": {
          "description": "Western bounding-box edge sent upstream, in degrees.",
          "type": "number"
        },
        "max_longitude": {
          "description": "Eastern bounding-box edge sent upstream, in degrees.",
          "type": "number"
        },
        "min_depth_km": {
          "description": "Applied minimum depth, km.",
          "type": "number"
        },
        "max_depth_km": {
          "description": "Applied maximum depth, km.",
          "type": "number"
        },
        "alert_level": {
          "description": "Applied minimum PAGER alert; absent for EMSC.",
          "type": "string"
        },
        "min_felt": {
          "description": "Applied minimum DYFI response count; absent for EMSC.",
          "type": "number"
        },
        "min_significance": {
          "description": "Applied minimum significance; absent for EMSC.",
          "type": "number"
        },
        "event_type": {
          "description": "Applied event type; absent for EMSC.",
          "type": "string"
        },
        "magnitude_type": {
          "description": "Applied magnitude type.",
          "type": "string"
        },
        "product_type": {
          "description": "Applied required product; USGS only.",
          "type": "string"
        },
        "review_status": {
          "description": "Applied review status; USGS only.",
          "type": "string",
          "enum": [
            "automatic",
            "reviewed"
          ]
        },
        "source": {
          "type": "string",
          "enum": [
            "usgs",
            "emsc"
          ],
          "description": "Data source queried."
        }
      },
      "required": [
        "source"
      ],
      "additionalProperties": false
    },
    "ignoredFilters": {
      "description": "USGS-only filters supplied in the input but not sent upstream because source=emsc does not support them. The count is NOT constrained by these — re-run with source=usgs to apply them. Absent when every supplied filter was applied.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "Name of an input filter that was not applied."
      }
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_range`: Minimum magnitude or depth exceeds its maximum, or start_time is after end_time. `invalid_radius`: latitude or longitude provided without radius_km, or vice versa. `invalid_bounding_box`: min_latitude exceeds max_latitude, or min_longitude exceeds max_longitude. `source_unavailable`: Selected source API returns a 5xx or is unreachable. `source_timeout`: Selected source API did not answer before the request deadline. `upstream_rejected`: The source API rejected the query parameters and explained why in its response body. `upstream_rejected_no_reason`: The source API rejected the query but its response body carried no usable explanation. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_range",
                "invalid_radius",
                "invalid_bounding_box",
                "source_unavailable",
                "source_timeout",
                "upstream_rejected",
                "upstream_rejected_no_reason"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "count",
        "max_allowed",
        "source",
        "exceeds_limit"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}