Earthquakes

URL Path

https://data.api.xweather.com/earthquakes/

Data Coverage

Global

Update Interval

Near real-time

Time Range

From 1568-01-01

The earthquake data set provides information on US and international earthquakes, as provided by the USGS. This data includes location, magnitude, depth, and more. Earthquake archive data is available from 1945 and can be retrieved up to one year at a time.

Requests

Every request to the endpoint must include one of the supported actions in the url.

https://data.api.xweather.com/earthquakes/{action}?client_id={client_id}&client_secret={client_secret}&{params}

Supported Actions

The following actions are supported with the /earthquakes endpoint:

Action	Description
:id	Type: stringTypically used for passing a geographical location name or identifier such as city name, lat/long, or even US and Canadian postal codes. Learn more.
closest	Type: stringBased on a location search, the results will be returned in order from closest to farthest. Learn more.
within	Type: stringUses a circle or polygon, define an area to search for results. Learn more.
search	Type: stringA generalized action that is determined with the endpoints query parameters. Learn more.
affects	Type: stringReturns a list of locations that are currently affected by a weather event. Criteria for the location(s) can be determined in your query parameters. Learn more.

Response

The following is an example of what each object in the response will consist of. Depending on your requested action, the response may contain multiple instances of this object within an array.

Properties

loc (object)

The location of the record.

loc.long (number)

The place or nearest place to the record.

loc.lat (number)

The latitude coordinate of the record.

report (object)

Object containing the earthquake report.

report.id (string)

The USGS earthquake ID

report.timestamp (number)

UNIX timestamp when the event took place.

report.dateTimeISO (string)

The date and time in ISO-8601 format of the event.

report.updatedTimestamp (number)

The UNIX timestamp when the event was last updated.

report.updatedDateTimeISO (string)

The date and time in ISO-8601 format when the event was last updated.

report.mag (number)

The magnitude of the earthquake.

report.type (string)

The earthquake category:
- mini: 0 - 2.9
- minor: 3 - 3.9
- light: 4 - 4.9
- moderate: 5 - 5.9
- strong: 6 - 6.9
- major: 7 - 7.9
- great: 8.0+

report.depthKM (number)

The depth of the earthquake in kilometers.

report.depthMI (number)

The depth of the earthquake in miles.

report.region (string)

The region of the earthquake.

report.location (string)

The location of the earthquake.

place (object)

Object containing the place information.

place.name (string)

The place or nearest place to the record.

place.state (string)

The state abbreviation in which the response is located. This may be null or an empty string depending on the country.

place.country (string)

The 2 letter ISO-3166 country abbreviation in which the response is located.

profile (object)

Object containing information about the location or event.

profile.tz (string)

Timezone name of the location, such as America/New_York.

profile.elev (number)

(Deprecated) The elevation of the location in meters. Please use elevM or elevFT instead.

profile.elevM (number)

The elevation of the location in meters.

profile.elevFT (number)

The elevation of the location in feet.

relativeTo (object)

Object containing information about the location used for the request compared to the record"s actual location.

relativeTo.lat (number)

Latitude coordinate of the location used for the request. This may be different than the record"s loc.lat value if there was no record exactly at the request location.

relativeTo.long (number)

Longitude coordinate of the location used for the request. This may be different than the record"s loc.long value if there was no record exactly at the request location.

relativeTo.bearing (number)

Bearing in degrees of the record"s location relative to the location used for the request.

relativeTo.bearingENG (string)

Cardinal direction of the record relative to the location used for the request.

relativeTo.distanceKM (number)

Distance, in kilometers, from the requested location to the record"s actual location.

relativeTo.distanceMI (number)

Distance, in miles, from the requested location to the record"s actual location.

[
  {
    "loc": {
      "long": -150.3594,
      "lat": 63.182
    },
    "report": {
      "id": "ak023fztqut5",
      "timestamp": 1702576890,
      "dateTimeISO": "2023-12-14T09:01:30-09:00",
      "updatedTimestamp": 1702576890,
      "updatedDateTimeISO": "2023-12-14T09:01:30-09:00",
      "mag": 1.8,
      "type": "mini",
      "depthKM": 94.8,
      "depthMI": 58.91,
      "region": "74 km WSW of Cantwell, Alaska",
      "location": "74 km WSW of Cantwell, Alaska"
    },
    "place": {
      "name": "cantwell",
      "state": "ak",
      "country": "us"
    },
    "profile": {
      "tz": "America/Anchorage",
      "elev": 669,
      "elevM": 669,
      "elevFT": 2195
    }
  }
]

Endpoints