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:
'raw'
Returns the rawrequests.Response
object.'snake'
Returns acivis.response.Response
object for the json-encoded content of a response. This maps the top-level json keys to snake_case.'pandas'
Returns apandas.DataFrame
for list-like responses and apandas.Series
for single a json response.
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
endpointdatabases An instance of the Databases
endpointfiles An instance of the Files
endpointimports An instance of the Imports
endpointjobs An instance of the Jobs
endpointmodels An instance of the Models
endpointpredictions An instance of the Predictions
endpointqueries An instance of the Queries
endpointreports An instance of the Reports
endpointscripts An instance of the Scripts
endpointtables An instance of the Tables
endpointusers 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.