Sorry, you need to enable JavaScript to visit this website.

Map Examples

Map Examples

Have a look at our functional examples to see how easy it is to implement map features with the Maps SDK.
Speed up development by using our sample code snippets in your app.
Try all of this out with the Maps SDK Examples app!

Map Display

TomtomMap contains a variety of options, like a number of map layers: map
tiles and traffic tiles.

Map tiles

Allow your users to display the map in either raster or vector format:

  • Raster tiles are served as images. They require less processing power and memory to render, but have a larger file size than vector tiles.

  • Vector tiles take the form of data that describes map entries such as geographic points, forests, lakes, built up areas (as polygons), and roads (as lines). They are styled by means of a style sheet. Vector tiles can be scaled to different sizes without losing quality. The file size of vector tiles is smaller than that of raster tiles.

Sample use case 1: Your app is designed to use raster tiles for map display. You want to update the app with TomTom Online Maps raster tiles.

Sample use case 2: You want to take advantages of vector tiles features such as map 2.5 D perspective, custom map styles, etc.

Sample use case 3: Your app runs on devices with different capabilities. You want to use vector tiles for map display on powerful devices and raster tiles on devices with less processing power.

Use the code snippets below in your app to display the map with raster or vector tiles.

To select vector tiles:



To select raster tiles:



To turn off all tiles:



In this example you will see buttons that allow to switch between raster and vector tiles at runtime:


Raster tiles.


Vector tiles.

Traffic layers

Give your users the ability to see real time traffic in your mobile apps.

With Online Traffic Flow tiles your users will have information about congestion,
the speed of traffic on different road segments, and the difference between that speed and the
free-flow speed on the same road segments. You can find more information and details about
Online Traffic Flow tile parameters on
Online Vector Traffic Flow tiles or
Online Raster Traffic Flow tiles.

Online Traffic flow tiles

Traffic flow tiles are available in two formats: vector (.pbf) and raster (.png).
Vector tiles provide a possibility for visual customization and better visual experience.
Therefore, we recommend using the vector tiles for map and traffic display.
Raster tiles are especially suitable for low performance devices.

Vector traffic flow tiles are used by default for traffic flow in Maps SDK.
Vector traffic flow tiles are available from map zoom levels: 11 to 20.
Raster traffic flow tiles are available from map zoom levels: 0 to 18.
You can switch to raster traffic flow tiles by using the method:



You can change back to vector traffic tiles by using the method:



Traffic type and styles

Online Traffic tiles styles are represented in the SDK as Java data classes.
Online Traffic flow tiles style types are represented in the SDK as data classes.

The available vector traffic flow styles are listed below and can be set by method:

tomtomMap.getUiSettings().turnOnVectorTrafficFlowTiles(new TrafficFlowType.RelativeTrafficFlowStyle()); //default
tomtomMap.getUiSettings().turnOnVectorTrafficFlowTiles(new TrafficFlowType.AbsoluteTrafficFlowStyle());
tomtomMap.getUiSettings().turnOnVectorTrafficFlowTiles(new TrafficFlowType.RelativeDelayTrafficFlowStyle());


The available raster traffic flow styles are listed below and can be set by method:

tomtomMap.getUiSettings().turnOnRasterTrafficFlowTiles(new RelativeTrafficFlowStyle()); //default
tomtomMap.getUiSettings().turnOnRasterTrafficFlowTiles(new AbsoluteTrafficFlowStyle());
tomtomMap.getUiSettings().turnOnRasterTrafficFlowTiles(new RelativeDelayTrafficFlowStyle());
tomtomMap.getUiSettings().turnOnRasterTrafficFlowTiles(new ReducedSensitivityTrafficFlowStyle());


Sample use case: You want to visualize traffic information in your app so your users can adjust
their commute based on traffic information.

Use the code snippets below in your app to enable and visualize the vector traffic flow layer on
the map:



You can turn off traffic flow by using the method:



Information about set style:

VectorTrafficFlowType style = tomtomMap.getUiSettings().getTrafficVectorFlowStyle();


Traffic incidents

Online Traffic incidents style types are represented in the SDK as a data class. The available
traffic incidents options are the following



You can turn off traffic incidents by using the method:




Traffic vector flow layer on vector map.


Traffic raster flow shown on raster map.


Traffic raster incidents layer in sample app.


Traffic raster incidents and raster flow layer on raster map.


No traffic in sample app.

My location layer

Allow your user to display and track its current location. By default, it is disabled.
Permissions to use GPS are automatically handled by the map.

Sample use case: you want to display user’s current location and use it to plan a route.

To enable location tracking:


To get user’s current location:

Location location = tomtomMap.getUserLocation();

Map language

Allow your user to see the map in different languages to make your app international.
The language parameter determines the language of labels on the map.
It does not affect any proper nouns, like the names of streets, plazas, etc.
List of the supported languages can be found

Sample use case: You want to have all labels only in British English

To change language for the map:



Map labels in English


Map labels in Russian


Map labels in Dutch

Geopolitical view

Allow your user to see the map boundaries based on unified or local country views.
The local view is available for a particular area of the world that is considered as disputed by two or more countries.
You can change the geopolitical view of your map. If you don’t specify a geopolitical view the "Unified" view will be used.
The Israel Geopolitical view is currently available only for vector maps.

List of the supported views can be found here.

Note: Inside India’s territory only the "IN" geopolitical view is available without the possibility of being overridden.

Sample use case: You want to display local map view for Israel.

To change geopolitical view for the map:



Israel international view


Israel local view

Map manipulation

When you use the TomtomMap in your application, users would like to play
with it in a variety of ways. In this section you will learn how to
implement such actions and how to register for their callbacks.

Map centering

Center the map in your mobile app either at the current coordinates or any other location, at the zoom level of your choice.

Sample use case: You want to display the maps for selected cities in specific zoom levels. Your users should be able to easily to switch between different locations.

Use the code snippets below in your app to display maps of different locations (in this case, the current location and the TomTom offices in Amsterdam and Berlin).

The example shows how to center the map on Amsterdam with the zoom level set to 10:




Map centered on Amsterdam with 10 zoom level


Map centered on London with 10 zoom level


Map centered on Berlin with 10 zoom level

Map perspective

Set either 2D map perspective for typical map view mode, or 2.5D map perspective for custom scenarios such as
moving the map.

Sample use case: You want to switch from 2D to 2.5D modes to support following the moving location in your app.

Use the code snippets below in your app to switch between perspectives.

Note, that switching between 2D and 3D mode only changes the perspective. The zoom level and map orientation are
set with the methods described in the "Map centering" example.

In order to change the map mode to 2-dimensional, you need to call the
following method:



To change it back to 3D simply apply the other option setting:




3D map perspective


2D map perspective

Map events

Implement any action you need to be triggered on one of the following map events:

  • Panning.

  • Single press.

  • Double press.

  • Long press.

Sample use case: In your app, users invoke one behavior with a single press and another with a long press.

Use the code snippets below in your app to catch map events. In this example, the action is simply to display a toast with latitude and longitude on each map event. Of course, you can implement other cool features instead.

If you want to receive callbacks after a map is clicked, long-clicked or
panned, then you need to define your own TomtomMapCallback listeners:

private TomtomMapCallback.OnMapClickListener onMapClickListener =
        new TomtomMapCallback.OnMapClickListener() {
            public void onMapClick(@NonNull LatLng latLng) {
private TomtomMapCallback.OnMapLongClickListener onMapLongClickListener =
        new TomtomMapCallback.OnMapLongClickListener() {
            public void onMapLongClick(@NonNull LatLng latLng) {
private TomtomMapCallback.OnMapViewPortChanged onMapViewPortChangedListener =
        new TomtomMapCallback.OnMapViewPortChanged() {
            public void onMapViewPortChanged(float focalLatitude,
                                             float focalLongitude,
                                             double zoomLevel,
                                             float perspectiveRatio,
                                             float yawDegrees) {


Then you just have to set them to your TomtomMap instance:



In this example you will see a Toast with latitude and longitude of a
point that was clicked on the map, but you can utilize this information
in your own manner.


Receive callbacks after the map is clicked


Receive callbacks after the map is long clicked


Receive callbacks after the map panning

Enable and disable gestures

You can disable gestures such as zooming, panning and rotating in your application by passing gestures settings object to tomtomMap:
By default all gestures are enabled.

Disable zooming gesture



Disable the rotating gesture



Disable the tilting gesture



Disable the panning gesture



You can turn off more than one gesture by setting up the mask on properties like below:



If you want to enable gestures, pass the GesturesDetectionSettings object to the tomtomMap object like below:



or even in the simpler way:



Map UI Extensions

Use default compass, current location buttons, zooming and panning controls built-in Maps SDK.
You can read more on Map UI extensions page.

Sample use case 1: You want to provide your users with compass, current location, panning and zooming controls so they can quickly center the map on their current location, set it to display north at the top of the screen after rotating the map, pan or zoom the map You can use the default controls provided with Maps SDK.

Sample use case 2: You want to provide your users with compass, current location, panning and zooming controls, and you want to use custom icons that are designed for your app style.

Sample use case 3: In some of the screens in your app, you want to remove the compass, current location, panning and zooming controls.

Since all ui elements are fully customizable because the android view’s properties are exposed, changing the
default icons for them is straight forward:

ArrowButtonsGroup arrowButtons = tomtomMap.getUiSettings().getPanningControlsView().getView();


ZoomButtonsGroup zoomButtons = tomtomMap.getUiSettings().getZoomingControlsView().getView();



Default ui extensions controls


Default ui extensions controls - Hidden


Custom ui extensions controls

Map annotations


Utilize different Maps SDK markers features to provide engaging functionality in your mobile app.

The main marker features are as following:

  • Customizable marker icons – use the default TomTom marker or favorite icons or use your own

  • Simple and decal marker mode – choose how the marker is rendered on the map

  • Draggable markers – allow your users to drag and drop a marker around the map

  • Animated markers - use GIFs as marker icons

You can find details of each of the marker feature below the examples on this page.

Sample use case: In your app, you want to display a number of markers, to mark places on the map. Use the code snippet below to display a single marker at specific coordinates on the map.

MarkerBuilder markerBuilder = new MarkerBuilder(position)
        .icon(Factory.fromResources(getContext(), R.drawable.ic_favourites))
        .markerBalloon(new SimpleMarkerBalloon(positionToText(position)))
        .tag("more information in tag").iconAnchor(MarkerAnchor.Bottom)
        .decal(true); //By default is false

Examples are below:


Icon Marker


Decal Marker

Create a simple marker with default icon and add it to the map, only location needs to by specified:

MarkerBuilder markerBuilder = new MarkerBuilder(position)
        .markerBalloon(new SimpleMarkerBalloon(positionToText(position)));

Marker selected

You can implement an observable of marker selected event. You can do that with the global listener OnMarkerClickedListener for all markers that has to be registered on MarkerSettings as following:



For that purpose the passed object has to implement the below interface:

interface OnMarkerClickListener {
     * Called when the user clicks on the marker.
     * @param marker Selected marker.
    void onMarkerClick(@NonNull Marker marker);


You can remove all markers from the map in this way:


You can remove all the markers one-by-one in this way:

  • Remove all markers with the tag "tag".

  • Remove marker by id.



Simple and decal marker modes

  • Focal (default) - where the icon always stands vertically even when the map is rotated. All nine callout anchor points are supported with this annotation type.

  • Decal - where icon sticks to the map even when the map is rotated. Only one callout anchor point is supported for decal MarkerAnchor - Bottom.

Mixing icons of different modes is generally unsupported and advised against, as there are unresolvable depth-sorting issues and the results
will not always look correct. It is safe to mix some modes, however, such as either of the decal modes with any of the standing modes.

Non-decal icons may optionally cast a shadow on the map. You will need to leave additional empty space between icons in your drawable if you
specify a non-zero blur amount.

Draggable markers

Thanks to this feature your users are able move existing markers around the map. They long click on a marker
that is on the map to start dragging it, they drop the marker on a selected position by releasing
the finger from the screen.

In order to do that you need to set 'draggable' to true.

MarkerBuilder markerBuilder = new MarkerBuilder(position)
        .markerBalloon(new SimpleMarkerBalloon(positionToText(position)))

It is also possible to register to receive Marker’s dragging callbacks.

As an example you can create listener like this one:

TomtomMapCallback.OnMarkerDragListener onMarkerDragListener = new TomtomMapCallback.OnMarkerDragListener() {
    public void onStartDragging(@NonNull Marker marker) {
        Timber.d("onMarkerDragStart(): " + marker.toString());
        displayMessage(R.string.marker_dragging_start_message, marker.getPosition().getLatitude(), marker.getPosition().getLongitude());

    public void onStopDragging(@NonNull Marker marker) {
        Timber.d("onMarkerDragEnd(): " + marker.toString());
        displayMessage(R.string.marker_dragging_end_message, marker.getPosition().getLatitude(), marker.getPosition().getLongitude());

    public void onDragging(@NonNull Marker marker) {
        Timber.d("onMarkerDragging(): " + marker.toString());

And register it to receive events related to dragging the marker over the map:


Animated markers

Thanks to this feature you can use GIFs as marker icons. For this purpose, you need to place your images
in the assets folder and then use them in the following way:

MarkerBuilder markerBuilder = new MarkerBuilder(position)
    .icon(Icon.Factory.fromAssets(view.getContext(), SAMPLE_GIF_ASSET_PATH));

Marker anchoring

You have a possibility to change the anchoring point for your icon. The anchor specifies which point of an annotation image is attached to the map. The annotation will rotate around this anchoring point when rotating the map.
You can use the default image representation of an annotation which is attached to the bottom height center width as presented in the figure below.
You can change this behavior by MarkerAnchor enumeration on the builder.
E.g. if you want to use a crosshair annotation image, you should set the anchor to MarkerAnchor.Center

MarkerBuilder markerBuilder = new MarkerBuilder(position)
        .icon(Factory.fromResources(getContext(), R.drawable.ic_favourites))
        .markerBalloon(new SimpleMarkerBalloon(positionToText(position)))
        .tag("more information in tag").iconAnchor(MarkerAnchor.Bottom)
        .decal(true); //By default is false

All possible anchors are define in the enum:

 * Copyright (c) 2015-2018 TomTom N.V. All rights reserved.
 * This software is the proprietary copyright of TomTom N.V. and its subsidiaries and may be used
 * for internal evaluation purposes or commercial use strictly subject to separate licensee
 * agreement between you and TomTom. If you are the licensee, you are only permitted to use
 * this Software in accordance with the terms of your license agreement. If you are not the
 * licensee then you are not authorised to use this software in any manner and should
 * immediately return it to TomTom N.V.


 * The anchor property of the marker. Following values are possible:
 * (-0.5,0)       (0, 0)    (0.5,0)
 * TopLeft          Top     TopRight
 * (-0.5,-0.5f)  (0,-0.5f)  (0.5,-0.5f)
 * Left           Center    Right
 * (-0.5,-1f)   (0,-1)    (0.5,-1f)
 * BottomLeft     Bottom    BottomRight
public enum MarkerAnchor implements Serializable {

    Center(0f, -0.5f), Left(-0.5f, -0.5f), Right(0.5f, -0.5f), Top(0, 0), Bottom(0, -1f),
    TopLeft(-0.5f, 0), TopRight(0.5f, 0), BottomLeft(-0.5f, -1f), BottomRight(0.5f, -1f);

    public float xIconOffset;
    public float yIconOffset;

    MarkerAnchor(float xIconOffset, float yIconOffset) {
        this.xIconOffset = xIconOffset;
        this.yIconOffset = yIconOffset;

Marker performance

For performance purposes, it is recommended to combine multiple icons
into a single drawable, and specify the sub-region of the icon you are
interested in. If you use this approach, be sure to leave at least one
empty pixel between icons in your image to keep the edges from blending
together as the icons are scaled.

Markers clustering

Allow your users to cluster markers for better visualization. By default, markers clustering is disabled. You can decide per each marker, if it should be included in the clustering process or not (e.g. you want to have a few markers that are never clustered). To manipulate marker clustering, use MarkerSettings obtained from TomtomMap.

Sample use case: You want to display the distribution of parking spots across the city. Individual parking spots are shown only at higher zoom levels, otherwise data is clustered for better visualization.

To enable markers clustering:


To flag a marker that it should be clustered:

MarkerBuilder markerBuilder = new MarkerBuilder(position)
        .markerBalloon(new SimpleMarkerBalloon(positionToText(position)));

Examples are shown below:


Lower zoom level


Higher zoom level


Allow your users to display and customize balloons in a few lines of code.

Sample use case: You would like to learn more about a place on the map.
Depending on the selected location, the app displays a balloon containing either text or additional
information such as icons or pictures.

Every Marker can be linked with corresponding balloon to display detailed information.
Balloon can be triggered in two ways:

  • Automatically, if the annotation is tapped on the map

  • Calling Marker#select() method

A balloon can be closed in the following ways:

  • Automatically, if a user taps on the map

  • Automatically, if a user taps on another Marker

You can use one of build in balloon views that provide easy way to display it, like SimpleMarkerBalloon
that is used to display default balloon.
A balloon object is an instance of MarkerBalloon that has to implement ViewAdapter interface.

Default Balloons

By default every marker when selected will display default balloon which is instance of BaseMarkerBalloon
filled with coordinates of marker. BaseMarkerBalloon is a view model of the marker balloon view.
To add a property to the model, you need to use this function:

BaseMarkerBalloon markerBalloon = new BaseMarkerBalloon();
markerBalloon.addProperty("key", "value");

Model can be used to inflate balloon view.

Property Marker#canShowBalloon by default is set to true. By changing it to false marker can still
be selected but no balloon will appear.
Property Marker#selected determines if marker is selected at all.
By default is false.

There is only one defined common model property key, which can be used in BaseBalloonViewAdapter
to inflate the balloon, however more property key can be added.

 * text property key, one of the most used properties for balloon.
public static final String KEY_TEXT = "text";

To display a balloon model we need to create and set a balloon view adapter:

 * Adapter of balloon view. Implement interface to inflate balloon adapter.
public interface BalloonViewAdapter<T extends MarkerBalloon> {

     * Callback which is call when inflating model.
     * @param container - container where marker or balloon item will be inflated
     * @param marker - marker which has a balloon
     * @param markerBalloon - view model of marker balloon
    <M extends T> View onCreateView(ViewGroup container, Marker marker, M markerBalloon);

     * @param view  the root view of inflating layout
     * @param marker value which is used to fill layout
     * @param markerBalloon view model of the marker balloon
    <M extends T> void onBindView(View view, Marker marker, M markerBalloon);

     * View of the marker balloon
     * @return can be null when balloon is not inflated yet.
    View getBalloonView();

     * Get balloon offset from tke marker.
    Point getBalloonOffset(Marker marker);

There are a few implementations of balloon view adapter provided. These implementations cover the commons cases for balloons.

Simple balloons


Figure 1. Simple balloon


To create a simple balloon (simple balloon is a balloon with one text line):

  1. Create a model for the marker balloon with text properties: new SimpleMarkerBalloon("Welcome to TomTom")

  2. Create a balloon view adapter: TextBalloonViewAdapter supports one text line balloon view model.

  3. Set an adapter.

  4. All steps bellow:

tomtomMap.getMarkerSettings().setMarkerBalloonViewAdapter(new TextBalloonViewAdapter());
SimpleMarkerBalloon balloon = new SimpleMarkerBalloon("Welcome to TomTom");
MarkerBuilder markerBuilder = new MarkerBuilder(Locations.AMSTERDAM_LOCATION)

Marker m = tomtomMap.addMarker(markerBuilder);
balloon.setText("Welcome to TomTom");


If any adapter is not set by user, TextBalloonViewAdapter is set by default.
Because of that points 2-4 are optional.

Custom balloons

Despite that you can use default balloon, SDK allows you to create fully customizable ones. Balloon is nothing more than Android layout implementation. Custom layout can be built in the way that you like either from Android Studio Builder or programmatically.


To create a custom layout balloon:

  • Create a model for the marker balloon - BaseMarkerBalloon doesn’t have properties by default.
    Properties can be added by the addProperties(key, value) method.

  • Use SingleLayoutBalloonViewAdapter and provide the layout in the constructor.

  • Set an adapter.

  • All steps bellow:

tomtomMap.getMarkerSettings().setMarkerBalloonViewAdapter(new SingleLayoutBalloonViewAdapter(R.layout.custom_balloon_layout));
MarkerBuilder markerBuilder = new MarkerBuilder(Locations.AMSTERDAM_LOCATION)
        .markerBalloon(new BaseMarkerBalloon());
Marker m = tomtomMap.addMarker(markerBuilder);

To manage the custom ballon view model override method of SingleLayoutBalloonViewAdapter:

 * @param view  the root view of inflating layout
 * @param marker value which is used to fill layout
 * @param markerBalloon view model of the marker balloon
<M extends T> void onBindView(View view, Marker marker, M markerBalloon);

or create own class which extends BalloonViewAdapter and override all abstract methods.


Allow your users to draw shapes like circles, polygons and polylines on your map to mark different areas on the map.

Sample use case: You are developing an app for a delivery company and need to illustrate ranges of the transportation area around different cities. What you need to do is e.g. to render circles round cities with radiuses indicating zones of deliveries. The details on the example implementation of shapes rendering are described below.

The TomtomMap supports several shape overlays which can be easily
created by using corresponding overlay builders. These are:

  • PolygonBuilder

  • PolylineBuilder

  • CircleBuilder

Shape overlays are immutable. That is: once they have been created their
shape cannot be changed. Visibility and color can be changed. If you
want to change a shape, you must remove the existing shape and replace
it with a new one. It is the responsibility of the framework user to take care
about performance and number of shapes in use. You should use as few shapes as
possible, and hide or dispose the ones that are not being displayed.

To create shape overlays:

Polygon polygon = PolygonBuilder.create()


Polyline polyline = PolylineBuilder.create()


Circle circle = CircleBuilder.create()


To register for click events:



To unregister from click events:




Polygon overlay


Polyline overlay


Circle overlay

Route display

You can display a route on the map and customize its origin and destination icons.
It is also possible to specify the fill color, outline color and width of the route.

Sample use case: when you add the route, you would like to highlight the starting and
the destination points. Also you would like to plan several routes simultaneously
with different origin and destination points and use different icons.


TomtomMap tomtomMap object was created and configured. Route coordinates are

Origin and destination icons customization

If you need to customize start and destination icons, you should create icons through Icon class.

The icon can be created in following ways:

  • with constructor:

    Icon startIcon = new Icon(name, drawable);
  • with Icon.Factory.fromDrawable method:

    Icon startIcon = Icon.Factory.fromDrawable(name, drawable);

    where name is String object and drawable is Drawable object.

  • with Icon.Factory.fromResources method:

    Icon endIcon = Icon.Factory.fromResources(context, iconId);

    where context is your Context object and iconId is an icon resource identifier.

When icons are created, you can add them to route using startIcon and
endIcon methods of RouteBuilder class,

Route customization

You can create a route with custom style properties like fill color, outline color and width. Firstly, you need to create RouteStyle object:



Next, you need to pass routeBuilder to addRoute method of tomtomMap, e.g.:

RouteBuilder routeBuilder = new RouteBuilder(route.getCoordinates())
final Route mapRoute = tomtomMap.addRoute(routeBuilder);


If you don’t call startIcon and endIcon there will be no icons on route. You can specify
only start icon by calling only startIcon or only end icon by calling only endIcon.

If you don’t call style then the default style will be applied.

You can use different images and styles for different routes.

Clear map

To clear map, delete all polylines, polygons, markers and routes use
clear method.

 * Clear from map all annotation, like markers, polyline, polygon's, routes or chevrons.
void clear();

Dynamic map

Follow the chevron

Allow your users to follow their changing positions on the map e.g. when driving. When a new
location is set, the animation moves the chevron to the new position.

Sample use case 1: You want to show your user position when driving.

Custom chevron indicator

You can set a custom icon for the chevron indicator.

To create custom chevron:

ChevronBuilder chevronBuilder = ChevronBuilder.create(activeIcon, inactiveIcon);
chevron = tomtomMap.getDrivingSettings().addChevron(chevronBuilder);

Chevron tracking mode

Additionally, it is possible to track the chevron. It means that the camera/map and the chevron
move when a new location is received so that the map is always centered on the chevron with
the bearing of the drive. In the tracking mode, rotate and pan gestures are blocked.
The user can change only zoom level, while the map camera is automatically adjusted
to follow the chevron.

To start tracking selected chevron:


To stop tracking selected chevron:



Chevron overview


Chevron tracking