Civis API Python Client

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

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 environment 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.

Note

Treat your API key like a password. Do not keep it under version control or share it with others.

Linux / MacOS

Add the following to your shell configuration file (~/.zshrc for MacOS or ~/.bashrc for Linux, by default):
```
export CIVIS_API_KEY="alphaNumericApiK3y"
```
Source your shell configuration file (or restart your terminal).

Windows

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…”.
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..”.
Enter CIVIS_API_KEY as the “Variable name”.
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 environment 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 assumed to be available):

pip install git+https://github.com/civisanalytics/civis-python.git

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 or polars to support dataframes. If you are using the civis.io namespace to read or write data from Civis, it is highly recommended that you install pandas or polars and set the argument return_as to "pandas" or "polars", respectively, in functions that accept that parameter. To install pandas:

pip install pandas

To install polars:

pip install polars

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

User Guide

For a more detailed walkthrough, see the User Guide.