CARTO 3 Public API

CARTO 3 Public API

Getting Started

Introduction

CARTO 3 API allows you to interact with your data in an external data warehouse using a existing connection in your CARTO 3 account. Learn more about connections here.

Authorization

CARTO 3 API uses an access token as the authorization method. In order to obtain an access token you need to call the https://auth.carto.com/oauth/token endpoint, using the client_id and client_secret from an application previously created in your account.

There are different types of applications:

  • Single Page Applications that can be used to login with CARTO for React, deck.gl, and other libraries and simple web applications.
  • Regular Web Application that can be used with regular web applications.
  • Machine to Machine that can be used in backend applications or Postman API collections.

After an application is created, you can copy the Client ID and Client Secret from the list and use them as required in different scenarios.

This is an example of how to get an access token with cURL:

1
2
3
4
5
6
7
curl --request POST \
  --url 'https://auth.carto.com/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials' \
  --data 'client_id=xyxhWf4tthisisjustanexampleZxwc4NP9jpTRIch8P' \
  --data 'client_secret=k4s0LOPzlVnehythisisjustanexampleHCc9BtbtdS1Sq7NcRS3AFVD5I3H6s0a0aKz3aZyxK0' \
  --data 'audience=carto-cloud-native-api' 

Creating an application

  • Login to your CARTO 3 account and open the Developers section.
  • Click on + Create new
  • Fill in the name and description. The URL is not relevant in this example, so feel free to use something like https://example.domain.com
  • Open the Advanced Settings menu
  • In Application Type select Machine to Machine.
  • Make sure that Token Endpoint Authentication Method is set to Post
  • Click Save and check that your application is listed.

Using the Postman collection

The CARTO 3 API complete reference is available at api-docs.carto.com as a Postman collection that you can explore interactively by clicking on the Run in Postman button.

In order to obtain the access token required to run the collection, you need to follow these steps:

  • Create a Machine to Machine application in your CARTO 3 account as described above.
  • Go to api-docs.carto.com and click on Run in Postman
  • Import the Collection in one of your Postman Workspaces
  • Configure your Environment:
    • Click on Environments
    • Select Documentation
    • Set the variables apiBaseURL, clientId, and clientSecret with the values that you will find in the Developers section of your CARTO 3 account.
  • You are all set! Select a folder in the collection and run the example requests.