Skip to main content

gdacs-api

Unofficial python library for working with Global Disaster Alert and Coordination System (GDACS) API.

Setup

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

Getting Started

Import Library

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

Setup API Client

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()

Get Latest Events

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.

Get Single Event Record

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 ID
  • source_format (str): xml, geojson or shp (Shapefile)
  • cap_file (bool)

Handling Errors

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)

Testing

The project uses unittest (Python inbuilt testing library) to run its suite of unit tests.

(venv)$ cd ./gdacs/tests
(venv)$ python -m unittest

License

This project is licensed under the MIT License - see the LICENSE for details.

Metadata

Release files for gdacs-api 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gdacs-api 2.0.0
File Size Uploaded Provenance Actions
gdacs-api-2.0.0.tar.gz 5.1 kB Without provenance Details for gdacs-api-2.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gdacs-api 2.0.0
File Interpreter ABI Platform Actions
gdacs_api-2.0.0-py3-none-any.whl Python 3 none any Details for gdacs_api-2.0.0-py3-none-any.whl

Total release size: 10.9 kB

Release files / gdacs-api-2.0.0.tar.gz

Download URL gdacs-api-2.0.0.tar.gz
Size 5.1 kB
Tags Source
SHA-256 checksum
How to use checksums
77b0ec951ea9aa6b448e8b25fd6f29d1eb40582b00a84e203bb66a3cc8dc9e06
BLAKE2b-256 checksum
How to use checksums
106a522bc552f3f633196616b81b370c19d1beaa0e95d5e7f8b5f2e1b96f15b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.9.13

Release files / gdacs_api-2.0.0-py3-none-any.whl

Download URL gdacs_api-2.0.0-py3-none-any.whl
Size 5.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f905fe6132474a55cc87250a0f9ee86bbfaa37bf0e9dd0c43ad9aa9307c02fe2
BLAKE2b-256 checksum
How to use checksums
5d9a28f87400f6eb255ce45c129a3dbd4b65c972b733bb2e5f753269e56cde4b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.9.13

Security for gdacs-api 2.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page