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.

    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 supports two styling languages:

    • High-level CartoCSS styling language. Mobile SDK has a few limitations and supports several extensions to the base specification as decribed here
    • Low-level Mapnik XML styling language. Again, the SDK implementation has a few notable differences and extensions that are documented here