gideon-api 0.3.0

GIDEON provides epidemiological data going back to 1348 AD. This package provides an interface with the GIDEON API to access its Infectous Disease database within Python.

GIDEON - Python Interface (BETA)

A package for accessing the GIDEON API using Python.

The gideon_api package provides functions to access the GIDEON API without the need of writing your own REST API queries.

GIDEON Authentication

• The GIDEON API requires the use of an API key, which can be set in two ways:

1. The package will attempt to read the environment variable $GIDEON_API_KEY, which is set to your GIDEON API key.
   • The API key can be set either in the terminal for the current terminal session only or the $HOME/.bashrc file for persistent storage. In either case, set the API key with the line export GIDEON_API_KEY=<YOUR API KEY>
2. The GIDEON API key can be updated within Python by calling the function gideon_api.set_api_key(<YOUR API KEY>). Be sure to protect your key and not store it in code or a repository shared with others.

Basic Installation

$ pip install --user gideon-api

Developer Installation

Install the Python Virtual Environment

1. Install the pipenv Python environment manager.
   • Install the pipenv Python package to your Python user install directory with the following terminal command: $python3 -m pip install --user pipenv
2. Install the developer virtual environment. Change directory to the repository root and execute the terminal command $python3 -m pipenv install --dev
3. From the repository root or an of its subdirectories, enter the virtual environment with the command $python3 -m pipenv shell

Build and Install the gideon_api Package.

• From the root directory, $pip install -e .
• The -e/--editable flag allows the developer to not have to reinstall the package when the Python files are updated.

Build the HTML Documentation

1. Activate the project's pipenv environment. Follow step #3 from the "Install the Virtual Environment" section.
2. Change directory to the repository's docs/ directory, one level below the root of the repository.
3. Run make html to build the HTML documents in the build/ subdirectory. If the build/ directory does not exist, it will be generated by the make html command.

Functionality Overview

GIDEON ID Codes

Many of the items in the GIDEON database use a unique identifier code, such as diseases, bacteria, drugs, etc. Refer to the GIDEON ID Codes Documentation for a list of lookup functions.

Outbreak Data

The following command will query the GIDEON API for particular outbreak data:

• gideon_api.outbreaks_by_year
• gideon_api.outbreaks_by_country_year
• gideon_api.latest_outbreaks_by_country
• gideon_api.outbreaks_by_disease
• gideon_api.endemic_countries_by_disease
• gideon_api.endemic_diseases_by_country

Query the GIDEON API Directly

• gideon_api.query: This is the main function users should use to send commands to the GIDEON API
• gideon_api.query_online: This version should be used to process the request without interacting with the cache and provides lower level response data.