In this guide, you will learn the basics of visualizing data with CARTO VL on top of a world basemap. There are no previous requirements to complete this guide, but a basic knowledge of HTML, CSS and JavaScript would be helpful.
After completing this guide, you will have your first CARTO VL map!
The most straight-forward way to use CARTO VL is to include the required files from our CDN as seen in the code below. You will also need to add Mapbox GL JavaScript and CSS files.
1
2
3
4
5
6
7
8
<head>
<!-- Include CARTO VL JS from the CARTO CDN-->
<script src="https://libs.cartocdn.com/carto-vl/v1.4.4/carto-vl.min.js"></script>
<!-- Include Mapbox GL from the Mapbox CDN-->
<script src="https://api.tiles.mapbox.com/mapbox-gl-js/v1.0.0/mapbox-gl.js"></script>
<link href="https://api.tiles.mapbox.com/mapbox-gl-js/v1.0.0/mapbox-gl.css" rel="stylesheet" />
</head>
Note:
Mapbox GL: CARTO VL is not compatible with every version. We recommend using the same version that we use in the examples. However, every version from v0.50.0
should work. Historically, we provided patched MGL bundles, but this is no longer required.
Note:
Developers: if you have experience with npm
and a build system in your project (webpack, rollup…), you can install CARTO VL library with npm install @carto/carto-vl
. You can import it with import carto from '@carto/carto-vl'
and then you will have access to an already babelified version of the library, ready to be used.
Next, you need to create a div
where the map will be drawn:
1
<div id="map"></div>
Style the map div
to ensure the map displays properly:
1
2
3
4
5
#map {
position: absolute;
height: 100%;
width: 100%;
}
Once you have a div
for your map, you have to use the mapboxgl.Map
constructor to create a new map with the following parameters:
container
: element ID to indicate where the map is going to be placedstyle
: sets the basemap style to usecenter
: sets the opening center coordinates of the map (longitude, latitude)zoom
: sets the default zoom level of the map1
2
3
4
5
6
const map = new mapboxgl.Map({
container: 'map',
style: carto.basemaps.voyager,
center: [0, 30],
zoom: 2
});
For the basemap style
parameter, you can add either Mapbox custom styles or one of the three predefined styles offered by CARTO:
carto.basemaps.voyager
(see style details at voyager-gl-style)carto.basemaps.positron
(positron-gl-style)carto.basemaps.darkmatter
(dark-matter-gl-style)At this point you will have a basic map with Voyager as the base, that opens at zoom level 2 and centered on the world:
View this step here
In order to render data from CARTO you need to create a CARTO account and then get the necessary credentials.
The first thing you need to do is authenticate the client with your username
and apiKey
. For guides and examples, we provide a public CARTO account that you can use to try out the library:
1
2
3
4
carto.setDefaultAuth({
username: 'cartovl',
apiKey: 'default_public'
});
The next step is to define the source
from your account to be displayed on the map. In the example below, the source
is a dataset named populated_places
with all the most populated places around the world from Natural Earth.
1
const source = new carto.source.Dataset('populated_places');
A Viz object
is one of the core elements of CARTO VL. It defines how the data will be styled and displayed on your map.
Create an empty Viz
object that uses the default CARTO VL styling:
1
const viz = new carto.Viz();
Now that you have created a source
and a Viz object
, you need to create a new layer
that can be added to the map.
1
const layer = new carto.Layer('layer', source, viz);
Once you have created the layer
, you need to use the addTo
method to add it to the map.
1
layer.addTo(map);
Instead of using the Viz
object you created in a previous step, with the default values, we can set custom values for the color
and size
of the points on your map:
1
2
3
4
const viz = new carto.Viz(`
color: purple
width: 5
`);
For more information about styling, check out the guide Style with Expressions.
You can explore the final step here
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<script src="https://libs.cartocdn.com/carto-vl/v1.4.4/carto-vl.min.js"></script>
<script src="https://api.tiles.mapbox.com/mapbox-gl-js/v1.0.0/mapbox-gl.js"></script>
<link href="https://api.tiles.mapbox.com/mapbox-gl-js/v1.0.0/mapbox-gl.css" rel="stylesheet" />
<link href="https://carto.com/developers/carto-vl/v1.4.4/examples/maps/style.css" rel="stylesheet">
</head>
<body>
<!-- Add map container -->
<div id="map"></div>
<script>
// Add basemap and set properties
const map = new mapboxgl.Map({
container: 'map',
style: carto.basemaps.voyager,
center: [0, 30],
zoom: 2
});
//** CARTO VL functionality begins here **//
// Define user
carto.setDefaultAuth({
username: 'cartovl',
apiKey: 'default_public'
});
// Define source
const source = new carto.source.Dataset('populated_places');
// Define Viz object and custom style
const viz = new carto.Viz(`
color: purple
width: 5
`);
// Define map layer
const layer = new carto.Layer('layer', source, viz);
// Add map layer
layer.addTo(map);
</script>
</body>
</html>