CARTO VL is a JavaScript library to create custom Location Intelligence applications over vector rendering.
This library is still under support but it will not be further developed. We don’t recommend starting new projects with it as it will eventually become deprecated. Instead, learn more about our current CARTO for deck.gl library here
In this guide you will learn how to use different data sources in your CARTO VL layers. After finishing this guide, you will be able to use different type of sources, and know which type is best for you.
This guide assumes that you have previously gone through the Getting Started Guide and know how to make a basic map.
By the end of this guide, you will be able to create this CARTO VL map:
CARTO VL is a library that visualizes geographical datasets in a powerful and flexible way. Those datasets can be yours or they can be served by some other provider, but the first step to know is where they are hosted and how they can be accessed.
CARTO VL currently supports three basic types of data sources:
Every type is a different kind of Source, and CARTO VL provides you with a suitable object in its API to use them under the namespace carto.source (for example carto.source.Dataset).
Both Dataset and SQL are based in Vector Tiles, following the Mapbox Vector Tile Specification or MVT. This advanced technology allows transferring geographic data from the server to your browser in small chunks, allowing good performance through progressive loading of data.
Note: In fact, there is a fourth type of source in CARTO VL called carto.source.MVT but its usage is only recommended for some advanced cases.
In the following section you will see how to use the three main source types. Before getting started with that, you will need to create a basic map.
You can start from this basemap. Go ahead and copy its source code into a new file called sources.html.
Note:
To copy the source code from an example, you just have to navigate to it with your browser, click right button > View source and copy the whole text, from <html> to </html> tags.
A Dataset source can be created with the carto.source.Dataset constructor. If you have a GIS background, this is like a local vector file with points, lines or polygons, hosted in CARTO. If you don’t, you can think of it as a table on the server with a geometry field you can use to draw it on a map.
You already know how to add a Dataset thanks to the Getting Started guide:
1
const aSource = new carto.source.Dataset('name_of_your_dataset');
That was using carto.setDefaultAuth method, but now you will see how to include custom credentials for a specific dataset. This allows to work with multiple Sources with different combinations of usernames and API keys. Add this to your current working file (sources.html if you followed our suggestion), just after map creation.
1
2
3
4
const citiesSource = new carto.source.Dataset('populated_places', {
username: 'cartovl',
apiKey: 'default_public'
});
Now you’re ready for the layer creation:
1
const citiesLayer = new carto.Layer('cities', citiesSource, new carto.Viz());
The first parameter, in this case, 'cities', is the Mapbox GL ID for the layer, you should avoid name clashing with your basemap layer IDs.
And now you can add that layer to the map, by including this code:
1
citiesLayer.addTo(map);
The result should look like this:
View this step here
You have a CARTO account, with several custom datasets, and you want to visualize one of them on a map, with all its rows.
A GeoJSON can be used in CARTO VL with carto.source.GeoJSON. GeoJSON is a standard format to encode geographic data using JSON. You can create some .geojson contents online at geojson.io.
In the next set of steps, you’ll create a new GeoJSON layer, to visualize the main CARTO offices around the world.
You can include GeoJSON content and embed it directly in your JavaScript, like this:
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
const offices = {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-73.944158, 40.678178]
},
"properties": {
"address": "Brooklyn, New York"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-3.70379, 40.416775]
},
"properties": {
"address": "Madrid, Spain"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-77.036871, 38.907192]
},
"properties": {
"address": "Washington, DC"
}
}
]
};
Note: If your dataset is much bigger, you would probably store that content in an external file (see this External GeoJSON layer example).
And then use it within a GeoJSON source, like this:
1
const officesSource = new carto.source.GeoJSON(offices);
Define a map layer:
1
const officesLayer = new carto.Layer('offices', officesSource, new carto.Viz());
And finally add that layer to the map:
1
officesLayer.addTo(map);
Now the map should look like this:
View this step here
You already have your data in GeoJSON format, and you don’t have access to a CARTO account (if you do have a CARTO account, you should import it to get a better performance and more capabilities, and then use a Dataset source). This can also be a useful format for some quick tests, using inline GeoJSON if you are managing just a few rows or a .geojson file just next to your .html.
SQL is a very common language to make queries in databases and geospatial software. It provides a flexible mechanism to adapt your dataset to your specific needs.
Let’s see how to add a SQL source to your map!
Define a query (select only the largest cities in the world: with megacity category) from the populated_places dataset:
1
const query = 'SELECT * FROM populated_places WHERE megacity = 1';
Note: This is a simple query but the SQL runs on CARTO’s backend, which is powered by PostGIS, so you could also execute more sophisticated queries and even spatial analysis.
Create a SQL source:
1
2
3
4
const megacitiesSource = new carto.source.SQL(query, {
username: 'cartovl',
apiKey: 'default_public'
});
Define the new style:
1
const megacitiesViz = new carto.Viz('color: blue');
Create a common layer with those selected megacities:
1
const megacitiesLayer = new carto.Layer('megacities', megacitiesSource, megacitiesViz);
And finally add this layer to the map:
1
megacitiesLayer.addTo(map);
Using your CARTO account, you want to visualize a custom query in a layer: apply some transformations to your dataset, filter using PostGIS functionality, or to join a couple of datasets.
Congrats! You have finished this guide. The final map should look like this:
You can explore the final step here
This is the complete code:
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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<script src="https://libs.cartocdn.com/carto-vl/v1.0.0/carto-vl.min.js"></script>
<script src="https://api.tiles.mapbox.com/mapbox-gl-js/v0.50.0/mapbox-gl.js"></script>
<link href="https://api.tiles.mapbox.com/mapbox-gl-js/v0.50.0/mapbox-gl.css" rel="stylesheet" />
<link href="https://carto.com/developers/carto-vl/v1.0.0/examples/maps/style.css" rel="stylesheet">
</head>
<body>
<div id="map"></div>
<script>
const map = new mapboxgl.Map({
container: 'map',
style: carto.basemaps.voyager,
center: [0, 30],
zoom: 2
});
const nav = new mapboxgl.NavigationControl();
map.addControl(nav, 'top-left');
//** CARTO VL functionality begins here **//
// DATASET
// Define Dataset source with custom credentials
const citiesSource = new carto.source.Dataset('populated_places', {
username: 'cartovl',
apiKey: 'default_public'
});
const citiesViz = new carto.Viz(`
color: grey
width: 4
`);
const citiesLayer = new carto.Layer('cities', citiesSource, citiesViz);
citiesLayer.addTo(map);
// GEOJSON
// Create GeoJSON content
const offices = {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-73.944158, 40.678178]
},
"properties": {
"address": "Brooklyn, New York"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-3.70379, 40.416775]
},
"properties": {
"address": "Madrid, Spain"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-77.036871, 38.907192]
},
"properties": {
"address": "Washington, DC"
}
}
]
};
// Define GeoJSON source
const officesSource = new carto.source.GeoJSON(offices);
const officesViz = new carto.Viz(`
color: red
width: 20
`);
const officesLayer = new carto.Layer('offices', officesSource, officesViz);
officesLayer.addTo(map);
// SQL
// Define query
const query = 'SELECT * FROM populated_places WHERE megacity = 1';
// Define SQL source with query and custom credentials
const megacitiesSource = new carto.source.SQL(query, {
username: 'cartovl',
apiKey: 'default_public'
});
const megacitiesViz = new carto.Viz('color: blue');
const megacitiesLayer = new carto.Layer('megacities', megacitiesSource, megacitiesViz);
megacitiesLayer.addTo(map);
</script>
</body>
</html>