CartoDB

CartoDB Google Maps v3 library

0.54
Back

Documentation

Using the library is really easy. It accepts the following parameters to manage the behavior of your CartoDB layers:

Parameter name Description Type Callback variables Required
map The Google Map object. Object Yes
username Your CartoDB user name. String Yes
table_name Your CartoDB table name. String Yes
query A SQL query. Default: "SELECT * FROM {{table_name}}" String Yes
opacity If you want to change the opacity of the CartoDB layer. Default: 1 Number No
layer_order If you want to set the order of the CartoDB layer. Default: "top" Number or String ("top" or "bottom") No
tile_style If you want to add other style to the layer String No
map_style Show the same style as you defined in the CartoDB map. Boolean No
interactivity If you want to add interactivity to the layer without making requests. String (columns separated by commas) No
featureOver A callback when hovers in a feature Function event: Mouse event object
latlng: The LatLng gmapsv3 object where was hovered
pos: Object with x and y position in the DOM map element
data: The CartoDB data of the clicked feature with the `interactivity` param.
No (But only will work with `interactivity` specified)
featureOut A callback when hovers out a feature Function No (But only will work with `interactivity` specified)
featureClick A callback when clicks in a feature Function event: Mouse event object
latlng: The LatLng gmapsv3 object where was clicked or touched
pos: Object with x and y position in the DOM map element
data: The CartoDB data of the clicked feature with the `interactivity` param.
No (But only will work with `interactivity` specified)
tile_style If you want to add other style to the layer. String No
auto_bound Bounds in the area with your query results. Boolean No
debug If you want to debug the library, set to true. Boolean No
tiler_domain Base domain of the tiler URL. Default: "cartodb.com" String No
tiler_port Port of the tiler URL. Default: "80" Number No
tiler_protocol Protocol for the tiler URL. Default: "http" String No
sql_domain Set your SQL API domain. Default: "cartodb.com" String No
sql_port Set your SQL API port. Default: "80" Number No
sql_protocol Set your SQL API protocol. Default: "http" String No
Usage notes

If you want to get a feature clicked || hover data (via the interactivity parameter), the columns must be in a string separated by commas. If you don't want to write the name of the table several times, you can use {{table_name}} in the query or tile_style parameters. We strongly recommend the use of the files available in this repository. These are tested, and if you decide use updated ones, the library could not work.

Example

First of all add the necessary script and css files:

<link href="css/cartodb-gmapsv3.css" rel="stylesheet" type="text/css" />
<link  href="http://code.google.com/apis/maps/documentation/javascript/examples/default.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="http://maps.googleapis.com/maps/api/js?sensor=false"></script>
<script type="text/javascript" src="js/wax.g.min.js"></script>
<script type="text/javascript" src="dist/cartodb-gmapsv3-min.js"></script>
          

* We strongly recommend to use the library files we have in this repository, they are fully tested.

When the document is loaded, start creating the map:

var map = new google.maps.Map(document.getElementById('map'), {
  center: new google.maps.LatLng(20, 0),
  zoom: 3,
  mapTypeId: google.maps.MapTypeId.ROADMAP,
  mapTypeControl: false
});
          

Then create the CartoDB layer:

var cartodb_gmapsv3 = new CartoDBLayer({
  map: map,
  user_name:'example',
  table_name: 'earthquakes',
  query: "SELECT * FROM {{table_name}}",
  layer_order: "top",
  tile_style: "#{{table_name}}{marker-fill:red}",
  interactivity: "cartodb_id, magnitude",
  featureClick: function(ev, latlng, pos, data) {alert(data.cartodb_id)},
  featureOver: function(ev, latlng, pos, data) {},
  featureOut: function() {},
  auto_bound: true
});
          
Functions

New funcionalities are coming, in the meantime you can use:

  • setMap: Attach the layer to the map or remove it.

       cartodb_gmapsv3.setMap(null);
  • hide: Hide the cartodb layer from the map.

       cartodb_gmapsv3.hide();
  • show: Show again the cartodb layer in the map.

       cartodb_gmapsv3.show();
  • setInteraction: Set the interaction of your layer to true or false.

       cartodb_gmapsv3.setInteraction(false);
  • setLayerOrder: Change the opacity of the CartoDB layer.

       cartodb_gmapsv3.setLayerOrder("top");
  • setQuery: Change the query parameter for the layer.

       cartodb_gmapsv3.setQuery("SELECT * FROM {{table_name}} WHERE cartodb_id > 10");
  • isVisible: Get the visibility of the layer.

       cartodb_gmapsv3.isVisible();
  • isAdded: Returns if the layer belongs to the map.

       cartodb_gmapsv3.isAdded();
  • setStyle: Change the style of the layer tiles.

       cartodb_gmapsv3.setStyle("#{{table_name}}{marker-fill:blue}");
  • setInteractivity: Change the columns you want to get data (it needs to reload the tiles).

       cartodb_gmapsv3.setInteractivity("cartodb_id, the_geom, magnitude");
  • setOpacity: Change the opacity of the layer

       cartodb_gmapsv3.setOpacity(0.2);
  • setOptions: Change any parameter at the same time refreshing the tiles once

       cartodb_gmapsv3.setOptions({query: "SELECT * FROM {{table_name}} WHERE cartodb_id<100", interactivity: "cartodb_id,the_geom,magnitude"});
  • setBounds: Set bounds in the map using a new query or the default one

       cartodb_gmapsv3.setBounds(); cartodb_gmapsv3.setBounds("SELECT * FROM {{table_name}} WHERE cartodb_id < 100");
Custom infowindow

If you want to use the cartodb custom infowindow, you need to add the script in the html:

<script type="text/javascript" src="dist/cartodb-infowindow-min.js"></script>
          

Create the CartoDB infowindow passing the map object:

var infowindow = new CartoDBInfowindow(map);
          

And then use as you want:

...
featureClick: function(ev,latlng,pos,data) {
  // Set infowindow content
  // You can pass an Object, an Array or a String
  infowindow.setContent(data);

  // Set position
  infowindow.setPosition(latlng);

  // Show it!
  infowindow.open();
},
...
          

You can see an example using it here.

Further info? Take a look a the docs

Visit our support area and get some help from the community.

CartoDB is also used by

  • Harvard
  • UNEP-WCMC
  • NASA
  • Convention on Biological Diversity
  • Wall Street Journal
  • WORLD RESOURCES INSTITUTE
  • Common questions

  • Do you have any educational plans?

    Yes we have. Contact us for getting more information. We are quite friends of academics so, you will get a lot of benefits.

  • Need something extra? Let us know.

    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.