Skip to main content

Access the Civis Platform API

Project description

Build status Latest version on PyPI Supported python versions for civis-python

Deprecation Warning: Civis will no longer support Python 2.7 or Python 3.4 as of April 1, 2020. The first Civis Platform API Python Client release made after that date will remove Python 2 support.

Introduction

The Civis Platform API Python client is a Python package that helps analysts and developers interact with the Civis Platform. The package includes a set of tools around common workflows as well as a convenient interface to make requests directly to the Civis API.

Please see the full documentation for more details.

API Keys

In order to make requests to the Civis API, you will need a Civis Platform API key that is unique to you. Instructions for creating a new key are found here. API keys have a set expiration date and new keys will need to be created at least every 30 days. The API client will look for a CIVIS_API_KEY environmental variable to access your API key, so after creating a new API key, follow the steps below for your operating system to set up your environment.

Linux / MacOS

  1. Add the following to .bash_profile (or .bashrc for Linux) for bash:

    export CIVIS_API_KEY="alphaNumericApiK3y"
  2. Source your .bash_profile (or restart your terminal).

Windows 10

  1. Navigate to “Settings” -> type “environment” in search bar -> “Edit environment variables for your account”. This can also be found in “System Properties” -> “Advanced” -> “Environment Variables…”.

  2. In the user variables section, if CIVIS_API_KEY already exists in the list of environment variables, click on it and press “Edit…”. Otherwise, click “New..”.

  3. Enter CIVIS_API_KEY as the “Variable name”.

  4. Enter your API key as the “Variable value”. Your API key should look like a long string of letters and numbers.

Installation

After creating an API key and setting the CIVIS_API_KEY environmental variable, install the Python package civis with the recommended method via pip:

pip install civis

Alternatively, if you are interested in the latest functionality not yet released through pip, you may clone the code from GitHub and build from source:

git clone https://github.com/civisanalytics/civis-python.git
cd civis-python
python setup.py install

You can test your installation by running

import civis
client = civis.APIClient()
print(client.users.list_me()['username'])

If civis was installed correctly, this will print your Civis Platform username.

The client has a soft dependency on pandas to support features such as data type parsing. If you are using the io namespace to read or write data from Civis, it is highly recommended that you install pandas and set use_pandas=True in functions that accept that parameter. To install pandas:

pip install pandas

Machine learning features in the ml namespace have a soft dependency on scikit-learn and pandas. Install scikit-learn to export your trained models from the Civis Platform or to provide your own custom models. Use pandas to download model predictions from the Civis Platform. The civis.ml code optionally uses the feather format to transfer data from your local computer to Civis Platform. Install these dependencies with

pip install scikit-learn
pip install pandas
pip install feather-format

Some CivisML models have open-source dependencies in addition to scikit-learn, which you may need if you want to download the model object. These dependencies are civisml-extensions, glmnet, and muffnn. Install these dependencies with

pip install civisml-extensions
pip install glmnet
pip install muffnn

Python version support

Python 3.5, 3.6, and 3.7

Usage

civis includes a number of wrappers around the Civis API for common workflows.

import civis
df = civis.io.read_civis(table="my_schema.my_table",
                         database="database",
                         use_pandas=True)

The Civis API may also be directly accessed via the APIClient class.

import civis
client = civis.APIClient()
database = client.databases.list()

See the documentation for a more complete user guide.

Retries

The API client will automatically retry for certain API error responses.

If the error is one of [413, 429, 503] and the API client is told how long it needs to wait before it’s safe to retry (this is always the case with 429s, which are rate limit errors), then the client will wait the specified amount of time before retrying the request.

If the error is one of [429, 502, 503, 504] and the request is not a patch* or post* method, then the API client will retry the request several times, with a delay, to see if it will succeed.

Build Documentation Locally

To install dependencies for building the documentation:

pip install Sphinx
pip install sphinx_rtd_theme
pip install numpydoc

To build the API documentation locally:

cd docs
make html

Then open docs/build/html/index.html.

Note that this will use your API key in the CIVIS_API_KEY environment variable so it will generate documentation for all the endpoints that you have access to.

Command-line Interface (CLI)

After installing the Python package, you’ll also have a civis command accessible from your shell. It surfaces a commandline interface to all of the regular Civis API endpoints, plus a few helpers. To get started, run civis --help. Please see the CLI documentation for more details.

Contributing

See CONTRIBUTING.md for information about contributing to this project.

License

BSD-3

See LICENSE.md for details.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

civis-1.14.1.tar.gz (492.8 kB view hashes)

Uploaded Source

Built Distribution

civis-1.14.1-py3-none-any.whl (894.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page