equake

equake is a Python library to intuitively access and handle earthquake data.

This library retrieves earthquake data from the USGS earthquake database and allows you to apply various filters to customise your search.

Benefits

• This library is a convenient wrapper of the USGS Earthquake API, meaning you can communicate with its key functionality in an object-oriented, Pythonic way.
• Plenty of very thorough validation is provided to ensure robustness.
• The abstraction means you can focus on the more important details of your program rather than actually preparing the query string to send a request, for example.
• Both kilometres and miles are supported.
• The code has been rigorously tested for Python 3.7 and above, and major bugs have been fixed.
• The library has been documented fully, with the documentation inside the code.
• There are no third-party dependencies at all, not even the widely used requests library. This makes installation of the library very easy and error-free.

Installation

Pip can be used to easily install this library.

pip install equake

Note: This library supports Python 3.7 and above. Slightly older versions might work, but they have not been tested, so this is not guaranteed. Python 2 is incompatible.

Getting Started

For full details, consult the code documentation.

The main modules available are filt and quake

filt handles the filter functionality, allowing you to create filters to search for earthquakes.

quake allows you to count/get earthquakes from the API, and also holds the Earthquake class.

Create a Filter

To search for earthquakes, you first must create a filter in the filt module.

The overarching filter object is EarthquakeFilter, which consists of sub-filters.

• TimeFilter - filter earthquakes by time of the event, and time updated.
• LocationFilter - filter earthquakes by location (Rectangle/Circle).
• DepthFilter - filter earthquakes by depth.
• MagnitudeFilter - filter earthquakes by magnitude.
• IntensityFilter - filter earthquakes by maximum intensity.
• PAGER Level - filter earthquakes by severity of damage.
• Minimum reports - filter earthquakes by minimum number of reports from the public.

For example, to create a filter for earthquakes with a depth between 100 and 200 kilometres, a magnitude between 5 and 7, a PAGER level of 'orange', and 100 minimum reports, the following code would be used:

from equake import filt

earthquake_filter = filt.EarthquakeFilter(
    filt.DepthFilter(100, 200),
    filt.MagnitudeFilter(5, 7),
    pager_level="orange",
    min_reports=100
)

For more complex use cases, see the examples folder and the documentation.

Count or Get Earthquakes

Once you have a filter, you can count/get earthquakes by using the quake module.

To count/get the number of earthquakes in a simple way, this is the code you would use.

from equake import filt, quake

earthquake_filter = filt.EarthquakeFilter() # Just for example purposes.
earthquake_count = quake.count(earthquake_filter)
earthquakes = quake.get(earthquake_filter)

Again, for more complex use cases, see the examples folder and the documentation.