Unofficial python library for working with Global Disaster Alert and Coordination System (GDACS) API.
If you already have pip
installed, use the commands below to install the gdacs-api
python library.
From pypi.org:
(venv)$ pip install gdacs-api
From GitHub with pip:
(venv)$ pip install git+https://github.com/Kamparia/gdacs-api.git
From cloned GitHub repo for development:
(venv)$ git clone https://github.com/Kamparia/gdacs-api.git
(venv)$ cd ./gdacs-api
(venv)$ pip install -e .
The installation of gdacs-api v.2.0.0
package depends on the following packages.
- Python >=3.6
- Requests >=2.10.0
- Xmltodict
- Cachetools
- Pydantic
To access the API functionalities of this libray, you need to import it into the Python script where it will be called.
from gdacs.api import GDACSAPIReader
You need to setup an API client to interact with the GDACS API. You can do so by simply using the code snippet below.
client = GDACSAPIReader()
Use the code snippet below to retrieve latets disaster events from the GDACS RSS Feed.
events = client.latest_events() # all recent events
events = client.latest_events(limit=10) # 10 most events
You can filter event by the different types of natural disasters.
tc_events = client.latest_events(event_type="TC")
fl_events = client.latest_events(event_type="FL")
Optional parameters:
event_type
(str): TC (Tropical Cyclones), EQ (Earthquakes), FL (Floods), VO (Volcanoes), WF (Wild Fires) and DR (Droughts)limit
(int): returned events count.
The python library also supports the retrieval of single event with a known GDACS Event ID.
event = client.get_event(event_type='TC', event_id='1000132')
To retrieve the record of a particular event episode, include episode_id
in your code as shown below.
event = client.get_event(event_type='TC', event_id='1000132', episode_id='8')
The library supports the retrieval of data in different formats provided by the GDACS API. The default source format for all retrievals is xml
but you can also make use of geojson
or shp
.
event = client.get_event(event_type='DR', event_id='1012428', episode_id='10', source_format='geojson')
Required parameters:
event_type
(str): TC (Tropical Cyclones), EQ (Earthquakes), FL (Floods), VO (Volcanoes), WF (Wild Fires) and DR (Droughts)event_id
(str): GDACS Event ID
Optional parameters:
episode_id
(str): GDACS Event Episode IDsource_format
(str): xml, geojson or shp (Shapefile)cap_file
(bool)
Invalid arguments or retrieval of missing records from the GDACS API may result in an error. You can catch them with GDACSAPIError
which includes the error message returned.
from gdacs.api import GDACSAPIError
try:
# try to retrieve an invalid/missing event
client.get_event(event_type='DR', event_id='1012428', source_format='geojson')
except GDACSAPIError as error:
print(error)
The project uses unittest
(Python inbuilt testing library) to run its suite of unit tests.
(venv)$ cd ./gdacs/tests
(venv)$ python -m unittest
This project is licensed under the MIT License - see the LICENSE for details.