Developer Reference

API Documentation

Talivio Seismic Platform REST API — FastAPI · OpenAPI 3.1

⚡ Swagger UI 📖 ReDoc Base URL: https://earthquake.talivio.com

🔓 Authentication: Free usage is subject to an IP-based rate limit (60 req/min). Paid API key raises the limit to 1,000 req/hour. Key: Authorization: Bearer tvio_... or ?api_key=tvio_...

Prediction Endpoints

POST /api/v1/predict/bands Multi-band ML prediction (M4-5, M5-6, M6-7, M7+)

Returns independent ML predictions across four magnitude bands for the given coordinates and date. Each band is trained with a different algorithm.

Field	Type	Required	Description
lat	float	yes	Latitude (-90 / +90)
lon	float	yes	Longitude (-180 / +180)
date	string	no	Date YYYY-MM-DD, defaults to today
save_forecast	bool	no	Save result to forecast table

RESPONSE 200

{
  "bands": [
    {
      "band":         "M4-5",
      "risk_score":   0.62,
      "risk_percent": 62.0,
      "risk_label":   "Medium-High",
      "algorithm":    "LightGBM",
      "roc_auc":      0.74
    }
  ],
  "dominant_band": "M4-5"
}

POST /api/v1/predict Legacy single-score prediction (backwards compatibility)

Preserved endpoint to support the legacy PHP frontend. New integrations should prefer /api/v1/predict/bands.

Field	Type	Required	Description
lat	float	yes	Latitude
lon	float	yes	Longitude
date	string	no	YYYY-MM-DD

{
  "risk_score":  0.57,
  "risk_label":  "Medium",
  "risk_percent":57.0
}

Forecast Tracking Endpoints

GET /api/v1/forecasts List saved forecasts

Parameter	Type	Default	Description
limit	int	50	Records per page
band	string	all	M4-5 / M5-6 / M6-7 / M7+
outcome	string	all	pending / hit / miss / expired

"forecasts": [
  {
    "id":         42,
    "band":       "M5-6",
    "risk_score": 0.48,
    "outcome":    "pending",
    "created_at": "2026-03-15T08:00:00"
  }
]

GET /api/v1/forecasts/accuracy Per-band prediction accuracy statistics

{
  "total":   128,
  "hit":     74,
  "miss":    31,
  "pending": 23,
  "by_band": { "M4-5": {"accuracy":0.71}, "M5-6": {"accuracy":0.65} }
}

POST /api/v1/forecasts/verify Verify pending forecasts against USGS data

{
  "verified": 12,
  "hits":     5,
  "misses":   7
}

Data Pipeline Endpoints

GET /api/v1/data/usgs/recent Fetch recent earthquakes from the USGS catalog

Parameter	Type	Default	Description
days	int	7	How many days back to retrieve
min_mag	float	4.5	Minimum magnitude filter

"events": [ { "mag":5.2, "lat":40.9, "lon":29.1, "depth":12.0, "time":"2026-03-30T14:22:00Z" } ]

POST /api/v1/data/usgs/ingest Ingest USGS data (background job)

Initiates a two-phase USGS fetch (summary + detail/moment tensor). Progress can be tracked via GET /api/v1/data/ingest/{job_id} using the returned job_id.

# POST /api/v1/data/usgs/ingest
{ "status":"started", "job_id":"usgs_20260401_080000" }
# GET /api/v1/data/ingest/usgs_20260401_080000
{ "status":"completed", "records":142 }

GET /api/v1/pipeline/status APScheduler job schedule and last run times

{
  "usgs_ingest":     { "interval":"6h",     "last_run":"2026-04-01T06:00:00" },
  "gnss_ingest":     { "interval":"24h",    "last_run":"2026-04-01T02:00:00" },
  "quality_check":   { "interval":"12h",    "last_run":"2026-04-01T00:00:00" },
  "retrain":         { "interval":"weekly",  "last_run":"2026-03-31T03:00:00" }
}

API Key Management

Rate Limiting

Usage	Limit	Burst
No key (free)	60 req/min, 500 req/hour	15 req/10 sec
API Key (paid)	1,000 req/hour	100 req/10 sec

Exceeding the burst limit blocks the IP for 5 minutes. The paid key raises all limits.

Purchase API Key — 5€

After payment your API key is automatically sent to your email address. Rate limit is raised to 1,000 req/hour.

Purchase API Key →

Keys start with the tvio_ prefix. Maximum 5 active keys per email address.

GET /api/v1/apikey/verify Check whether an API key is valid

Send your key via the Authorization: Bearer tvio_... header or ?api_key=tvio_... query parameter.

{
  "valid":          true,
  "tier":           "paid",
  "rate_limit":     "1000/hour",
  "requests_total": 142
}

GET /api/v1/apikey/usage Show usage statistics for an API key

Requires a valid API key.

{
  "email":           "user@example.com",
  "tier":            "paid",
  "rate_limit":      "1000/hour",
  "requests_total":  142,
  "last_used_at":    "2026-04-01 14:30:00",
  "created_at":      "2026-03-15 10:00:00"
}

POST /api/v1/apikey/create Manual key creation (internal use)

Normally created automatically via Stripe webhook. Direct use is for testing purposes.

Field	Type	Required	Description
email	string	yes	Email address
stripe_session_id	string	no	Stripe session ID

# Response (key is shown only once!)
{
  "api_key":    "tvio_a1b2c3d4e5f6...",
  "key_prefix": "tvio_a1b2c3",
  "tier":       "paid",
  "rate_limit": "1000/hour",
  "message":    "Store your key in a safe place."
}

Pydantic Schemas

Data Models

BandPrediction

bandstrM4-5 / M5-6 / M6-7 / M7+

risk_scorefloat0.0 – 1.0

risk_percentfloat0.0 – 100.0

risk_labelstrLow / Medium / High / Critical

algorithmstrWinning algorithm name

roc_aucfloatTest set ROC-AUC

MultiBandPredictRequest

latfloatRequired

lonfloatRequired

datestr?YYYY-MM-DD, optional

save_forecastboolDefault false

ForecastRecord

idintPrimary key

bandstrMagnitude band

risk_scorefloatScore at prediction time

outcomestrpending / hit / miss / expired

created_atdatetimeRecord timestamp

CelestialResponse

datestrYYYY-MM-DD

tidal_stressfloat0–1 normalised tidal stress

full_indexfloatComposite celestial index

is_high_riskboolAbove threshold?

moon_phasestrMoon phase name

Ready-to-use Examples

cURL Examples

# Multi-band prediction — Istanbul
curl -X POST "https://earthquake.talivio.com/api/v1/predict/bands" \
  -H "Content-Type: application/json" \
  -d '{"lat": 41.01, "lon": 28.97, "date": "2026-04-07"}'

# Multi-band prediction — Tokyo (save forecast)
curl -X POST "https://earthquake.talivio.com/api/v1/predict/bands" \
  -H "Content-Type: application/json" \
  -d '{"lat": 35.69, "lon": 139.69, "save_forecast": true}'

# Celestial stress components — today
curl "https://earthquake.talivio.com/api/v1/celestial/2026-04-07"

# Recent USGS earthquakes last 7 days (M5+)
curl "https://earthquake.talivio.com/api/v1/data/usgs/recent?days=7&min_mag=5.0"

# Band model status
curl "https://earthquake.talivio.com/api/v1/ml/bands/status"

# Verify pending forecasts against USGS
curl -X POST "https://earthquake.talivio.com/api/v1/forecasts/verify" \
  -H "Content-Type: application/json" -d '{}'

# System health check
curl "https://earthquake.talivio.com/api/v1/health"

# Request with API key (header)
curl -H "Authorization: Bearer tvio_YOUR_KEY_HERE" \
  "https://earthquake.talivio.com/api/v1/predict/bands" \
  -X POST -H "Content-Type: application/json" \
  -d '{"lat": 41.01, "lon": 28.97}'

# Verify API key
curl -H "Authorization: Bearer tvio_YOUR_KEY_HERE" \
  "https://earthquake.talivio.com/api/v1/apikey/verify"

# Usage statistics
curl "https://earthquake.talivio.com/api/v1/apikey/usage?api_key=tvio_YOUR_KEY_HERE"