Metadata-Version: 2.1
Name: gideon-api
Version: 0.3.0
Summary: 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.
Home-page: https://gideononline.github.io/gideon-api-python-docs
Author: GIDEON Informatics
Author-email: info@gideononline.com
License: Mozilla Public License Version 2.0
Project-URL: GitHub, https://github.com/gideononline/gideon-api-python
Project-URL: Documentation, https://gideononline.github.io/gideon-api-python-docs
Project-URL: GIDEON, https://www.gideononline.com/
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Healthcare Industry
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE

# 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](https://gideononline.github.io/gideon-api-python-docs/gideon_id_codes.html) 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`](https://gideononline.github.io/gideon-api-python-docs/outbreaks.html#gideon_api.outbreaks_by_year)
- [`gideon_api.outbreaks_by_country_year`](https://gideononline.github.io/gideon-api-python-docs/outbreaks.html#gideon_api.outbreaks_by_country_year)
- [`gideon_api.latest_outbreaks_by_country`](https://gideononline.github.io/gideon-api-python-docs/outbreaks.html#gideon_api.latest_outbreaks_by_country)
- [`gideon_api.outbreaks_by_disease`](https://gideononline.github.io/gideon-api-python-docs/outbreaks.html#gideon_api.outbreaks_by_disease)
- [`gideon_api.endemic_countries_by_disease`](https://gideononline.github.io/gideon-api-python-docs/outbreaks.html#gideon_api.endemic_countries_by_disease)
- [`gideon_api.endemic_diseases_by_country`](https://gideononline.github.io/gideon-api-python-docs/outbreaks.html#gideon_api.endemic_diseases_by_country)

## Query the GIDEON API Directly

- [`gideon_api.query`](https://gideononline.github.io/gideon-api-python-docs/api_query_wrapper.html#gideon_api.query): This is the main function users should use to send commands to the GIDEON API
- [`gideon_api.query_online`](https://gideononline.github.io/gideon-api-python-docs/api_query_wrapper.html#gideon_api.query_online): This version should be used to process the request without interacting with the cache and provides lower level response data.


