GSIN API Documentation

Real-time global seismic intelligence, stress-field modeling, and forecasting data via RESTful and WebSocket interfaces.

API v1.0 – Base URL: https://api.gsin.dev/v1

Quick Start

Authentication Required

All API endpoints require an API key. Include your key in theX-API-Keyheader for all requests.

# Example request

curl -H "X-API-Key: your_api_key_here" \

https://api.gsin.dev/v1/events/recent

Global Coverage

Real-time data from USGS, EMSC, JMA, GFZ, and 50+ seismic networks

Low Latency

Event data updated within 250ms of source publication

Enterprise Ready

99.9% uptime SLA, rate limiting, webhook callbacks

Core Endpoints

GET

/events/recent

Recent Seismic Events

Retrieve the latest earthquake events from the global network.

Parameters

limitinteger

Number of events to return (1-1000, default: 100)

min_magnitudefloat

Minimum magnitude filter (default: 2.5)

start_timeISO8601

Filter events after this timestamp

end_timeISO8601

Filter events before this timestamp

regionstring

Geographic region code (e.g., 'asia-pacific', 'americas')

Response Example

{
  "events": [
    {
      "id": "us7000kx3e",
      "timestamp": "2025-11-07T14:32:18Z",
      "latitude": 35.6762,
      "longitude": 139.6503,
      "depth_km": 12.4,
      "magnitude": 5.7,
      "magnitude_type": "Mw",
      "location": "Tokyo Bay, Japan",
      "source": "JMA",
      "status": "reviewed"
    }
  ],
  "count": 1,
  "timestamp": "2025-11-07T14:35:42Z"
}

GET

/events/{event_id}

Event Details

Get comprehensive information about a specific seismic event.

Parameters

event_idstringrequired

Unique event identifier

Response Example

{
  "event": {
    "id": "us7000kx3e",
    "timestamp": "2025-11-07T14:32:18Z",
    "location": {
      "latitude": 35.6762,
      "longitude": 139.6503,
      "depth_km": 12.4,
      "description": "Tokyo Bay, Japan"
    },
    "magnitude": {
      "value": 5.7,
      "type": "Mw",
      "uncertainty": 0.2
    },
    "felt_reports": 1247,
    "intensity": "VII (Very Strong)",
    "source": "JMA",
    "phases": {
      "p_wave": "2025-11-07T14:32:18.234Z",
      "s_wave": "2025-11-07T14:32:22.891Z"
    }
  }
}

GET

/stress/region

Regional Stress Fields

Retrieve 3D crustal stress modeling data for a specified region.

Parameters

regionstringrequired

Region identifier (e.g., 'ring-of-fire-west')

resolutionstring

Grid resolution: 'low' (64³), 'medium' (128³), 'high' (256³)

timestampISO8601

Specific timestamp (default: latest)

Response Example

{
  "region": "ring-of-fire-west",
  "timestamp": "2025-11-07T14:00:00Z",
  "resolution": [128, 128, 128],
  "bounds": {
    "lat_min": 20.0,
    "lat_max": 50.0,
    "lon_min": 120.0,
    "lon_max": 150.0,
    "depth_max_km": 700
  },
  "stress_field": {
    "url": "https://cdn.gsin.dev/stress/2025-11-07/ring-of-fire-west.h5",
    "format": "HDF5",
    "size_mb": 142.3
  },
  "anomalies_detected": 3,
  "forecast_confidence": 0.87
}

GET

/forecast/regions

Forecast Hotspots

Get current stress accumulation forecasts and high-risk regions.

Parameters

thresholdfloat

Minimum forecast confidence (0.0-1.0, default: 0.7)

timeframestring

Forecast window: '24h', '72h', '7d' (default: '72h')

Response Example

{
  "forecasts": [
    {
      "region": "Philippine Trench",
      "coordinates": {
        "latitude": 12.5,
        "longitude": 127.3
      },
      "confidence": 0.84,
      "magnitude_range": [5.5, 6.2],
      "timeframe": "48-72 hours",
      "stress_accumulation_index": 0.91,
      "last_major_event": "2024-08-15T03:21:00Z",
      "historical_pattern_match": "2018-07-22 M6.1 sequence"
    }
  ],
  "generated_at": "2025-11-07T14:35:42Z"
}

GET

/swarms/active

Active Earthquake Swarms

Detect and monitor ongoing earthquake swarm sequences.

Parameters

min_eventsinteger

Minimum events in cluster (default: 5)

max_age_hoursinteger

Maximum swarm age in hours (default: 72)

Response Example

{
  "swarms": [
    {
      "id": "swarm_2025_1107_ph01",
      "status": "active",
      "region": "Philippines East Coast",
      "centroid": {
        "latitude": 14.2,
        "longitude": 125.8
      },
      "event_count": 23,
      "duration_hours": 18.5,
      "magnitude_range": [3.2, 5.1],
      "largest_event": {
        "magnitude": 5.1,
        "timestamp": "2025-11-07T08:14:32Z"
      },
      "classification": "normal_swarm",
      "forecast_mainshock_probability": 0.42
    }
  ]
}

POST

/webhooks/subscribe

Webhook Subscriptions

Subscribe to real-time event notifications via webhooks.

Parameters

urlstringrequired

Your webhook endpoint URL

event_typesarray

Event types to subscribe to: ['earthquake', 'forecast', 'swarm']

min_magnitudefloat

Minimum magnitude threshold (default: 4.0)

regionsarray

Specific regions to monitor (empty = global)

Response Example

{
  "subscription_id": "sub_a1b2c3d4e5f6",
  "status": "active",
  "created_at": "2025-11-07T14:35:42Z",
  "config": {
    "url": "https://your-domain.com/webhook",
    "event_types": ["earthquake", "forecast"],
    "min_magnitude": 5.0,
    "regions": ["asia-pacific"]
  }
}

WebSocket Streaming

Connect to real-time seismic event streams with sub-second latency. Perfect for dashboards, monitoring systems, and real-time alerting.

Connection Endpoint

wss://api.gsin.dev/v1/stream

Authentication

Send API key as first message after connection:

{"auth": "your_api_key_here"}

Subscribe to Channels

{"subscribe": ["events", "forecasts", "swarms"]}

Event Stream Example

{ "type": "earthquake", "data": { "id": "us7000kx3e", "magnitude": 5.7, "latitude": 35.6762, "longitude": 139.6503, "depth_km": 12.4, "timestamp": "2025-11-07T14:32:18Z", "location": "Tokyo Bay, Japan" } }

Advantages

• Sub-second event delivery
• Automatic reconnection
• Filtered event streams
• Binary data support (HDF5)

Rate Limits

• Max 5 concurrent connections
• 1000 messages/minute
• Auto-throttle on overload
• Enterprise plans: unlimited

Rate Limits & Authentication

API Key Tiers

Tier	Requests/Hour	WebSocket Connections	Data Export
Free	100	1	CSV only
Developer	1,000	3	CSV, JSON, HDF5
Professional	10,000	10	All formats + Raw
Enterprise	Unlimited	Unlimited	Custom pipelines

Getting an API Key

Free tier keys are available immediately. Developer and Professional tiers require verification. Enterprise deployments include dedicated support.

Request API Key

HTTP Response Codes

200

Request successful

400

Bad Request

Invalid parameters or malformed request

401

Unauthorized

Missing or invalid API key

403

Forbidden

API key valid but lacks permission for this endpoint

429

Rate Limit Exceeded

Too many requests, retry after specified time

500

Internal Server Error

Server error, please retry or contact support

503

Service Unavailable

Temporary downtime for maintenance

Code Examples

Python

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://api.gsin.dev/v1"

headers = {"X-API-Key": API_KEY}

# Get recent earthquakes
response = requests.get(
    f"{BASE_URL}/events/recent",
    headers=headers,
    params={"min_magnitude": 5.0, "limit": 50}
)

events = response.json()["events"]
for event in events:
    print(f"{event['magnitude']} - {event['location']}")

JavaScript

const API_KEY = "your_api_key_here";
const BASE_URL = "https://api.gsin.dev/v1";

async function getRecentEvents() {
  const response = await fetch(
    `${BASE_URL}/events/recent?min_magnitude=5.0&limit=50`,
    {
      headers: { "X-API-Key": API_KEY }
    }
  );
  
  const data = await response.json();
  return data.events;
}

getRecentEvents().then(events => {
  events.forEach(event => {
    console.log(`${event.magnitude} - ${event.location}`);
  });
});

cURL

# Get recent earthquakes
curl -H "X-API-Key: your_api_key_here" \
  "https://api.gsin.dev/v1/events/recent?min_magnitude=5.0&limit=50"

# Get specific event details
curl -H "X-API-Key: your_api_key_here" \
  "https://api.gsin.dev/v1/events/us7000kx3e"

# Subscribe to webhooks
curl -X POST -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/webhook", "event_types": ["earthquake"], "min_magnitude": 6.0}' \
  "https://api.gsin.dev/v1/webhooks/subscribe"

Support & Resources

Technical Support

Need help integrating the API? Our engineering team provides direct support for all paid tiers.

api@gsin.dev →

Documentation Updates

API documentation is continuously updated. Subscribe to our changelog for breaking changes and new features.

View Changelog →

SDKs & Libraries

Official client libraries for Python, JavaScript, Go, and R coming Q2 2026.

GitHub Repository →

System Status

Real-time API status, uptime monitoring, and scheduled maintenance windows.

View Status Page →