API Client

APIClient is a class for handling requests to the Civis API. An instantiated APIClient contains a set of resources (listed below) where each resource is an object with methods. By convention, an instantiated APIClient object is named client and API requests are made with the following syntax:

client = civis.APIClient()
response = client.resource.method(params)
class civis.APIClient(api_key=None, return_type='snake', retry_total=6, api_version='1.0', resources='base')

The Civis API client.

Parameters:

api_key : str, optional

Your API key obtained from the Civis Platform. If not given, the client will use the CIVIS_API_KEY environment variable.

return_type : str, optional

The following types are implemented:

retry_total : int, optional

A number indicating the maximum number of retries for 429, 502, 503, or 504 errors.

api_version : string, optional

The version of endpoints to call. May instantiate multiple client objects with different versions. Currently only “1.0” is supported.

resources : string, optional

When set to “base”, only the default endpoints will be exposed in the client object. Set to “all” to include all endpoints available for a given user, including those that may be in development and subject to breaking changes at a later date.

Attributes

credentials An instance of the Credentials endpoint
databases An instance of the Databases endpoint
files An instance of the Files endpoint
imports An instance of the Imports endpoint
jobs An instance of the Jobs endpoint
models An instance of the Models endpoint
predictions An instance of the Predictions endpoint
projects An instance of the Projects endpoint
queries An instance of the Queries endpoint
reports An instance of the Reports endpoint
scripts An instance of the Scripts endpoint
tables An instance of the Tables endpoint
users An instance of the Users endpoint
default_credential

The current user’s default credential.

get_aws_credential_id(cred_name, owner=None)

Find an AWS credential ID.

Parameters:

cred_name : str or int

If an integer ID is given, this passes through directly. If a str is given, return the ID corresponding to the AWS credential with that name.

owner : str, optional

Return the credential with this owner. If not provided, search for credentials under your username to disambiguate multiple credentials with the same name. Note that this function cannot return credentials which are not associated with an owner.
Returns:

aws_credential_id : int

The ID number of the AWS credentials.
Raises:

ValueError

If the AWS credential can’t be found.

Examples

>>> import civis
>>> client = civis.APIClient()
>>> client.get_aws_credential_id('jsmith')
1234

>>> client.get_aws_credential_id(1111)
1111

>>> client.get_aws_credential_id('shared-cred',
...                              owner='research-group')
99
get_database_credential_id(username, database_name)

Return the credential ID for a given username in a given database.

Parameters:

username : str or int

If an integer ID is given, this passes through directly. If a str is given, return the ID corresponding to the database credential with that username.

database_name : str or int

Return the ID of the database credential with username username for this database name or ID.
Returns:

database_credential_id : int

The ID of the database credentials.
Raises:

ValueError

If the credential can’t be found.

Examples

>>> import civis
>>> client = civis.APIClient()
>>> client.get_database_credential_id('jsmith', 'redshift-general')
1234

>>> client.get_database_credential_id(1111, 'redshift-general')
1111
get_database_id(database)

Return the database ID for a given database name.

Parameters:

database : str or int

If an integer ID is given, passes through. If a str is given the database ID corresponding to that database name is returned.
Returns:

database_id : int

The ID of the database.
Raises:

ValueError

If the database can’t be found.
get_table_id(table, database)

Return the table ID for a given database and table name.

Parameters:

table : str

The name of the table in format schema.table.

database : str or int

The name or ID of the database.
Returns:

table_id : int

The ID of the table. Only returns exact match to specified table.
Raises:

ValueError

If an exact table match can’t be found.
username

The current user’s username.