{ "openapi": "3.1.0", "info": { "title": "Earthquakes API", "version": "1.0.0", "description": "311,590 earthquakes of magnitude 4.5 and above since 1900 from USGS, with nearby and largest lookups, daily.\n\nEvery recorded earthquake worldwide of magnitude 4.5 or greater since 1900 — 311,590 events from the USGS ComCat catalog, refreshed daily. Each event carries precise time, coordinates, depth, magnitude with its type, a human-readable place, review status and a link to the USGS event page. The largest endpoint reads like seismology history: 1960 Chile M9.5, 1964 Alaska M9.2, 2011 Tohoku and 2004 Sumatra at M9.1. The nearby endpoint answers location questions in one call — 300 km around Tokyo at M7+ surfaces the 1923 Great Kanto earthquake 55 km out and the 2011 megathrust; search filters cover magnitude range, place, and dates (California at M6+: 1,072 events, led by the 1906 San Francisco quake). New events land daily and USGS''s post-event magnitude revisions flow in automatically via a rolling re-upsert window. Built for dashboards and news widgets, insurance and catastrophe models, education, and any product that needs seismic history plus a live feed behind one key. Public-domain source data, self-hosted — no third-party calls at request time.", "contact": { "name": "Data and APIs", "url": "https://dataandapis.com/contact" }, "termsOfService": "https://dataandapis.com/terms-of-service", "license": { "name": "Data and APIs Terms of Service", "url": "https://dataandapis.com/terms-of-service" }, "x-logo": { "url": "https://dataandapis.com/images/earthquakes.webp" } }, "externalDocs": { "description": "Documentation, live tester and pricing", "url": "https://dataandapis.com/apis/earthquakes" }, "servers": [ { "url": "https://api-earthquakes.dataandapis.com" } ], "tags": [ { "name": "Data", "description": "Earthquakes API belongs to the Data category of the Data and APIs catalog." } ], "paths": { "/v1/sources": { "get": { "operationId": "dataSources", "summary": "Data Sources", "description": "Data Sources endpoint of the Earthquakes API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/earthquakes/data-sources" }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "coverage": "USGS ComCat, M4.5+ worldwide, 1900-present (daily refresh)", "count": 1, "sources": [ { "slug": "usgs-comcat", "name": "USGS ComCat M4.5+ worldwide 1900-present", "publisher": "US Geological Survey", "licence": "US Government work - public domain", "source_url": "https://earthquake.usgs.gov/data/comcat/", "file_url": "https://earthquake.usgs.gov/fdsnws/event/1/query?format=csv", "cadence": "continuous (daily refresh)", "record_count": 311590, "retrieved_at": "2026-09-06" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/earthquakes/nearby": { "get": { "operationId": "earthquakesNearAPoint", "summary": "Earthquakes Near A Point", "description": "Earthquakes Near A Point endpoint of the Earthquakes API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/earthquakes/earthquakes-near-a-point" }, "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "string" }, "example": "35.68" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "25" }, { "name": "lon", "in": "query", "required": true, "schema": { "type": "string" }, "example": "139.69" }, { "name": "min_magnitude", "in": "query", "required": false, "schema": { "type": "string" }, "example": "7" }, { "name": "radius", "in": "query", "required": false, "schema": { "type": "string" }, "example": "300" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "lat": 35.68, "lon": 139.69, "radius_km": 300, "count": 3, "results": [ { "id": "iscgem911526", "time": "1923-09-01T02:58:35.270Z", "magnitude": 7.96, "magnitude_type": "mw", "place": "5 km SSE of ?iso, Japan", "latitude": 35.274, "longitude": 139.344, "depth_km": 15, "type": "earthquake", "status": "reviewed", "network": "iscgem", "url": "https://earthquake.usgs.gov/earthquakes/eventpage/iscgem911526", "distance_km": 55 }, { "id": "iscgem892187", "time": "1953-11-25T17:48:55.090Z", "magnitude": 7.9, "magnitude_type": "mw", "place": "174 km SE of Katsuura, Japan", "latitude": 34.006, "longitude": 141.625, "depth_km": 25, "type": "earthquake", "status": "reviewed", "network": "iscgem", "url": "https://earthquake.usgs.gov/earthquakes/eventpage/iscgem892187", "distance_km": 256.6 }, { "id": "usp000hvpa", "time": "2011-03-11T06:15:40.280Z", "magnitude": 7.9, "magnitude_type": "mwc", "place": "47 km E of ?arai, Japan", "latitude": 36.281, "longitude": 141.111, "depth_km": 42.6, "type": "earthquake", "status": "reviewed", "network": "us", "url": "https://earthquake.usgs.gov/earthquakes/eventpage/usp000hvpa", "distance_km": 144.3 } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/earthquakes/{id}": { "get": { "operationId": "getEarthquake", "summary": "Get Earthquake", "description": "Get Earthquake endpoint of the Earthquakes API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/earthquakes/get-earthquake" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "us6000jlqa" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "earthquake": { "id": "us6000jlqa", "time": "2023-02-06T10:24:48.811Z", "magnitude": 7.5, "magnitude_type": "mww", "place": "Elbistan earthquake, Kahramanmaras earthquake sequence", "latitude": 38.0106, "longitude": 37.1962, "depth_km": 7.432, "type": "earthquake", "status": "reviewed", "network": "us", "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us6000jlqa" } } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/earthquakes/largest": { "get": { "operationId": "largestEarthquakes", "summary": "Largest Earthquakes", "description": "Largest Earthquakes endpoint of the Earthquakes API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/earthquakes/largest-earthquakes" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "10" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2011" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "year": 2011, "count": 3, "results": [ { "id": "official20110311054624120_30", "time": "2011-03-11T05:46:24.120Z", "magnitude": 9.1, "magnitude_type": "mww", "place": "2011 Great Tohoku Earthquake, Japan", "latitude": 38.297, "longitude": 142.373, "depth_km": 29, "type": "earthquake", "status": "reviewed", "network": "official", "url": "https://earthquake.usgs.gov/earthquakes/eventpage/official20110311054624120_30" }, { "id": "usp000hvpa", "time": "2011-03-11T06:15:40.280Z", "magnitude": 7.9, "magnitude_type": "mwc", "place": "47 km E of ?arai, Japan", "latitude": 36.281, "longitude": 141.111, "depth_km": 42.6, "type": "earthquake", "status": "reviewed", "network": "us", "url": "https://earthquake.usgs.gov/earthquakes/eventpage/usp000hvpa" }, { "id": "usp000hvpg", "time": "2011-03-11T06:25:50.300Z", "magnitude": 7.7, "magnitude_type": "mwc", "place": "272 km ESE of Kamaishi, Japan", "latitude": 38.058, "longitude": 144.59, "depth_km": 18.6, "type": "earthquake", "status": "reviewed", "network": "us", "url": "https://earthquake.usgs.gov/earthquakes/eventpage/usp000hvpg" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/earthquakes": { "get": { "operationId": "searchEarthquakes", "summary": "Search Earthquakes", "description": "Search Earthquakes endpoint of the Earthquakes API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/earthquakes/search-earthquakes" }, "parameters": [ { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2023-01-01" }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2023-12-31" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "20" }, { "name": "max_magnitude", "in": "query", "required": false, "schema": { "type": "string" }, "example": "9.5" }, { "name": "min_magnitude", "in": "query", "required": false, "schema": { "type": "string" }, "example": "6" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "place", "in": "query", "required": false, "schema": { "type": "string" }, "example": "California" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "example": "magnitude" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "total": 102, "page": 1, "limit": 20, "count": 3, "results": [ { "id": "official19060418131226300_12", "time": "1906-04-18T13:12:26.300Z", "magnitude": 7.9, "magnitude_type": "mw", "place": "The 1906 San Francisco, California Earthquake", "latitude": 37.75, "longitude": -122.55, "depth_km": 11.7, "type": "earthquake", "status": "reviewed", "network": "official", "url": "https://earthquake.usgs.gov/earthquakes/eventpage/official19060418131226300_12" }, { "id": "ci3319401", "time": "1952-07-21T11:52:14.540Z", "magnitude": 7.5, "magnitude_type": "mw", "place": "The 1952 Kern County, California Earthquake", "latitude": 34.9582, "longitude": -118.998, "depth_km": 6, "type": "earthquake", "status": "reviewed", "network": "ci", "url": "https://earthquake.usgs.gov/earthquakes/eventpage/ci3319401" }, { "id": "iscgem911811", "time": "1922-01-31T13:17:31.440Z", "magnitude": 7.41, "magnitude_type": "mw", "place": "123 km W of Big Lagoon, California", "latitude": 41.189, "longitude": -125.608, "depth_km": 15, "type": "earthquake", "status": "reviewed", "network": "iscgem", "url": "https://earthquake.usgs.gov/earthquakes/eventpage/iscgem911811" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Create a free key at https://dataandapis.com/sign-up. 500 tokens a month on the Free plan; this API costs 1 token per call." } } }, "security": [ { "ApiKey": [] } ] }