CartoVistaWhat is the CartoVista REST API and what can I use it for? #
CartoVista has a REST API that will allow you to automate any of your actions on the platform, such as loading a dataset, modifying a dataset or part of a dataset, deleting an object on the plateform, etc.
CartoVista API is based on REST principles. API calls are made through HTTP requests, using the following standard methods: GET, POST, DELETE, PATCH.
This REST API allows for interoperability with other systems and databases. Here are a few examples of how it can be used:
- update a layer daily from a public data source
- update or add new features in a layer based on triggers in a database
- change a story content automatically when data exceeds a certain threshold
- export workspace statistics weekly to track the usage of public maps
- import your user base into CartoVista to send invites automatically
Get started #
Authenticate your request #
You will need an API key to get started with the CartoVista REST API. API keys are associated with users and inherit their permissions. You can use the tutorial Generate an API Key from the Resource Center in your workspace to learn how to generate your key.
A list of external IP addresses secures API Keys. You will therefore need to make the API calls from the computer whose IP you registered. Register multiple external IP addresses for one API Key by listing the IPs separated by a semicolon.
If you want to avoid using IP address whitelisting, you can generate a secret key and remove the IP whitelist content. The secret key is only visible temporarily on the platform, and you will have to regenerate it if you don’t save it elsewhere.
You can also combine the two security methods to have both a secret key and an IP whitelist. You need at least 1 security method for the API key to work (IP whitelist or secret key).
To generate a secret key, click on the user you want to create a key for in the Users tab of the platform. In the detailed panel of the user, click on the API Key tab. Click on the + icon to generate a new key.
Enter an IP address to generate the key.
Once the key is generated, you can copy it from the platform to integrate it into your script. You can also generate a secret key from this panel.
In your API calls, you will need to pass the header apiKey, and the header secretKey if you have generated one. The header secretKey is optional.
Please note that if you are using online API testing services such as Postman, you will need to use the secret key and remove the IP whitelist since the Postman IP address is not static.
Identify the request you need #
CartoVista uses Swagger to document the API endpoints. In the API Key tab of a user’s detail panel, you will find the link to the Swagger page. You can also use the tutorial Generate an API Key from the Resource Center in your workspace to get to the Swagger page.
Swagger is useful to learn more about the API, find out all the available calls and methods, and try them out using your API key. However, it cannot be used to automate your tasks.
Swagger gives you the list of all endpoints, organized by topic.
You can enter your API Key to test a request or connect to your account in another tab to authenticate your swagger calls. Please note that if your API Key has a secret key generated, you can’t authenticate your swagger calls by entering your API key, and you need to be logged in to your workspace in another tab.
Click on an endpoint to see details.
Fill in the parameters (see how to get the parameter values below), and click Try it out. The response will contain the Curl request, the response body and the response code.
✔️ You can now use any software capable of sending and receiving HTTP requests to use the CartoVista REST API and start to automate your tasks.
Parameters #
When using the REST API on maps or data, you will need to pass in the URL or the body
- the tenantUrlCode: this is your workspace’s identifier. You can find it in the URL of your CartoVista workspace: cloud.cartovista.com/{tenantUrlCode}/maps.
- the identifier of your dataset or your map.
To get the identifier of a map, click on the lower part of a map card to open the detailed panel of the map. The Information tab will give you the URL of the map. The identifier is the 5 character-long code (numbers and/or letters) between the workspace name and the map name:
To get the identifier of a layer or data table, click on the lower part of a data card in the Data Gallery to open the detailed panel of the data. The Information tab will give you the identifier of your data:
Pip package for Python #
In addition to the Swagger page, the API is also available as a pip package for Python. The installation instructions, usage examples, and detailed documentation are available on GitHub: https://github.com/cartovista/cartovista-cloud-restapi-python-clients.
