
CARTO + Mapbox GL JS
Build applications using CARTO & Mapbox GL JS.
Getting started
In this guide, you will learn the basics of visualizing a CARTO dataset with the Mapbox GL JS library. There are no previous requirements to complete this guide, but a basic knowledge of the Mapbox GL JS library would be helpful.
After completing this guide, you will have your first Mapbox GL map with a CARTO dataset!
About MapboxGL license
Beginning with v2.0.0, mapbox-gl-js
is no longer under the 3-Clause BSD license. Also, from that same version, a billable map load occurs whenever a Map object is initialized. That leaves 1.13.0 as the latest mapbox-gl-js version with BSD, that can be freely used.
Thus, in the current example we are using 1.13.0 assets, hosted at CARTO CDN, so no billing is applied if you replicate it as it is. For sure, you can replace those assets and use mapbox-gl >=v2 from their CDN, but in that case you would need to use a valid Mapbox access token and to ensure you know the new billing model and license.
For more info about this, you can read our blogpost Our Thoughts as MapboxGL JS v2.0 Goes Proprietary.
Basic setup
The first thing you need to do is to add all the required Mapbox GL dependencies (library and CSS files):
|
|
Add map container
Next, you need to create a div
inside the body
where the map will be drawn and you need to style them to ensure the map displays at full width:
|
|
Create map and set properties
Once you have a div
for your map, you can use the mapboxgl.Map
constructor to create your map with the desired initial view. Here we are also specifying the style property to use one of the CARTO basemaps. If you want to use a Mapbox basemap, you will need to provide your Mapbox access token:
|
|
At this point you will have a basic map with the Voyager CARTO basemap:
Add layer
In order to visualize a CARTO dataset, we need to provide vector tiles source URLs through the source.tiles
property while calling the addLayer
method on the map. We also need to indicate the ID for the layer and the styling properties:
|
|
The tiles source URLs need to be retrieved using the Maps API. You can go to the docs if you want to know more about the possibilities of the Maps API but, for this example, we will focus on the basic functionality.
MapConfig
When we want to use the Maps API, we first need to do a process called instantiating the map. This instantiation requires to send a payload called a MapConfig where we specify the SQL statement to retrieve the information for the dataset we want to visualize and additional options like the map type or the tile extent size.
|
|
In order to have the better performance, we recommend you to retrieve only the fields you want to use client-side, instead of selecting all the fields (SELECT *). If you select all the fields from the dataset, the vector tiles will be bigger than needed and would take more time to encode, download and decode.
Maps API Endpoint
This MapConfig must be sent to the Maps API endpoint. This endpoint has the following template:
https://{username}.carto.com/api/v1/map/?api_key={api_key}
In order to render data from CARTO you need to have a CARTO account and then get the necessary credentials. The credentials consists of a username and a corresponding API key. The API key determines what datasets can access the Maps API, so you need to create an API key with permissions to the dataset you want to visualize. For guides and examples, we use the public
CARTO account so you can try out the library using this endpoint:
https://public.carto.com/api/v1/map/?api_key=default_public
Instantiating the map
Now that we have our endpoint and our MapConfig, we can call the Maps API to get the tile sources URLs. We can use the fetch
function with a Request object to retrieve the information asynchronously. We are instantiating an anonymous map and the response contains, among other information, a metadata object about the layers requested in the MapConfig. This metadata object contains a tilejson
property with information about the tile sources URLs:
|
|
MapConfig objects can be quite large and, depending on the browser and the web server, we might hit a limit with the URL length. We recommend you to always use a GET request if possible, but if you are getting URL length errors, you should change to POST requests. In the complete example, we are checking the length against a 2048 character limit but this could be different depending on the browsers you want to support.
All together
You can explore the final step here
|
|