Tutorial: Earthquakes (USGS)

Environment

Data source: USGS Earthquake Hazards

Overview

Earthquakes (USGS) wraps USGS Earthquake Hazards, handling authentication, pagination, and rate limits for you. This tutorial covers all 4 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-earthquakes": {
      "url": "https://context.gnist.ai/mcp/earthquakes/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (4)

`search_earthquakes`

Search earthquakes from the USGS seismic event database. Query by magnitude range, date range, geographic bounding box, and depth. Data is sourced from the USGS Earthquake Hazards Program and updated every minute. Args: min_magnitude: Minimum magnitude (e.g. 4.5 for significant quakes). max_magnitude: Maximum magnitude. start_time: Start date/time in ISO 8601 (e.g. "2024-01-01" or "2024-01-01T00:00:00"). end_time: End date/time in ISO 8601. min_latitude: Southern boundary (-90 to 90). max_latitude: Northern boundary (-90 to 90). min_longitude: Western boundary (-180 to 180). max_longitude: Eastern boundary (-180 to 180). min_depth: Minimum depth in km. max_depth: Maximum depth in km. limit: Maximum results to return (1-200, default 20). order_by: Sort order — "time" (newest first), "time-asc", "magnitude", "magnitude-asc". Returns: Dict with 'count' and 'results' list of earthquakes. Each earthquake includes magnitude, location (place, lat/lon), depth, time, alert level, tsunami flag, and a USGS detail URL.

Parameter	Type	Required	Description
`min_magnitude`	any	optional	Minimum magnitude (e.g. 4.5 for significant quakes).
`max_magnitude`	any	optional	Maximum magnitude.
`start_time`	any	optional	Start date/time in ISO 8601 (e.g. "2024-01-01" or "2024-01-01T00:00:00").
`end_time`	any	optional	End date/time in ISO 8601.
`min_latitude`	any	optional	Southern boundary (-90 to 90).
`max_latitude`	any	optional	Northern boundary (-90 to 90).
`min_longitude`	any	optional	Western boundary (-180 to 180).
`max_longitude`	any	optional	Eastern boundary (-180 to 180).
`min_depth`	any	optional	Minimum depth in km.
`max_depth`	any	optional	Maximum depth in km.
`limit`	integer	optional	Maximum results to return (1-200, default 20). (default: `20`)
`order_by`	string	optional	Sort order — "time" (newest first), "time-asc", "magnitude", "magnitude-asc". (default: `time`)

curl -X POST "https://context.gnist.ai/mcp/earthquakes/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_earthquakes", "arguments": {"min_magnitude": "4.5"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/earthquakes/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'min_magnitude': '4.5'},
            'name': 'search_earthquakes'}},
)
print(resp.json())

`get_earthquake`

Get detailed information about a specific earthquake by its USGS event ID. Args: event_id: The USGS event identifier (e.g. "us7000n7q6"). Returns: Dict with earthquake details including magnitude, location, depth, time, felt reports count, alert level (green/yellow/orange/red), tsunami flag, and the USGS detail URL. Returns an error if the event is not found.

Parameter	Type	Required	Description
`event_id`	string	required	The USGS event identifier (e.g. "us7000n7q6").

curl -X POST "https://context.gnist.ai/mcp/earthquakes/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_earthquake", "arguments": {"event_id": "us7000n7q6"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/earthquakes/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'event_id': 'us7000n7q6'}, 'name': 'get_earthquake'}},
)
print(resp.json())

`latest_earthquakes`

Get the latest significant earthquakes globally or near a specific location. By default returns recent M4.5+ earthquakes worldwide. Optionally filter to a specific area by providing a center point and radius. Args: min_magnitude: Minimum magnitude threshold (default 4.5). limit: Maximum results to return (1-100, default 10). latitude: Center latitude for geographic filter (-90 to 90). Requires longitude. longitude: Center longitude for geographic filter (-180 to 180). Requires latitude. max_radius_km: Search radius in kilometers from the center point (default 500 if lat/lon given). Returns: Dict with 'count' and 'results' list of recent earthquakes sorted by time (newest first).

Parameter	Type	Required	Description
`min_magnitude`	number	optional	Minimum magnitude threshold (default 4.5). (default: `4.5`)
`limit`	integer	optional	Maximum results to return (1-100, default 10). (default: `10`)
`latitude`	any	optional	Center latitude for geographic filter (-90 to 90). Requires longitude.
`longitude`	any	optional	Center longitude for geographic filter (-180 to 180). Requires latitude.
`max_radius_km`	any	optional	Search radius in kilometers from the center point (default 500 if lat/lon given).

curl -X POST "https://context.gnist.ai/mcp/earthquakes/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "latest_earthquakes", "arguments": {"min_magnitude": 4.5}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/earthquakes/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'min_magnitude': 4.5}, 'name': 'latest_earthquakes'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/earthquakes/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/earthquakes/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_earthquakes to find items, then get_earthquake to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does Earthquakes (USGS) provide?

Recent and historical earthquake data — magnitude, location, depth, and alerts. It exposes 4 tools: search_earthquakes, get_earthquake, latest_earthquakes, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Earthquakes (USGS) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.