1.0.32 • Published 4 years ago
usgs-earthquake-api v1.0.32
The "what?"
This is the usgs.gov earthquake catalog API wrapper for NodeJS. It provides methods for accessing the data from all available endpoints:
- application.json (request known enumerated parameter values for the interface)
- application.wadl (request WADL for the interface)
- catalogs (request available catalogs)
- contributors (request available contributors)
- count (to perform a count on a data request. Count uses the same parameters as the query method)
- query (to submit a data request)
- version (request full service version number)
The "why"
While working on one of my "pet" projects I was looking for the source of real-time earthquake data. Quick search on the internet brought me to the usgs.gov website which contains all the data I needed. They also provide a free API for developers to access their data.
Since my project's back-end is written in NodeJS I started looking for a wrapper package for this service. Unfortunatelly I didn't find any up-to-date and still-maintained ready solution.
Even tho I only needed a peace of USGS earthquake catalog API functionality, I decided to implement an NodeJS wrapper for all of their available endpoints and move out the code into a separate package.
The "how"
Installation
npm install --save usgs-earthquake-apiUsage
In your code:
const api = require('usgs-earthquake-api');Interface parameters /application.json
const parameters = await api.application.getInterfaceParameters();{
"catalogs": [
"38457511",
"=c",
"ak",
"at",
"atlas",
"av",
"cdmg",
"cgs",
"choy",
"ci",
"cidev",
"dr",
"duputel",
"eqh",
"ew",
"ew_dm",
"gcmt",
"gsc",
"hv",
"id",
"is",
"iscgem",
"iscgemsup",
"ismpkansas",
"ld",
"mb",
"nc",
"ne",
"nm",
"nn",
"official",
"official19631013051759_30",
"ok",
"pr",
"pt",
"sc",
"se",
"unknown",
"us",
"ushis",
"uu",
"uw"
],
"contributors": [
"admin",
"ak",
"at",
"atlas",
"av",
"cgs",
"ci",
"ew",
"hv",
"ismp",
"ld",
"mb",
"nc",
"nm",
"nn",
"np",
"official",
"ok",
"pr",
"pt",
"se",
"us",
"uu",
"uw"
],
"producttypes": [
"associate",
"cap",
"deleted-text",
"disassociate",
"dyfi",
"earthquake-name",
"eq-location-map",
"finite-fault",
"focal-mechanism",
"general-header",
"general-link",
"general-text",
"geoserve",
"ground-failure",
"historical-moment-tensor-map",
"historical-seismicity-map",
"image",
"impact-link",
"impact-text",
"internal-origin",
"isoseismal-map",
"losspager",
"losspager-admin",
"moment-tensor",
"moreinformation",
"nearby-cities",
"oaf",
"origin",
"p-wave-travel-times",
"phase-data",
"poster",
"scitech-link",
"scitech-text",
"shake-alert",
"shakemap",
"significance",
"tectonic-summary",
"touch",
"trump",
"trump-cap",
"trump-dyfi",
"trump-general-link",
"trump-general-text",
"trump-geoserve",
"trump-ground-failure",
"trump-impact-text",
"trump-losspager",
"trump-moment-tensor",
"trump-nearby-cities",
"trump-origin",
"trump-phase-data",
"trump-shakemap",
"trump-tectonic-summary",
"unassociated-amplitude"
],
"eventtypes": [
"acoustic noise",
"acoustic_noise",
"anthropogenic_event",
"building collapse",
"chemical explosion",
"chemical_explosion",
"collapse",
"earthquake",
"eq",
"experimental explosion",
"explosion",
"ice quake",
"induced or triggered event",
"industrial explosion",
"landslide",
"meteor",
"meteorite",
"mine collapse",
"mine_collapse",
"mining explosion",
"mining_explosion",
"not reported",
"not_reported",
"nuclear explosion",
"nuclear_explosion",
"other event",
"other_event",
"quarry",
"quarry blast",
"quarry_blast",
"rock burst",
"Rock Slide",
"rockslide",
"rock_burst",
"snow_avalanche",
"sonic boom",
"sonicboom",
"sonic_boom",
"volcanic eruption",
"volcanic explosion"
],
"magnitudetypes": [
"2",
"4",
"fa",
"H",
"lg",
"m",
"ma",
"mb",
"MbLg",
"mb_lg",
"mc",
"Md",
"mdl",
"Me",
"mfa",
"mh",
"Mi",
"mint",
"ml",
"mlg",
"mlr",
"mlv",
"Ms",
"ms_20",
"Mt",
"mun",
"mw",
"mwb",
"mwc",
"mwp",
"mww",
"no",
"uk",
"Unknown"
]
}WADL for interface /application.wadl
const wadlData = await api.applicationWadl.getWadl(){
"application": {
"resources": [
{
"base": "https://earthquake.usgs.gov/fdsnws/event/1/",
"resource": [
{
"path": "version",
"method": [
{
"id": "version",
"name": "GET",
"response": [
{
"status": "200",
"representation": [
{
"mediaType": "text/plain"
}
]
}
]
}
]
},
{
"path": "catalogs",
"method": [
{
"id": "catalogs",
"name": "GET",
"response": [
{
"status": "200",
"representation": [
{
"mediaType": "application/xml"
}
]
}
]
}
]
},
{
"path": "contributors",
"method": [
{
"id": "contributors",
"name": "GET",
"response": [
{
"status": "200",
"representation": [
{
"mediaType": "application/xml"
}
]
}
]
}
]
},
{
"path": "application.wadl",
"method": [
{
"id": "application.wadl",
"name": "GET",
"response": [
{
"status": "200",
"representation": [
{
"mediaType": "application/xml"
}
]
}
]
}
]
},
{
"path": "query",
"method": [
{
"id": "query",
"name": "GET",
"response": [
{
"status": "200",
"representation": [
{
"mediaType": "application/xml",
"element": "q:quakeml"
},
{
"mediaType": "text/csv"
},
{
"mediaType": "application/vnd.google-earth.kml+xml"
},
{
"mediaType": "text/javascript"
},
{
"mediaType": "application/json"
}
]
}
],
"request": [
{
"param": [
{
"name": "starttime",
"style": "query",
"type": "xs:dateTime"
},
{
"name": "endtime",
"style": "query",
"type": "xs:dateTime"
},
{
"name": "updatedafter",
"style": "query",
"type": "xs:dateTime"
},
{
"name": "minlatitude",
"style": "query",
"type": "xs:double",
"default": "-90"
},
{
"name": "maxlatitude",
"style": "query",
"type": "xs:double",
"default": "90"
},
{
"name": "minlongitude",
"style": "query",
"type": "xs:double",
"default": "-180"
},
{
"name": "minlongitude",
"style": "query",
"type": "xs:double",
"default": "180"
},
{
"name": "latitude",
"style": "query",
"type": "xs:double",
"default": "0"
},
{
"name": "longitude",
"style": "query",
"type": "xs:double",
"default": "0"
},
{
"name": "minradius",
"style": "query",
"type": "xs:double",
"default": "0"
},
{
"name": "maxradius",
"style": "query",
"type": "xs:double",
"default": "180"
},
{
"name": "mindepth",
"style": "query",
"type": "xs:double"
},
{
"name": "maxdepth",
"style": "query",
"type": "xs:double"
},
{
"name": "minmagnitude",
"style": "query",
"type": "xs:double"
},
{
"name": "maxmagnitude",
"style": "query",
"type": "xs:double"
},
{
"name": "magnitudetype",
"style": "query",
"type": "xs:string"
},
{
"name": "includeallmagnitudes",
"style": "query",
"type": "xs:boolean"
},
{
"name": "includeallorigins",
"style": "query",
"type": "xs:boolean"
},
{
"name": "includearrivals",
"style": "query",
"type": "xs:boolean"
},
{
"name": "eventid",
"style": "query",
"type": "xs:string"
},
{
"name": "limit",
"style": "query",
"type": "xs:integer"
},
{
"name": "offset",
"style": "query",
"type": "xs:integer",
"default": "1"
},
{
"name": "orderby",
"style": "query",
"default": "time",
"option": [
{
"value": "time"
},
{
"value": "time-asc"
},
{
"value": "magnitude"
},
{
"value": "magnitude-asc"
}
]
},
{
"name": "contributor",
"style": "query",
"type": "xs:string"
},
{
"name": "catalog",
"style": "query",
"type": "xs:string"
},
{
"name": "format",
"style": "query",
"default": "quakeml",
"option": [
{
"value": "quakeml",
"mediaType": "application/xml"
},
{
"value": "csv",
"mediaType": "text/csv"
},
{
"value": "geojson",
"mediaType": "application/json"
},
{
"value": "kml",
"mediaType": "application/vnd.google-earth.kml+xml"
}
]
},
{
"name": "callback",
"style": "query",
"mediaType": "text/javascript"
},
{
"name": "kmlcolorby",
"style": "query",
"default": "age",
"option": [
{
"value": "age"
},
{
"value": "depth"
}
]
},
{
"name": "kmlanimated",
"style": "query",
"type": "xs:boolean",
"default": "false"
},
{
"name": "eventtype",
"style": "query",
"type": "xs:string"
},
{
"name": "reviewstatus",
"style": "query",
"option": [
{
"value": "automatic"
},
{
"value": "reviewed"
}
]
},
{
"name": "minmmi",
"style": "query",
"type": "xs:double"
},
{
"name": "maxmmi",
"style": "query",
"type": "xs:double"
},
{
"name": "mincdi",
"style": "query",
"type": "xs:double"
},
{
"name": "maxcdi",
"style": "query",
"type": "xs:double"
},
{
"name": "minfelt",
"style": "query",
"type": "xs:integer"
},
{
"name": "alertlevel",
"style": "query",
"default": "*",
"option": [
{
"value": "green"
},
{
"value": "yellow"
},
{
"value": "orange"
},
{
"value": "red"
},
{
"value": "*"
}
]
},
{
"name": "mingap",
"style": "query",
"type": "xs:double"
},
{
"name": "maxgap",
"style": "query",
"type": "xs:double"
},
{
"name": "minsig",
"style": "query",
"type": "xs:integer"
},
{
"name": "maxsig",
"style": "query",
"type": "xs:integer"
},
{
"name": "producttype",
"style": "query",
"option": [
{
"value": "moment-tensor"
},
{
"value": "focal-mechanism"
},
{
"value": "shakemap"
},
{
"value": "losspager"
},
{
"value": "dyfi"
}
]
}
]
}
]
}
]
}
]
}
]
}
}Available catalogs /catalogs
const catalogs = await api.catalogs.getCatalogs()[
"38457511",
"=c",
"ak",
"at",
"atlas",
"av",
"cdmg",
"cgs",
"choy",
"ci",
"cidev",
"dr",
"duputel",
"eqh",
"ew",
"ew_dm",
"gcmt",
"gsc",
"hv",
"id",
"is",
"iscgem",
"iscgemsup",
"ismpkansas",
"ld",
"mb",
"nc",
"ne",
"nm",
"nn",
"official",
"official19631013051759_30",
"ok",
"pr",
"pt",
"sc",
"se",
"unknown",
"us",
"ushis",
"uu",
"uw"
]Available contributors /contributors
const contributors = await api.contributors.getContributors()[
"admin",
"ak",
"at",
"atlas",
"av",
"cgs",
"ci",
"ew",
"hv",
"ismp",
"ld",
"mb",
"nc",
"nm",
"nn",
"np",
"official",
"ok",
"pr",
"pt",
"se",
"us",
"uu",
"uw"
]Count on data request /count
const count = await api.count.getCount({ maxdepth: 5 });{
"count": 4983,
"maxAllowed": 20000
}Query /query
const earthquakes = await api.query.earthquakes({ limit: 1, maxdepth: 5 });{
"type": "FeatureCollection",
"metadata": {
"generated": 1596245138000,
"url": "https://earthquake.usgs.gov/fdsnws/event/1/query?limit=1&maxdepth=5&format=geojson",
"title": "USGS Earthquakes",
"status": 200,
"api": "1.10.3",
"limit": 1,
"offset": 1,
"count": 1
},
"features": [
{
"type": "Feature",
"properties": {
"mag": 0.8,
"place": "9km WNW of Cobb, CA",
"time": 1596244682970,
"updated": 1596245043536,
"tz": null,
"url": "https://earthquake.usgs.gov/earthquakes/eventpage/nc73436721",
"detail": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=nc73436721&format=geojson",
"felt": null,
"cdi": null,
"mmi": null,
"alert": null,
"status": "automatic",
"tsunami": 0,
"sig": 10,
"net": "nc",
"code": "73436721",
"ids": ",nc73436721,",
"sources": ",nc,",
"types": ",nearby-cities,origin,phase-data,scitech-link,",
"nst": 16,
"dmin": 0.009233,
"rms": 0.02,
"gap": 63,
"magType": "md",
"type": "earthquake",
"title": "M 0.8 - 9km WNW of Cobb, CA"
},
"geometry": {
"type": "Point",
"coordinates": [
-122.8236694,
38.8383331,
1.81
]
},
"id": "nc73436721"
}
]
}Service version /version
const version = await api.version.getVersion();{
"result": "1.10.3"
}Supported parameters
api.count.getCount and api.query.earthquakes methods accept an object with following possible
properties:
| property | type | default | description |
|---|---|---|---|
| endtime | String | present time | Limit to events on or before the specified end time (ISO8601 format) |
| starttime | String | NOW - 30 days | Limit to events on or after the specified start time (ISO8601 format) |
| updatedafter | String | null | Limit to events updated after the specified time (ISO8601 format) |
| minlatitude | Decimal -90,90 degrees | -90 | Limit to events with a latitude larger than the specified minimum |
| minlongitude | Decimal -360,360 degrees | -180 | Limit to events with a longitude larger than the specified minimum |
| maxlatitude | -90,90 degrees | 90 | Limit to events with a latitude smaller than the specified maximum |
| maxlongitude | Decimal -360,360 degrees | 180 | Limit to events with a longitude smaller than the specified maximum |
| latitude | Decimal -90,90 degrees | null | Specify the latitude to be used for a radius search |
| longitude | Decimal -180,180 degrees | null | Specify the longitude to be used for a radius search |
| maxradius | Decimal 0, 180 degrees | 180 | Limit to events within the specified maximum number of degrees from the geographic point defined by the latitude and longitude parameters |
| maxradiuskm | Decimal 0, 20001.6 km | 20001.6 | Limit to events within the specified maximum number of kilometers from the geographic point defined by the latitude and longitude parameters |
| catalog | String | null | Limit to events from a specified catalog |
| contributor | String | null | Limit to events contributed by a specified contributor |
| eventid | String | null | Select a specific event by ID |
| includeallmagnitudes | Boolean | false | Specify if all magnitudes for the event should be included |
| includeallorigins | Boolean | false | Specify if all origins for the event should be included |
| includearrivals | Boolean | false | Specify if phase arrivals should be included |
| includedeleted | Boolean, or only | false | Specify if deleted products and events should be included. The value only returns only deleted events. |
| includesuperseded | Boolean | false | Specify if superseded products should be included. This also includes all deleted products, and is mutually exclusive to the includedeleted parameter. |
| limit | Integer 1,20000 | null | Limit the results to the specified number of events |
| maxdepth | Decimal -100, 1000 | 1000 | Limit to events with depth less than the specified maximum |
| maxmagnitude | Decimal | null | Limit to events with a magnitude smaller than the specified maximum |
| mindepth | Decimal -100, 1000 km | -100 | Limit to events with depth more than the specified minimum |
| minmagnitude | Decimal | null | Limit to events with a magnitude larger than the specified minimum |
| offset | Integer1,∞ | 1 | Return results starting at the event count specified, starting at 1 |
| orderby | String | time | Order the results. The allowed values are: time, time-asc, magnitude, magnitude-asc |
| alertlevel | String | null | Limit to events with a specific PAGER alert level. The allowed values are: green, yellow, orange, red |
| eventtype | String | null | Limit to events of a specific type |
| maxcdi | Decimal 0,12 | null | Maximum value for Maximum Community Determined Intensity reported by DYFI |
| maxgap | Decimal 0,360 degrees | null | Limit to events with no more than this azimuthal gap |
| maxmmi | Decimal 0,12 | null | Maximum value for Maximum Modified Mercalli Intensity reported by ShakeMap |
| maxsig | Integer | null | Limit to events with no more than this significance |
| mincdi | Decimal | null | Minimum value for Maximum Community Determined Intensity reported by DYFI |
| minfelt | Integer1,∞ | null | Limit to events with this many DYFI responses |
| mingap | Decimal0,360 degrees | null | Limit to events with no less than this azimuthal gap |
| minsig | Integer | null | Limit to events with no less than this significance |
| producttype | String | null | Limit to events that have this type of product associated |
| productcode | String | null | Return the event that is associated with the productcode; The event will be returned even if the productcode is not the preferred code for the event |
| reviewstatus | String | all | Limit to events with a specific review status; The different review statuses are: automatic, reviewed |
Error handling
Wrapper automagically processes all the API request failures and re-throws an error with a descriptive message.
From documentation about the limit parameter:
Limit the results to the specified number of events. NOTE: The service limits queries to 20000, and any that exceed this limit will generate a HTTP response code "400 Bad Request".
Example:
try {
const earthquakes = await api.query.earthquakes({ limit: 50000 })
} catch (e) {
console.log(e.message)
}Error: Bad limit value "50000". Valid values are 0 <= limit <= 200001.0.32
4 years ago
1.0.31
4 years ago
1.0.29
4 years ago
1.0.30
4 years ago
1.0.28
4 years ago
1.0.26
4 years ago
1.0.27
4 years ago
1.0.24
4 years ago
1.0.22
4 years ago
1.0.21
4 years ago
1.0.23
4 years ago
1.0.19
4 years ago
1.0.18
4 years ago
1.0.17
4 years ago
1.0.16
4 years ago
1.0.15
4 years ago
1.0.14
4 years ago
1.0.13
4 years ago
1.0.12
4 years ago
1.0.11
4 years ago
1.0.10
4 years ago
1.0.8
4 years ago
1.0.7
4 years ago
1.0.5
4 years ago
1.0.4
4 years ago
1.0.3
4 years ago
1.0.2
4 years ago
1.0.1
4 years ago
1.0.0
4 years ago