The Civis 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. See the full documentation for more details.
-
Get a Civis API key (instructions)
-
Add a
CIVIS_API_KEY
environment variable. -
You can add the following to
.bash_profile
for bashexport CIVIS_API_KEY="alphaNumericApiK3y"
-
Source your
.bash_profile
-
Install the package
pip install civis
-
Optionally, install
pandas
,pubnub
, andrequests-toolbelt
to enable some functionality incivis-python
pip install pandas pip install pubnub pip install requests-toolbelt
Installation of
pandas
will allow some functions to returnDataFrame
outputs. Installation ofpubnub
will improve performance in all functions which wait for a Civis Platform job to complete. Installation ofrequests-toolbelt
will allow streaming file uploads to Civis viacivis.io.file_to_civis
.
civis-python
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 full documentation for a more complete 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 patch*
or post*
method, then the API client will retry the request several times, with a delay,
to see if it will succeed.
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.
See CONTIBUTING.md
for information about contributing to this project.
BSD-3
See LICENSE.md
for details.