IMPORTANT
This library is deprecated. We have created a new library called CartoDB.js that includes all the funcionality of this library plus many more things. This library isn't going to be updated anymore. If you have any questions don't hesitate to send us an email to support@cartodb.com.
What is the CartoDB library for GMaps v3?
This library allows you to use your own CartoDB tables with Google Maps v3.
Using the library
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. | 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 clicked 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. | Booelan | 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: 8080 | 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
There are several usages of this library in examples folder.
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-6.2.0-touched.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
});
And then add the CartoDB layer:
var cartodb_gmapsv3 = new CartoDBLayer({
map: map,
user_name:'examples',
table_name: 'earthquakes',
query: "SELECT * FROM {{table_name}}",
layer_order: "top",
tile_style: "#{{table_name}}{marker-fill:red}",
interactivity: "cartodb_id, magnitude",
featureClick: function(feature, latlng, pos, data) {alert(feature)},
featureOut: function() {},
featureOver: function(feature, latlng, pos, data) {},
auto_bound: true
});
Functions
New funcionalities are coming, in the meantime you can use:
- setMap: Attach the layer to the map or remove it.
Example:
cartodb_gmapsv3.setMap(null);
- hide: Hide the cartodb layer from the map.
Example:
cartodb_gmapsv3.hide();
- show: Show again the cartodb layer in the map.
Example:
cartodb_gmapsv3.show();
- setInteraction: Set the interaction of your layer to true or false.
Example:
cartodb_gmapsv3.setInteraction(false);
- setLayerOrder: Change the order of the CartoDB layer.
Example:
cartodb_gmapsv3.setOrder("top"); cartodb_gmapsv3.setOrder("bottom"); cartodb_gmapsv3.setOrder(2);
- setQuery: Change the query parameter for the layer
Example:
cartodb_gmapsv3.setQuery("SELECT * FROM {{table_name}} WHERE cartodb_id > 10");
- setStyle: Change the style of the layer tiles
Example:
cartodb_gmapsv3.setStyle("#{{table_name}}{marker-fill:blue}");
- isVisible: Get the visibility of the layer.
Example:
cartodb_gmapsv3.isVisible();
- isAdded: Returns if the layer belongs to the maps or not.
Example:
cartodb_gmapsv3.isAdded();
- setInteractivity: Change the columns you want to get data (it needs to reload the tiles)
Example:
cartodb_gmapsv3.setInteractivity("cartodb_id, the_geom, magnitude");
- setOptions: Change any parameter at the same time refreshing the tiles once
Example:
cartodb_gmapsv3.setOptions({query: "SELECT * FROM {{table_name}} WHERE cartodb_id<100", interactivity: "cartodb_id,the_geom,magnitude"});
- setOpacity: Change the opacity of the layer
Example:
cartodb_gmapsv3.setOpacity(0.2);
- setBounds: Set bounds in the map using a new query or the default one
Example:
cartodb_gmapsv3.setBounds("SELECT * FROM {{table_name}} WHERE cartodb_id < 100");