Civis API Python Client¶
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.
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
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
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¶
Add the following to your shell configuration file (
~/.zshrcfor MacOS or
~/.bashrcfor Linux, by default):
Source your shell configuration file (or restart your terminal).
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_KEYalready 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.
After creating an API key and setting the
variable, install the Python package
civis with the recommended method via
pip install civis
Alternatively, if you are interested in the latest functionality not yet released through
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'])
civis was installed correctly, this will print your Civis
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
use_pandas=True in functions that accept that parameter. To install
pip install pandas
Machine learning features in the
ml namespace have a soft dependency on
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
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
scikit-learn, which you may need if you want to
download the model object. These dependencies are
muffnn. Install these
pip install civisml-extensions pip install glmnet pip install muffnn
For a more detailed walkthrough, see the User Guide.
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
method, then the API client will retry the request several times, with an exponential delay,
to see if it will succeed. If the request is of type
post* it will retry with the same parameters
for error codes [429, 503].