https://github.com/nexxus-vi/ingv_quake
Ruby gem that simplifies access to earthquake event data from the INGV's fdsnws-event API!
https://github.com/nexxus-vi/ingv_quake
earthquakes fsdn ingv quakeml ruby ruby-gem ruby-on-rails seismic-data seismology
Last synced: 8 months ago
JSON representation
Ruby gem that simplifies access to earthquake event data from the INGV's fdsnws-event API!
- Host: GitHub
- URL: https://github.com/nexxus-vi/ingv_quake
- Owner: nexxus-vi
- License: mit
- Created: 2023-05-17T15:27:41.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2023-05-17T15:49:23.000Z (about 3 years ago)
- Last Synced: 2025-02-28T13:18:06.962Z (over 1 year ago)
- Topics: earthquakes, fsdn, ingv, quakeml, ruby, ruby-gem, ruby-on-rails, seismic-data, seismology
- Language: Ruby
- Homepage: https://rubygems.org/gems/ingv_quake
- Size: 42 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# IngvQuake
### 🫨 Get details about Earthquake events.
This gem is a wrapper around the [fdsnws-event api](https://webservices.ingv.it/swagger-ui/dist/?url=https://ingv.github.io/openapi/fdsnws/event/0.0.1/event.yaml#) provided by the [INGV](https://www.ingv.it/) with some additions to improve the inspection of events and their data.
[](https://rubygems.org/gems/ingv_quake)
[](https://github.com/nexxus-vi/ingv_quake/actions/workflows/ci.yml)
[](https://coveralls.io/github/nexxus-vi/ingv_quake?branch=master)
[](https://rubydoc.info/gems/ingv_quake)
### ⚠ Requirements
- Ruby 2.6+
## ⚙️ Installation
Add this line to your application's Gemfile:
```ruby
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:
```ruby
client = IngvQuake::Client.new
```
You can also provide your preferred adapter for the underlying Faraday connection:
```ruby
client = IngvQuake::Client.new(adapter: httpx)
```
A curated list of supported adapters can be found in the [awesome-faraday](https://github.com/lostisland/awesome-faraday#adapters) repo
- #### Get Events Data
Use the get_events method to initialize an EventResource and then fetch earthquake events from the API:
```ruby
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`](https://rubydoc.info/gems/ingv_quake/IngvQuake/BasicInfoEvent)
- #### Xml response
The `xml` response has all the information about an event.
[Here an example](https://webservices.ingv.it/fdsnws/event/1/query?starttime=2023-04-25T00:00:00&endtime=2023-05-01T23:59:59&limit=5).
This response is parsed as a [`FullInfoEvent`](https://rubydoc.info/gems/ingv_quake/IngvQuake/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:
```ruby
events.between_dates(starttime: '2023-05-08', endtime: DateTime.now)
```
#### 🎚️ By magnitude range:
```ruby
events.between_magnitude(minmag: 3.5, maxmag: 6.0)
```
#### ⌚️ Within the last hour:
```ruby
events.within_last_hour
```
#### ☝🏼 Custom Query
Use the `where` method to create a custom query with specific parameters:
```ruby
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](https://github.com/alexreisner/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:
### For a full list of methods and params, take a look at the [full documentation](https://rubydoc.info/gems/ingv_quake/IngvQuake/EventResource)
## 🛟 Contributing
Bug reports and pull requests are welcome on [GitHub](https://github.com/nexxus-vi/ingv_quake/issues).
## 📃 License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).