CARTOframes

Authentication

This guide focuses on the basics of authentication in CARTOframes.

Authentication is needed to store your data tables and map visualizations in your CARTO account, to use Data Services (geocoding, isolines) or the Data Observatory (download, enrichment). If you don’t already have an account, you can create one here.

You don’t need to be authenticated to visualize your local data with CARTOframes.

Getting your API Key

Once you have created an account, you need to get your Master API Key. The API keys page can be accessed from your CARTO Dashboard. Once there, click on your avatar to open the dashboard menu. The API keys link will be shown.

From here, copy the Master API Key to use in the next section.

Setting your credentials

Credentials class is used to load your credentials in CARTOframes. This should be passed to every method that interacts with your CARTO account. You can create multiple instances of credentials to manage different CARTO accounts.

There are different ways to set them but we recommend using the one that reads the credentials from a JSON file:

1
2
3
from cartoframes.auth import Credentials

creds = Credentials.from_file('creds.json')

With set_default_credentials, the same user’s authentication will be used by every CARTOframes component by default, so you don’t need to pass the parameter to every method that requires it.

1
2
3
from cartoframes.auth import set_default_credentials

set_default_credentials('creds.json')

Example creds.json file using the credentials above:

1
2
3
4
{
  "username": "johnsmith",
  "api_key": "b1ff3ed88761070116180189d9a1f5cb9cc80654"
}

Credential parameters

• username: your CARTO account username
• api_key: your CARTO account API Key. If the data to be accessed is public, it can be set to default_public
• base_url: only needed for on-premise or custom installations. Typically in the form of https://username.carto.com/ for user username. On-premises installation (and others) may have a different URL pattern.

Google Cloud credentials

CARTO’s Data Observatory is built on top of Google BigQuery, so every CARTO Enterprise organization has an associated Google Cloud account to run Data Observatory operations.

In case you have an Enterprise account and want to perform data operations directly with the Python BigQuery client, you can obtain the credentials of the associated Google Cloud account and create a Google Credentials instance.

1
2
3
4
5
6
7
from cartoframes.auth import Credentials
from google.oauth2.credentials import Credentials as GoogleCredentials

creds = Credentials.from_file('creds.json')

gcloud_project, gcloud_token = creds.get_gcloud_credentials()
gcloud_credentials = GoogleCredentials(gcloud_token)