Skip to content

Ruby gem that simplifies access to earthquake event data from the INGV's fdsnws-event API!

License

Notifications You must be signed in to change notification settings

nexxus-vi/ingv_quake

Repository files navigation

IngvQuake

🫨 Get details about Earthquake events.

This gem is a wrapper around the fdsnws-event api provided by the INGV with some additions to improve the inspection of events and their data.

Gem GitHub Workflow Status Coveralls Rubydoc

⚠ Requirements

  • Ruby 2.6+

⚙️ Installation

Add this line to your application's Gemfile:

gem 'ingv_quake'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install ingv_quake

📝 Usage

  • Initialize the Client

Create a new instance of the IngvQuake::Client class to interact with the INGV Earthquake web services API:

client = IngvQuake::Client.new

You can also provide your preferred adapter for the underlying Faraday connection:

client = IngvQuake::Client.new(adapter: httpx)

A curated list of supported adapters can be found in the awesome-faraday repo

  • Get Events Data

Use the get_events method to initialize an EventResource and then fetch earthquake events from the API:

events = client.get_events
events.within_last_hour

The Ingv api can return 2 kinds of response format: text or xml (default).

  • Text response

    The text response is a simplified representation of an event, containing basic information:

    #EventID|Time|Latitude|Longitude|Depth/Km|Author|Catalog|Contributor|ContributorID|MagType|Magnitude|MagAuthor|EventLocationName|EventType
    34726341|2023-04-19T14:50:48.640000|43.8972|11.9382|14.1|SURVEY-INGV||||ML|0.9|--|5 km NW Bagno di Romagna (FC)|earthquake
    

    This response is parsed as a BasicInfoEvent

  • Xml response

    The xml response has all the information about an event. Here an example.

    This response is parsed as a FullInfoEvent

You can choose which level of information to get by passing or omitting the format: 'text' param when querying for events.

🧐 Query Events with Filters

The EventResource class provides several methods for querying events with specific filters. Some examples:

📆 By date range:

events.between_dates(starttime: '2023-05-08', endtime: DateTime.now)

🎚️ By magnitude range:

events.between_magnitude(minmag: 3.5, maxmag: 6.0)

⌚️ Within the last hour:

events.within_last_hour

☝🏼 Custom Query

Use the where method to create a custom query with specific parameters:

events.where(starttime: '2023-04-25', endtime: '2023-05-01', minmag: 4.5, maxmag: 6.0)

events.where(address: 'Roma, Via Condotti', maxradiuskm: 400, maxmag: 6.0)

Note: the address param is an addition of the ingv_quake gem, you won't find it in the original api specifications. Under the hood the string address is transformed into lat and long params by the geocoder gem.

ShakeMap

ShakeMap attributes are images that provides near-time maps of ground shaking for Magnitude >= 3.0 earthquakes in Italy and neighbouring areas. An example of intensity shake map is this:

“intensity

For a full list of methods and params, take a look at the full documentation

🛟 Contributing

Bug reports and pull requests are welcome on GitHub.

📃 License

The gem is available as open source under the terms of the MIT License.