usgs-earthquake-api

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-api

Usage

In your code:

const api = require('usgs-earthquake-api');

Interface parameters /application.json

const parameters = await api.application.getInterfaceParameters();

Result

{
  "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()

Result

{
  "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()

Result

[
  "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()

Result

[
  "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 });

Supported parameters

Result

{
  "count": 4983,
  "maxAllowed": 20000
}

Query /query

const earthquakes = await api.query.earthquakes({ limit: 1, maxdepth: 5 });

Supported parameters

Result

{
  "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

{
  "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	Integer[1,∞]	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	Integer[1,∞]	null	Limit to events with this many DYFI responses
mingap	Decimal[0,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)
}
 

Result

Error: Bad limit value "50000". Valid values are 0 <= limit <= 20000