The simplest way to use a visualization created in CARTO on an external site is as follows:
Using the CARTO.js Library
CARTO.js can be used to embed a visualization you have designed using CARTO’s user interface, or to dynamically create visualizations from scratch, using your data. If you want to create new maps on your webpage, jump to Creating a visualization from scratch. If you already have maps on your webpage and want to add CARTO visualizations to them, read Adding CARTO layers to an existing map.
You can also use the CARTO APIs to create visualizations programmatically. This can be useful when the visualizations react to user interactions. To read more about it, jump to Creating visualizations at runtime.
To start using CARTO.js, paste this piece of code within the HEAD tags of your HTML:
Other Mapping Libraries
We have also made it easy for you to build maps using the mapping library of your choice. Whether you are using Leaflet or something else, our CARTO.js code remains the same. This makes our API documentation simple and straightforward. It also makes it easy for you to consistently develop, or maintain, multiple maps online.
Note: CARTO.js automatically includes dependencies from other mapping libraries (such as Leaflet, jQuery, Mustache, Underscore, and so on). You do not have to manually include these libraries, or worry about other mapping library version control, when you are using CARTO.js. If you need to see which version of other mapping libraries are included, view the vendor folder for each CARTO.js release.
Creating a Visualization from Scratch
This is the easiest way to quickly get a CARTO map onto your webpage. Use this method when there is no map in your application, and you want to add the visualization to hack over it. CARTO.js handles all the details of loading a map interface, basemap, and your CARTO visualization.
You can start by giving CARTO.js the DIV ID from your HTML where you want to place your map, and the viz.json URL of your visualization (which you can get from the Publish your map options).
That’s it! No need to create the map instance, insert controls, or load layers. CARTO.js takes care of this for you.
The viz.json file tells CARTO.js all the information about your map, including the style you want to use for your data and the filters you want to apply with SQL. The viz.json file is served with each map you create in your CARTO account.
Although the viz.json file stores all your map settings, all these settings can be easily customized with CARTO.js. If you want to modify the result after instantiating your map with the viz.json, reference the CARTO.js API available methods. For example, you can also use the returned layer to build more functionality (show/hide, click, hover, custom infowindows):
Tip: You can download a viz.json from any visualization you have created and inspect it with a text editor, or view it in your browser if you have a JSON viewer. If you are unfamiliar with the JSON file format, view the official JSON website for more information.
Adding CARTO Layers to an Existing Map
In case you already have a map instantiated on your page, you can simply use the createLayer method to add new CARTO layers to it. This is particularly useful when you have more things on your map apart from CARTO layers or you have an application where you want to integrate CARTO layers.
Below, you have an example using a previously instantiated Leaflet map.
Creating Visualizations at Runtime
All CARTO services are available through the API, which basically means that you can create a new visualization without doing it before through CARTO Editor. This is particularly useful when you are modifying the visualization depending on user interactions that change the SQL to get the data or CartoCSS to style it. Although this method requires more programming skills, it provides all the flexibility you might need to create more dynamic visualizations.
Want more information? See the complete list of API methods.
You can use all the functionality of CARTO.js with HTTPs support. Be sure to use https when importing both the JS library and the CSS file. You will also need to use HTTPs in the viz.json URL you pass to
Using a Different Host
CARTO.js sends all requests to the carto.com domain by default. If you are running your own instance of CARTO, you can change the URLs to specify a different host.
A different host can be configured by using
maps_api_template in the
cartodb function call.
The format of these templates is as follows:
CARTO.js will replace
Note that you do not need to set the path to the endpoint, CARTO.js sets it automatically.
Loading Listener Events
done, tells your code that the library has successfully read the information from the viz.json, and loaded the layer you requested.
error, tells you that something did not go as expected when trying to load the requested layer:
Note: For information about active layer events, which are triggered by layers on your webpage that are already loaded, see Events.
CARTO.js Usage Examples
The best way to start learning about the library is by taking a look at some of the examples below: