CARTO VL

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

Add Data Sources

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:

Supported Data Sources

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:

  • Dataset: a vector dataset hosted by CARTO and available with your credentials (for example, a dataset with all the stores in your city).
  • SQL: a dataset with a SQL query applied to it (e.g. just the stores with > 500 sq meters).
  • GeoJSON: a vector dataset in GeoJSON format.

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.

Getting started

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.

Dataset source

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.

Add a Dataset source

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

When to use a Dataset source?

You have a CARTO account, with several custom datasets, and you want to visualize one of them on a map, with all its rows.

GeoJSON source

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.

Add a GeoJSON source

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

When to use a GeoJSON source?

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 source

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.

Add a SQL source

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);

When to use SQL?

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.


All together

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.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>
    <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>