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 an id code, such as diseases, bacteria, drugs, etc. Use gideon_api.lookup_item to get specific item code to use when calling the GIDEON API.

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.