CartoDB.js
CartoDB offers a simple unified JavaScript library called CartoDB.js that let you interact with the CartoDB service. This library allows you to connect to your stored visualizations, create new visualizations, add custom interaction, or access and query your raw data from a web browser; meaning, your applications just got a whole lot more powerful with a lot less code.
When you add CartoDB.js to your websites you get some great new tools to make maps or power your content with data. Let’s take a look.
If you want to check out the source code or contribute, please visit the project Github page.
The simplest way to use a visualization created in CartoDB on an external site is:
``` javascript
...
<body>
<div id="map"></div>
</body>
...
<script>
// get the viz.json url from the CartoDB UI
// - go to the map tab
// - click on share
// - go to API tab
window.onload = function() {
cartodb.createVis('map', 'http://examples-beta.cartodb.com/api/v1/viz/219/viz.json');
}
</script>
```
get the complete example here.
CartoDB.js can be used when you want to embed and use a visualization you have designed using CartoDB user interface, or to create visualizations from scratch dynamically using your data. If you want to create new maps on your webpage, jump to "using CartoDB visualizations in your webpage". If you already have maps on your webpage and want to add CartoDB visualizations to them, read "Add CartoDB layer to an existing map".
You can also use CartoDB APIs to create visualization without having to define them using the website, you can create them dynamically in your code. This is useful for example when the visualizations change depending on user interactions. To read more about it jump to, create visualizations at runtime.
We’ve also made it easier than ever for you to build maps using the mapping library of your choice. Whether you are using Leaflet or Google Maps your CartoDB.js code remains the same. This makes our API documentation simple and straightforward. It also makes it easy for you to remember and keep consistent if you development or maintain multiple maps online.
To use CartoDB.js in your web-page, you no longer need to host the library on your servers, instead we have made a fast and lightweight version of it available for you online. This has the extra benefit that whenever we fix bugs they get fixed automatically on your visualizations without having to update anything on your side. To start building maps with your CartoDB hosted tables, just including the CartoDB.js inside the HEAD tag of your page:
``` html
<link rel="stylesheet" href="http://libs.cartocdn.com/cartodb.js/v2/themes/css/cartodb.css" />
<!--[if lte IE 8]>
<link rel="stylesheet" href="http://libs.cartocdn.com/cartodb.js/v2/themes/css/cartodb.ie.css" />
<![endif]-->
<script src="http://libs.cartocdn.com/cartodb.js/v2/cartodb.js"></script>
```
The library is being mirrored on servers all over the world (using a CDN), so you can be sure that no matter where your website viewers are, they will get CartoDB.js loaded in the fastest way possible.
The cartodb.createVis method is probably going to be the most important one in your CartoDB toolbox.
This is the easiest way to quickly get a CartoDB map onto your webpage. It handles all the details of loading a map interface, basemap, and your CartoDB data visualization. You can start by giving cartodb.js the DIV ID from your HTML where you want to place your map and the Viz JSON URL from your CartoDB map.
``` javascript
cartodb.createVis('map', 'http://examples-beta.cartodb.com/api/v1/viz/791/viz.json');
```
That's it! No need to create the map instance, insert controls, or load layers, it handles it all for you. You just give cartodb.js a set of options (zoom, loader, infowindows...) to modify how your final map looks, see cartodb.Vis in the API section for the full list of options.
You can also use the returned layer to build functionality (show/hide, click, hover, custom infowindows) using the new layer:
``` javascript
cartodb.createVis('map', 'http://examples-beta.cartodb.com/api/v1/viz/791/viz.json')
.done(function(vis, layers) {
// layer 0 is the base layer, layer 1 is cartodb layer
layers[1].on('featureOver', function(e, latlng, pos, data) {
cartodb.log.log(e, latlng, pos, data);
});
// you can also get the map object created by cartodb.js
map = vis.getNativeMap();
// Now, perform any operations you need
// map.setZoom(3)
// map.setCenter(new google.maps.Latlng(...))
});
```
If you have used Google Maps for you basemap in your CartoDB account, using createViz requires that you load the Google Maps V3 JavaScript libarary in the HEAD of your HTML. If you use other basemaps, cartodb.js will load the Leaflet library for you automatically.
With visualizations already created through the CartoDB website, you can simply use the createLayer function to add them into your web pages. Unlike the cartodb.createVis, you will use this method if you create you map instance independantly of cartodb.js. This is useful when you have more things on your map apart from CartoDB layers or you have an existing application.
This method works the same whether you are using Google Maps or Leaflet. Learn the details and different uses of layers in our API documentation below.
To show you just how simple CartoDB.js can be, let's put it all together. Start by including the necessary libararies in the HEAD of your HTML (remember the Google Maps JS library if you are using a Google Maps basemap):
``` html
<link rel="stylesheet" href="http://libs.cartocdn.com/cartodb.js/v2/themes/css/cartodb.css" />
<!--[if lte IE 8]>
<link rel="stylesheet" href="http://libs.cartocdn.com/cartodb.js/v2/themes/css/cartodb.ie.css" />
<![endif]-->
<script src="http://libs.cartocdn.com/cartodb.js/v2/cartodb.js"></script>
```
Next, in the BODY of your HTML include a DIV for your map and the minimum CartoDB.js script to load your data.
``` javascript
<div id="map"></div>
<script>
var map = new L.Map('map', {
center: [0,0],
zoom: 2
})
cartodb.createLayer(map, 'http://examples-beta.cartodb.com/api/v1/viz/766/viz.json')
.on('error', function(err) {
alert("some error occurred: " + err);
});
</script>
```
In the above case, we create a new map, but in your case you probably already have the instance of map available in your code.
See cartodb.createLayer in the API section or see a simple example.
All CartoDB services are available via the APIs. That means that you can create a new visualization without having to create them before on the CartoDB website. 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. This method, although more advance, provides all the flexibility you might need to create the most dynamic visualizations.
When you create a visualization using the CartoDB website, you get automatically a viz.json URL defining it. When you want to create the visualization via JS, obviously you dont have it, so you will pass all the required parameters to the library so that it can create the visualization at runtime and display it on your map. It is pretty simple.
``` javascript
cartodb.createLayer(map, {
type: 'cartodb',
options: {
table_name: 'mytable',
user_name: 'cartodb_username'
query: 'select * from mytable where age > 10'
}
}).done(function(layer) {
map.addLayer(layer);
});
```
That's it! That is all the code you need to start developing your own maps with CartoDB.js. If you want to start building applications straight away, head over to our tutorials to see how to start making your own maps.
The CartoDB.js has many great features for you to use in your applications. Let’s take a look at the most important for your application development.
The Viz.JSON document tells CartoDB.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 CartoDB account.
Although the Viz JSON file stores all your map settings, all the values are also easy to customize with CartoDB.js if you want to do something completely different than what you designed in your console. Loading the Viz JSON is as simple as:
``` javascript
cartodb.createVis('map', 'http://examples.cartodb.com/api/v1/viz/ne_10m_populated_p_1/viz.json')
```
We have added easy method to get the bounding box for any dataset or filtered query using the CartoDB.js library. The getBounds function can be useful for guiding users to the right location on a map or for loading only the right data at the right time based on user actions.
``` javascript
var sql = new cartodb.SQL({ user: 'cartodb_user' });
sql.getBounds('select * from table').done(function(bounds) {
console.log(bounds);
});
```
The CartoDB.js is highly asynchronous, meaning your application can get on with what it needs to do while the library efficiently does what you request in the background. This is useful for loading maps or getting query results. At the same time, we have made it very simple to add listeners and callbacks to the async portions of the library.
The createLayer and createVis functions returns two important events for you to take advantage of: the first is done, which will let your code know that the library has successfully read the information from the Viz JSON and loaded the layer you requested. The second is ‘error’, which lets you know something did not go as expected when loading a requested layer:
``` javascript
cartodb.createLayer(map, 'http://examples.cartodb.com/api/v1/viz/0001/viz.json')
.on('done', function(layer) {
alert(‘CartoDB layer loaded!’);
}).on('error', function(err) {
alert("some error occurred: " + err);
});
```
The next important set of events for you to use happen on those layers that are already loaded (returned by the done event above). Three events are triggered by layers on your webpage, each requires the layer to include an interactivity layer. The first event is featureClick, which lets you set up events after the user clicks anything that you have mapped.
``` javascript
layer.on('featureClick', function(e, latlng, pos, data) {
console.log("mouse clicked polygon with data: " + data);
});
```
The second event is the featureOver event, which lets you listen for when the user’s mouse is over a feature. Be careful, as these functions can get costly if you have a lot of features on a map.
``` javascript
layer.on('featureOver', function(e, latlng, pos, data) {
console.log("mouse over polygon with data: " + data);
});
```
Similarly, there is the featureOut event. This is best used if you do things like highlighting polygons on mouseover and need a way to know when to remove the highlighting after the mouse has left.
``` javascript
layer.on('featureOut', function(e, latlng, pos, data) {
console.log("mouse left polygon with data: " + data);
});
```
If you want to use Leaflet it gets even easier, CartoDB.js handles loading all the necessary libraries for you! just include CartoDB.js and CartoDB.css in the HEAD of your website and you are ready to go! The CartoDB.css document isn’t mandatory, however if you are making a map and are not familiar with writing your own CSS for the various needed elements, it can greatly help to jumpstart the process. Adding it is as simple as adding the main JavaScript library:
``` html
<link rel="stylesheet" href="http://libs.cartocdn.com/cartodb.js/v2/themes/css/cartodb.css" />
<script src="http://libs.cartocdn.com/cartodb.js/v2/cartodb.js"></script>
```
We have worked hard to support Internet Explorer with CartoDB.js. It currently works for IE7 through IE10. The biggest change you should note is that for the CSS you will need to include an additional IE CSS document we have made available. Your
tag should now house links to three documents, as follows,``` html
<link rel="stylesheet" href="http://libs.cartocdn.com/cartodb.js/v2/themes/css/cartodb.css" />
<!--[if lte IE 8]>
<link rel="stylesheet" href="http://libs.cartocdn.com/cartodb.js/v2/themes/css/cartodb.ie.css" />
<![endif]-->
<script src="http://libs.cartocdn.com/cartodb.js/v2/cartodb.js"></script>
```
We are committed to making sure your website works as intended no matter what changes in the future. While we may find more efficient or more useful features to add to the library as time progresses. We never want to break things you have already developed, for this reason, we make versioned CartoDB.js libraries available to you, meaning that the way they function will never unexpectedly change on you.
We recommend that you always develop against the most recent version of CartoDB.js, always found at:
``` javascript
http://libs.cartocdn.com/cartodb.js/v2/cartodb.js
```
Anytime you wish to push a stable version of your site to the web though, you can find the version of CartoDB.js you are using by looking at the first line of the library, here:
``` javascript
http://libs.cartocdn.com/cartodb.js/v2/cartodb.js
```
Or, by running the following in your code:
``` javascript
alert(cartodb.VERSION)
```
Now, that you have your CartoDB.js version, you can point your site at that release. If the current version of CartoDB.js is 2.0.11, the URL would be:
``` javascript
http://libs.cartocdn.com/cartodb.js/v2/2.0.11/cartodb.js
```
You can do the same for the CSS documents we provide:
``` javascript
http://libs.cartocdn.com/cartodb.js/v2/2.0.11/themes/css/cartodb.css
```
If you want to start playing with the library, there are several examples to start with:
The documentation below reflects CartoDB.js for the 2.0.x library versions. For major changes in the library we will update the documentation here. This documentation is meant to help developers find specific methods for using the CartoDB.js library.
For any questions regarding the usage of the library or for problems with the documentation please contact us at support@cartodb.com.
cartodb.Vis is probably going to be the most important instrument in your toolbox. This method allows to do a complete visualization, managing everything for the map and layer creation. In addition, it allows you to add easily modify widgets like zoom, loader, infowindow, tooltips, and overlays.
Creates a visualization inside the map_id DOM object:
``` javascript
var url = 'http://examples-beta.cartodb.com/api/v1/viz/791/viz.json';
cartodb.createVis('map', url)
.done(function(vis, layers) {
});
```
Return an array of layers in the map. The first is the base layer.
Add an overlay to the map, these are the overlays you can add: zoom, tooltip, infobox.
An overlay object, depending on the options.type different object will be returned, see cartodb.vis.Overlays.
Return the first overlay with the specified type.
``` javascript
var zoom = vis.getOverlay('zoom')
zoom.clean() // remove it from the screen
```
Returns a list of overlays currently on the screen (see overlays description).
Returns the native map object being used. It can be google.maps.Map or L.Map depending on the provider you setup in the UI.
An overlay is a control shown on top of the map.
Overlay objects are always created using method addOverlay of cartodb.Vis object.
An overlay is internally a Backbone.View so if you know how backbone works you can use it. If you want to use plain DOM objects you can access to overlay.el (overlay.$el for jquery object).
With visualizations already created through the CartoDB console, you can simply use the createLayer function to add them into your web pages. Unlike createVis, this method requires an already activated map object and it does not load a basemap for you. The method works the same whether your map object is Google Maps or Leaflet.
layerSource: contains information about the layer. It can be specified in 2 ways:
passing the url where the layer data is located:
``` javascript
cartodb.createLayer(map, 'http://myserver.com/layerdata.json')
```
passing the data directly:
``` javascript
cartodb.createLayer(map, { ... layer metadata ... });
```
Layer metadata is always in the form: { type: 'LAYER_TYPE_NAME', options: {....} }options: each type of layer has different options.
callback(layer): if a function is specified is called when the layer is created passing it as argument.
Promise object. You can listen for the following events:
``` javascript
var map;
var mapOptions = {
zoom: 5,
center: new google.maps.LatLng(43, 0),
mapTypeId: google.maps.MapTypeId.ROADMAP
};
map = new google.maps.Map(document.getElementById('map'), mapOptions);
cartodb.createLayer(map, 'http://examples.cartodb.com/tables/TODO/cartodb.js')
.on('done', function(layer) {
layer
.on('featureOver', function(e, latlng, pos, data) {
console.log(e, latlng, pos, data);
})
.on('error', function(err) {
console.log('error: ' + err);
});
}).on('error', function(err) {
console.log("some error occurred: " + err);
});
```
Should be called after removing the layer from the map.
Hides the cartodb layer from the map. Disables the interaction if it was enabled.
Show the cartodb layer in the map if it was previously added. Enables the interaction if it was enabled.
Get the visibility of the layer. Returns true or false.
true: if layer is visible.
Change the opacity of the layer.
Sets the interaction of your layer to true (enabled) or false (disabled). When is disabled featureOver, featureClick and featureOut are not triggered.
Sets the sql query. The layer will show the geometry returned by this query. When the query raises an error, error event is triggered. If you set sql to null the query is set to 'select * form {{table_name}}'.
The layer is refreshed just after you execute this function.
``` javascript
// this will show in the map the geometries with area greater than 10
layer.setQuery("SELECT * FROM {{table_name}} WHERE area > 10");
// error management
layer.setQuery("wrong syntax query");
layer.on('error', function(err) {
console.log("there was some problem: " + err);
});
```
Changes the style of the layer. An 'error' event is triggered on the layer if something is wrong with the style. Set cartoCSS to null to reset to original style
``` javascript
layer.setCartoCSS("#{{table_name}}{ marker-fill:blue }");
```
Change the columns you want to get data.
Change any parameter at the same time refreshing the tiles once.
``` javascript
layer.setOptions({
query: "SELECT * FROM {{table_name}} WHERE cartodb_id < 100",
interactivity: "cartodb_id,the_geom,magnitude"
});
```
You can add custom functions to layer events. This is useful for integrating your website with your maps, adding events for mouseovers and click events.
A callback when hovers in a feature.
``` javascript
layer.on('featureOver', function(e, latlng, pos, data) {
console.log("mouse over polygon with data: " + data);
});
```
A callback when hovers out any feature.
A callback when clicks in a feature.
Same as featureOver.
There are a few functions in CartoDB.js for creating, enabling, and disabling pieces of the user-interface.
Shows a small tooltip on hover:
``` javascript
var tooltip = vis.addOverlay({
type: 'tooltip'
template: '<p>{{variable}}</p>' // mustache template
});
```
The tooltip is shown when hover on feature when is called.
The tooltip is not shown when hover on feature.
Show an small box when the user hovers on a map feature. The position is fixed:
``` javascript
var box = vis.addOverlay({
type: 'infobox',
template: '<p>{{name_to_display}}</p>'
width: 200, // width of the box
position: 'bottom|right' // top, bottom, left and right are available
});
```
The tooltip is shown when hover on feature when is called.
The tooltip is not shown when hover on feature.
Shows the zoom control:
``` javascript
vis.addOverlay({ type: 'zoom' });
```
CartoDB offers a powerful SQL API for you to query and retreive data from your CartoDB tables. The CartoDB.js offers a simple to use wrapper for sending those requests and using the results.
cartodb.SQL is the tool you will use to access data you store in your CartoDB tables. This is a really powerful technique for returning things like: items closest to a point, items ordered by date, or GeoJSON vector geometries. It’s all powered with SQL and our tutorials will show you how easy it is to begin with SQL.
``` javascript
var sql = new cartodb.SQL({ user: 'cartodb_user' });
sql.execute("select * from table where id > {{id}}", { id: 3 })
.done(function(data) {
console.log(data.rows);
})
.error(function(errors) {
// errors contains a list of errors
console.log("error:" + err);
})
```
It accepts the following options:
These arguments will be applied for all the queries performed by this object, if you want to override them for one query see execute options.
It executes a sql query.
Promise object. You can listen for the following events:
You can also use done and error methods:
``` javascript
sql.execute('select * from table')
.done(fn)
.error(fnError)
```
Return the bounds [ [sw_lat, sw_lon], [ne_lat, ne_lon ] ] for the geometry resulting of specified query.
``` javascript
sql.getBounds('select * form table').done(function(bounds) {
console.log(bounds);
});
```
Keep in mind the version of CartoDB.js you are using for development. For any live code, we recommend you link directly to the tested CartoDB.js version from your development. You can find the version at anytime as follows:
Contains the library version, should be something like '2.0.11'.
Visit our support area and get some help from the community.
Yes we have. Contact us for getting more information. We are quite friends of academics so, you will get a lot of benefits.
Need us to help you with your visualization or application? Does your organization have unique requirements that don’t quite fit our plans? Contact us.