pynigma is a simple Python client for the Enigma API.
pynigma can be installed using pip
$ pip install pynigmaOr, you can clone this repository and run the setup script
$ git clone git@github.com:thejunglejane/pynigma.git
$ cd pynigma
$ python setup.py installThere 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>'` >> .envYou will need to source the .env file for the ENIGMA_API_KEY environment variable to be available in a Terminal session.
pynigma uses unittest. To run the tests
$ python -m unittest discover tests/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)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.
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.
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 datasetThe 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.
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']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 URLThe 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