Your search returned no results

Try another search term or view Stack Exchange, where we have active conversations with Developers about GIS.
    Support channel in Stack Exchange

    Thousands of developers around the world have helped make CartoDB a success, and we have active conversations with them about GIS in Stack Exchange.

    Go to Stack Exchange

    Developer Guide to SDK Features

    The following advanced features can be customized by mobile app developers.

    Listening to events
    Clusters to display multiple points of interest as objects
    Ground overlays to project a bitmap image over a basemap
    Vector styles for vector map tiles

    Listening to Events

    Once you have implemented and set the MapEventListener interface for a MapView, the following listener events are generated as parameters:

    • onMapMoved - map moving, zooming, tilting, rotating. This event is called for each pixel movement, so any changed to this parameter can make map panning animation visibly slower

    • onMapClicked(MapClickInfo) - map clicked, provides info about click:


      • ClickPos - geographical click position (in map projection)

    • onVectorElementClicked(VectorElementsClickInfo) - any vector object on map was clicked (could be line,polygon,point,marker,balloon popup or a 3D model)

      • ClickType - same description as above, results include CLICK_TYPE_SINGLE, CLICK_TYPE_LONG, CLICK_TYPE_DOUBLE or CLICK_TYPE_DUAL

      • VectorElementClickInfos - sorted list of clicked objects, nearest is first. Each ClickInfo contains:

        • ClickPos - geographical click location

        • ElementClickPos - click locaton projected to element, different from ClickPos if click was not precisely on object (which it never really is)

        • Distance - distance from the vector element to the camera

        • Order - order of element within VectorElementClickInfos

        • VectorElement - the actual clicked element

    Implement MapEventListener

    NOTE: This is a map event listener, if you wish to listen to vector element clicks, implement VectorElementEventListener in a similar fashion and attach it to a Vectorlayer

    Create a new class called MyMapEventListener which implements MapEventListner interface.

    Initialize Listener

    Apply the following code to initialize listener events for map clicks.

    Show/Hide Labels for Map Clicks

    MapEventListener contains special functionality that shows, or hides, a small label text over a clicked object. The following label click event rules apply:

    • If you click on an object, it creates another map object as a BalloonPopup. This contains the text from the metadata of the clicked object

      For this reason, our samples apps include a Metadata field value. You can use the metadata value directly, or use the object unique ID as the metadata, to query details about the clicked object from the database.

    • When a viewer clicks a new location on the map (or click another map object), the original BalloonPopup is deleted, and new one appears at the click location

    • The BalloonPopup is added to the DataSource, which is linked existing map layers. The same DataSource is used for other vector elements on a map


    When you have too many Points of Interest (POIs) that cannot be displayed as individual markers, it results in a cluttered map. It also effects the rendering performance of your map, and may even result in running out of memory. As an alternative, replace individual objects with clusters.

    Clusters are markers which display a location of several objects, and typically indicate the number of markers within each object.

    Cluster sample

    CARTO Mobile SDK has built-in cluster feature, which is highly customizable. You can define the following options in your app code:

    • Styling the cluster objects
    • Dynamically generate cluster object styles. For example, automatically display the number of objects in each cluster
    • Define the minimum zoom level for clusters
    • Set the minimum distance between objects, before it becomes a cluster
    • Indicate the action when clicking on marker. For example, zoom in, or expand the cluster without zooming

      Tip: The cluster expand feature is useful for small clusters (containing up to four objects inside)

    API Methods for Clusters

    Clusters are generated dynamically, based on VectorDataSource data that loads the map layer. If using an API, it works as a unique layer with the ClusteredVectorLayer method, and includes the following parameters in the a hierarchal order:

    1. Select the layer DataSource

      In most cases, the LocalVectorDataSource function contains all the elements to request the data. It is important that the DataSource displays all elements in a layer, and does not limit it to the current map visualization bbox (bounding box)

    2. ClusterElementBuilder defines a single method buildClusterElement

    Define Cluster Data and Layer

    Define ClusterElementBuilder

    The Cluster Element Builder takes set of original markers (map objects) as input, and returns one object (or another VectorElement, such as a Point or BalloonPopup) which dynamically replaces the original marker.

    Note: It is highly recommended to reuse and cache styles to reduce memory usage. For example, a marker style with a specific number is only created once. Android and iOS samples use platform-specific graphic APIs to generate the bitmap for the marker. .NET example only uses BalloonPopup, which is slower but works the same across all platforms.

    Ground Overlays

    Ground overlays projects a bitmap (PNG, JPG) image of a defined coordinate over a basemap. For example, a ground overlay bitmap may be used to show an indoor floorplan over a building map.

    Example of mobile ground overlays

    Note: Your bitmap must define geographical map coordinates with Ground Control Points. Currently, Mobile SDK supports three or four points on a bitmap image.

    Ground Overlay Requirements

    The following requirements allow you to ground overlays with the Mobile SDK.

    • linear affine transformation enables you to set three control points to set the location, size, and rotation of the bitmap

    • perspective transformation enables you to control four control points for the bitmap

    • If you have more control points in your data, it is suggested to choose three or four of your best ones, and select those as your ground control settings

    • Control points must be defined in the app code. Mobile SDK does not automatically gather control points from the source file metadata

      For example, if you need GeoTIFF, ESRI World File, MapInfo TAB, Geospatial PDF, or other referenced data, you will get this from the GIS Extension (see below).

    • The entire bitmap must fit to device memory (RAM). Depending on the target device, the maximum size could vary. For example, the target device maximum size might be 2000x2000 pixels.

      Tip: For larger rasters, the SDK Extensions allow you to display any size bitmap, up to hundreds of megabytes. These bitmaps are read directly from common GIS raster formats (such as GeoTIFF, BSB, ECW, MrSID, JPEG2000, and so on). Additionally, the source data can be entered using different coordinate systems. Please contact us if you are interested in enabling SDK Extensions as part of your account.

    Code Samples

    This example uses only one geographical coordinate. The building size is known, and the building direction is facing north. This allows us to calculate other ground points with the code. Four ground control points are set to the corners of the bitmap, which typically returns the most accurate result.

    Tip: The following sample code assumes that you have the jefferson-building-ground-floor.jpg bitmap file as part of your application project.

    • For Android, this image is located under assets
    • In iOS, it can be located anywhere in your project

    Vector Styles

    When you create a basemap, the Mobile SDK package enables you to select one of our pre-defined, built-in basemap styles:

    • CARTO_BASEMAP_STYLE_VOYAGER - Light style, used as a general map where you need to distinguish forests, rivers, streets etc.
    • CARTO_BASEMAP_STYLE_DARKMATTER - Dark style, best when displaying light-styled data
    • CARTO_BASEMAP_STYLE_POSITRON - Gray style, used when displaying dark-styled data

    You can customize basemap styling by setting the colors, transparency, line styles (width, patterns, casings, endings), polygon patterns, icons, text placements, fonts, and other vector data parameters.

    CARTO uses Mapnik XML style description language for customizing the visual style of vector tiles. Our styling is optimized for mobile and contain some unique style parameters. In general, you can reuse your existing Mapnik XML, or CartoCSS, styling files and tools (such as TileMill/Mapbox Studio).

    Vector styling is applied in the mobile client, where the style files are bundled with the application installer. The application can change the styling anytime, without reloading vector map data. This enables you to download map data once, and change styling from “day mode” to “night mode” with no new downloads.

    CARTO map rendering implementation is intended for real-time rendering. As a result, several limitations apply.

    Mapnik Style Format

    Mapnik style definitions are a common file format for map styles, based on XML. It was originally created for Mapnik, but is used by other software, such as our Mobile SDK. The file format specifications are located in this XMLConfigReference document. There are several ways you can apply these styles:

    1. Use CARTO provided styles

    2. Modify the style.xml, located inside the sample style, with your own edits

    3. Create your own styles using a Mapnik editor tool

      Note: It is recommended to use the free MapBox Studio tool, which uses CartoCSS for primary style definitions. While the Mobile SDK does not use CartoCSS styles, you can modify and export Mapnik XML styles to be compatible with the Mobile SDK.

    Mapnik Limitations

    Please note the following limitations with Mapnik style formats.

    • There are no built-in fonts, fonts must be explicitly added to the project

    • Loading SVG icons is not supported, such icons should be converted to PNG format (Mapnik provides a svg2png utility)

    • Original layer ordering is not always preserved, texts are always drawn on top of 2D geometry. 3D buildings are drawn on top of texts

    • Layer opacity works per element, not per layer as in Mapnik. For non-overlapping elements, the result will be same. For overlapping elements, there are likely artifacts

    • comp-op feature is not supported (neither is layer/symbolizer)

    • line-join parameter is ignored, only miter line join is used

    • GroupSymbolizer and RasterSymbolizer are currently not supported

    • Text characters are rendered individually. If characters overlap, the halo of one character may cover glyph of another character. The suggested workaround is to increase spacing, or decrease the halo radius

    Note: The Mobile SDK does not implement 100% of the tags and features of Mapnik. This lists just a few of the Mapnik limitations, there are additional Mapnik XML features that are not standard. If you need some an unimplemented styling option, please contact us.

    Creating Vector Style Packages

    CARTO vector styles are distributed as zip-archives. All style-related files and folders must be placed into a single zip file.

    The most important part of the style is the style definition file, typically named project.xml. This file contains style descriptions for all layers, and usually references other files, such as fonts, icons, and pattern bitmaps (which should be placed in various subfolders).

    Vector Style Performance

    When using vector styles, the following recommendations are suggested for optimal performance:

    • Multiple symbolizers per layer may have very large performance hits. If possible, move each symbolizer into separate layer

    • BuildingSymbolizer requires an expensive OpenGL frame buffer read-back operation, and may perform very poorly on some devices (such as the original iPad Retina)

    • To increase performance, it is suggested to use power-of-two dimensions for bitmaps

    SDK Extensions for Mapnik XML style files

    The following CARTO specific extensions are specific to Mapnik XML style files.


    NutiParameters describe additional parameters that can be used in styles and controlled in the code (from MBVectorTileDecoder).

    • Parameters are typed, have default values and can be used as variables within nuti namespace in the style (for example, [nuti::lang])

    • Some parameters may have _ prefix in their name. Such variables are reserved and should not be updated directly by the application

    The following is a simple example of NutiParameters section, located in the style xml file:

    `  <NutiParameter name="lang" type="string" value="en" />`


    Metavariables add support for dynamic variable look-up. Variable names may depend on other variables. For example, [name_[nuti::lang]].

    If the value of nuti::lang is ‘en’, this metavariable expression would be equal to [name_en] expression.

    Conditional Operator

    Conditional operator ?: adds support for simple control flow management. It is similar to C language conditional operator and can be used in all expressions. For example:

    [nuti::lang] == 'en' ? 'English' : 'Other'

    3D Texts and Markers

    Mapnik MarkersSymbolizer and TextSymbolizer support additional values nutibillboard for placement parameter. This enables texts and markers to act as billboards (always facing the viewer), even when screen is tilted. This option can be used to give markers and texts more ‘3D-like’ appearance. For example,

    <MarkersSymbolizer placement="nutibillboard" fill="#666666" file="icon/[maki]-12.svg" />

    Supported Symbolizers and Parameters

    The following lists contains all supported symbolizers and parameters for vector styles:

    • PointSymbolizer: file, opacity, allow-overlap, ignore-placement, transform

    • BuildingSymbolizer: fill, fill-opacity, height, geometry-transform

    • LineSymbolizer: stroke, stroke-width, stroke-opacity, stroke-linejoin, stroke-linecap, stroke-dasharray, geometry-transform

    • LinePatternSymbolizer: file, fill, opacity, geometry-transform

    • PolygonSymbolizer: fill, fill-opacity, geometry-transform

    • PolygonPatternSymbolizer: file, fill, opacity, geometry-transform

    • MarkersSymbolizer: file, placement, marker-type, fill, opacity, width, height, spacing, allow-overlap, ignore-placement, transform

    • TextSymbolizer: name, face-name, fontset-name, placement, size, spacing, fill, opacity, halo-fill, halo-opacity, halo-radius, allow-overlap, minimum-distance, text-transform, orientation, dx, dy, wrap-width, wrap-before, character-spacing, line-spacing, horizontal-alignment, vertical-alignment

    • ShieldSymbolizer: name, face-name, fontset-name, placement, size, spacing, fill, opacity, halo-fill, halo-opacity, halo-radius, allow-overlap, minimum-distance, text-transform, orientation, dx, dy, wrap-width, wrap-before, character-spacing, line-spacing, horizontal-alignment, vertical-alignment, file, shield-dx, shield-dy, unlock-image

    CartoCSS Extensions for Vector Styles

    Metavariables and nutiparameters are also available as CartoCSS style extensions.