Crater Lake National Park


Digital maps for the National Park Service

CartoDb Layer Handler


The CartoDb layer handler makes it easy to bring dynamic tiles from CartoDB into an NPMap web map.

NPMap currently supports bringing CartoDB tiles into maps created using all of the base APIs, though interactivity (hover and identify) operations are only supported by the Google and Leaflet base APIs. Only publicly-accessible CartoDB tables can be added to your web map.


  • Display
  • Hover**
  • Identify**
  • Routing (with the route module)

** See limitations below.


The CartoDb layer handler currently has some limitations. We are working on beefing up support for all of the features supported by CartoDB, but for now keep these in mind when working with the layer handler:

  • Interactivity only works for one CartoDb layer at a time. You can add multiple CartoDb layers to your map, but only one will support the hover and identify operations. An imperfect workaround for this is combining all of your data into a single CartoDB table and then using queries to hide/show information dynamically.
  • There are some conflicts between CartoDb and TileStream layers. Display should work fine, but interactivity (hover and identify) may be spotty.


CartoDb layers can be added via the layers config in the NPMap.config object. Here are the properties that can be set on a CartoDb layer object:

Property Type Required?
identify {Object} Used to customize the way data returned from an identify operation on this layer are displayed in the InfoBox. See the Customizing what is displayed in the InfoBox section of the NPMap.InfoBox documentation for information on this property.
name {String} X The name of the layer. This name is used by NPMap by controls and modules. It must be unique. name: 'National Parks'
query {String} The SQL string you want to use to query information out of the CartoDB table. See the CartoDB SQL API docs for more information. query: "SELECT * FROM national_parks WHERE code = 'ACAD'"
style {String} The style string. style: ''
table {String} X The ID of the CartoDB table you want to associate this layer with. id: 'national_parks'
type {String} X The only valid value for this layer type is CartoDb. type: 'CartoDb'
user {String} X The user id for your CartoDB account. user: 'nps'


In addition to the methods available in the NPMap.Layer module, the CartoDb layer handler contains a custom method that can be accessed via the NPMap.Layer.CartoDb namespace:

  • updateQuery(config, query, callback?)


Here is an example of a working layer config object:

  name: 'National Parks',
  table: 'national_parks',
  type: 'CartoDb',
  user: 'nps'

To see this layer config object in context within the larger NPMap.config object, take a look at the CartoDb example.