Lightweight python API to USGS earthquake dataset. API Docs are located here
Clone the repo to your system and install
$ git clone https://github.com/BlakeJC94/quaker.git
$ cd quaker
$ pip install .This package comes equipped with a batteries-included CLI interface for downloading the latest earthquake event data in CSV, GeoJSON, and plain text format from the USGS database.
usage: quaker [-h] [--format FORMAT] [--endtime ENDTIME] [--starttime STARTTIME] [--updatedafter UPDATEDAFTER]
[--minlatitude MINLATITUDE] [--minlongitude MINLONGITUDE] [--maxlatitude MAXLATITUDE]
[--maxlongitude MAXLONGITUDE] [--latitude LATITUDE] [--longitude LONGITUDE] [--maxradius MAXRADIUS]
[--maxradiuskm MAXRADIUSKM] [--catalog CATALOG] [--contributor CONTRIBUTOR] [--eventid EVENTID]
[--includeallmagnitudes] [--includeallorigins] [--includedeleted] [--includesuperseded]
[--maxmagnitude MAXMAGNITUDE] [--mindepth MINDEPTH] [--minmagnitude MINMAGNITUDE] [--orderby ORDERBY]
[argfile]
positional arguments:
argfile Optional comma separated file with API arguments
options:
-h, --help show this help message and exit
Formats arguments:
--format FORMAT (default: quakeml) Specify the output format, one of csv, geojson, kml, quakeml, csv, text,
xml
Time arguments:
--endtime ENDTIME (default: present time) Limit to events on or before the specified end time. NOTE: All times
use ISO8601 Date/Time format. Unless a timezone is specified, UTC is assumed
--starttime STARTTIME
(default: NOW - 30 days) Limit to events on or after the specified start time. NOTE: All
times use ISO8601 Date/Time format. Unless a timezone is specified, UTC is assumed
--updatedafter UPDATEDAFTER
(default: null) Limit to events updated after the specified time. NOTE: All times use
ISO8601 Date/Time format. Unless a timezone is specified, UTC is assumed
Location (rectangle) arguments:
--minlatitude MINLATITUDE
(default: -90) [-90,90] degrees, Limit to events with a latitude larger than the specified
minimum. NOTE: min values must be less than max values
--minlongitude MINLONGITUDE
(default: -180) [-360,360] degrees, Limit to events with a longitude larger than the
specified minimum. NOTE: rectangles may cross the date line by using a minlongitude < -180
or maxlongitude > 180. NOTE: min values must be less than max values
--maxlatitude MAXLATITUDE
(default: 90) [-90,90] degrees, Limit to events with a latitude smaller than the specified
maximum. NOTE: min values must be less than max values
--maxlongitude MAXLONGITUDE
(default: 180) [-360,360] degrees, Limit to events with a longitude smaller than the
specified maximum. NOTE: rectangles may cross the date line by using a minlongitude < -180
or maxlongitude > 180. NOTE: min values must be less than max values
Location (circle) arguments:
--latitude LATITUDE (default: null) [-90,90] degrees, Specify the latitude to be used for a radius search
--longitude LONGITUDE
(default: null) [-180,180] degrees, Specify the longitude to be used for a radius search
--maxradius MAXRADIUS
(default: 180) [0, 180] degrees, Limit to events within the specified maximum number of
degrees from the geographic point defined by the latitude and longitude parameters. NOTE:
This option is mutually exclusive with maxradiuskm and specifying both will result in an
error
--maxradiuskm MAXRADIUSKM
(default: 20001.6) [0, 20001.6] km, Limit to events within the specified maximum number of
kilometers from the geographic point defined by the latitude and longitude parameters. NOTE:
This option is mutually exclusive with maxradius and specifying both will result in an error
Other arguments:
--catalog CATALOG (default: null) Limit to events from a specified catalog. Use the Catalogs Method to find
available catalogs. NOTE: when catalog and contributor are omitted, the most preferred
information from any catalog or contributor for the event is returned
--contributor CONTRIBUTOR
(default: null) Limit to events contributed by a specified contributor. Use the Contributors
Method to find available contributors. NOTE: when catalog and contributor are omitted, the
most preferred information from any catalog or contributor for the event is returned
--eventid EVENTID (default: null) Select a specific event by ID; event identifiers are data center specific.
NOTE: Selecting a specific event implies includeallorigins, includeallmagnitudes, and,
additionally, associated moment tensor and focal-mechanisms are included
--includeallmagnitudes
(default: false) Specify if all magnitudes for the event should be included, default is data
center dependent but is suggested to be the preferred magnitude only. NOTE: because
magnitudes and origins are strongly associated, this parameter is interchangeable with
includeallmagnitude
--includeallorigins (default: false) Specify if all origins for the event should be included, default is data
center dependent but is suggested to be the preferred origin only. NOTE: because magnitudes
and origins are strongly associated, this parameter is interchangable with
includeallmagnitude
--includedeleted (default: false) Specify if deleted products and events should be included. The value only
returns only deleted events. Deleted events otherwise return the HTTP status 409 Conflict.
NOTE: Only supported by the csv and geojson formats, which include status
--includesuperseded (default: false) Specify if superseded products should be included. This also includes all
deleted products, and is mutually exclusive to the includedeleted parameter. NOTE: Only
works when specifying eventid parameter
--maxmagnitude MAXMAGNITUDE
(default: null) Limit to events with a magnitude smaller than the specified maximum
--mindepth MINDEPTH (default: -100) [-100, 1000] km Limit to events with depth more than the specified minimum
--minmagnitude MINMAGNITUDE
(default: null) Limit to events with a magnitude larger than the specified minimum
--orderby ORDERBY Order the results. The allowed values are: time, time-asc, magnitude, magnitude-asc
Run quaker download and specify the parameters as keyword arguments and pipe the output to any
location:
$ quaker download --format csv --starttime 2022-08-01 --endtime 2022-09-01 > earthquake_data.csvFor more details on the available query parameters, use quaker --help or view the
USGS documentation.
Using the python API is also fairly straight-forward:
>>> import io
>>> import pandas as pd
>>> from quaker_db import Client
>>> client = Client()
# An empty query defaults to all events in the last 30 days
>>> recent_events = client.execute(format="csv")
>>> df = pd.read_csv(io.StringIO(recent_events))
# Large multi-page queries can also be handled
>>> events_from_last_5_months = client.execute(
... format="csv",
... starttime="2022-05-01",
... endtime="2022-10-01",
... )
>>> df = pd.read_csv(io.StringIO(events_from_last_5_months))
# You can filter results by location using the API
>>> events_in_august_in_120km_within_tokyo_above_mag_3 = client.execute(
... forma="csv",
... starttime="2022-08-01",
... endtime="2022-09-01",
... latitude=35.652832,
... longitude=139.839478,
... maxradiuskm=120.0,
... minmagnitude=3.0,
... }
# See `help(quaker_db.Query)` and https://earthquake.usgs.gov/fdsnws/event/1/ for more detailsThis is a small personal project, but pull requests are most welcome!
- Code is styled using
[black](https://github.com/psf/black)(pip install black) - Code is linted with
ruff(pip install ruff) - Requirements are managed using
poetry - Semantic versioning is used in this repo
- Major version: rare, substantial changes that break backward compatibility
- Minor version: most changes - new features, models or improvements
- Patch version: small bug fixes and documentation-only changes
Virtual environment handling by poetry is preferred:
# in the project directory
$ poetry install
$ poetry shell