pynigma

pynigma is a simple Python client for the Enigma API.

Installation
Setup
- Tests
Usage
- Parameters
Endponts
- Data
- Metadata
- Stats
- Export
- Limits

Installation

pynigma can be installed using pip

$ pip install pynigma

Or, you can clone this repository and run the setup script

$ git clone git@github.com:thejunglejane/pynigma.git
$ cd pynigma
$ python setup.py install

Setup

There is no setup required, but I recommend creating a .env that creates an environment variable with your Enigma API key. An example .env is included in this repository. You can copy the .env-example to a .env and fill in your API key, or echo the export statement to a .env file from the command line.

$ cp .env-example .env
$ # or
$ echo `export ENIGMA_API_KEY='<YOUR API KEY HERE>'` >> .env

You will need to source the .env file for the ENIGMA_API_KEY environment variable to be available in a Terminal session.

Tests

pynigma uses unittest. To run the tests

$ python -m unittest discover tests/

Usage

import os
from pynigma import client

# Load the ENIGMA_API_KEY environment variable
ENIGMA_API_KEY = os.environ['ENIGMA_API_KEY']

# Create a new instance of the EnigmaAPI class
api = client.EnigmaAPI(client_key=ENIGMA_API_KEY)

Parameters

Query parameters are accepted by each endpoint method as **kwargs.

params = {'search': '@visitee_namelast=FLOTUS'}
flotus_visitors = api.get_data(
    datapath='us.gov.whitehouse.visitor-list', **params)

Check the official API documentation for valid parameters and parameter formats for each endpoint. If an invalid parameter for an endpoint is passed, pynigma will throw a nice ValueError.

Endpoints

Each API endpoint is accessed in pretty much the same way. All you need to provide are a datapath (if applicable) and any query parameters.

Data Endpoint

The data endpoint provides the actual data associated with table datapaths. The data endpoint is accessed via the get_data() method.

import os
from pynigma import client

# Load the ENIGMA_API_KEY environment variable
ENIGMA_API_KEY = os.environ['ENIGMA_API_KEY']

api = client.EnigmaAPI(client_key=ENIGMA_API_KEY)

# Get the data on White House salaries in 2011
data = api.get_data(datapath='us.gov.whitehouse.salaries.2011')

data['result'][0]  # the first salary in the dataset

Metadata Endpoint

The metadata endpoint provides the metadata associated with table datapaths. The metadata endpoint is accessed via the get_metadata() method.

import os
from pynigma import client

# Load the ENIGMA_API_KEY environment variable
ENIGMA_API_KEY = os.environ['ENIGMA_API_KEY']

api = client.EnigmaAPI(client_key=ENIGMA_API_KEY)

# Get the metadata associated with the White House visitors dataset
metadata = api.get_metadata(datapath='us.gov.whitehouse.visitor-list')

# Print the column names in this dataset
for column in metadata['result']['columns']:
    print column['label']

The column metadata returned by pynigma will include an additional key not returned by the endpoint, 'python_type', representing the Python data type that corresponds to the type string returned. Mappings are based on the PL/Python PostgreSQL to Python mappings. If pynigma cannot determine the Python data type using these mappings, it will default to str, which is consistent with PL/Python.

Stats Endpoint

The stats endpoint provides statistics on columns within table datapaths. The stats endpoint is accessed via the get_stats() method.

import os
from pynigma import client

# Load the ENIGMA_API_KEY environment variable
ENIGMA_API_KEY = os.environ['ENIGMA_API_KEY']

api = client.EnigmaAPI(client_key=ENIGMA_API_KEY)

# Get statistics for the type_of_access column in the White House visitors
# dataset
stats = api.get_stats(
    datapath='us.gov.whitehouse.visitor-list', **{'select': 'type_of_access'})

# Print the number of visitors for each type of access
for type in stats['result']['frequency']:
    print type['type_of_access'], type['count']

Export Endpoint

The export endpoint provides URLs to gzipped CSV files of table datapaths. The export endpoint is accessed via the get_export() method.

import os
from pynigma import client

# Load the ENIGMA_API_KEY environment variable
ENIGMA_API_KEY = os.environ['ENIGMA_API_KEY']

api = client.EnigmaAPI(client_key=ENIGMA_API_KEY)

# Get URL for a gzipped CSV of the White House visitors dataset
export = api.get_export(datapath='us.gov.whitehouse.visitor-list')

print export['head_url']  # print the URL

Limits Endpoint

The limits endpoint provides current limits for the API key provided.

import os
from pynigma import client

# Load the ENIGMA_API_KEY environment variable
ENIGMA_API_KEY = os.environ['ENIGMA_API_KEY']

api = client.EnigmaAPI(client_key=ENIGMA_API_KEY)

# Get limits for ENIGMA_API_KEY
limits = api.get_limits()
print limits['data']  # remaining data API calls this month

gregorykremler/pynigma