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:

tomtomMap.getUiSettings().setMapTilesType(MapTilesType.VECTOR);

To select raster tiles:

tomtomMap.getUiSettings().setMapTilesType(MapTilesType.RASTER);

To turn off all tiles:

tomtomMap.getUiSettings().setMapTilesType(MapTilesType.NONE);

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 onOnline Vector Traffic Flow tiles orOnline 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:

Traffic incidents

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

tomtomMap.getUiSettings().turnOnRasterTrafficIncidents();

You can turn off traffic incidents by using the method:

tomtomMap.getUiSettings().turnOffTrafficIncidents();

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:

tomtomMap.setMyLocationEnabled(true);

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 foundhere.

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.

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 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:

tomtomMap.set2DMode();

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

tomtomMap.set3DMode();

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:

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:

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.

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

/**
* 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.
*/packagecom.tomtom.online.sdk.map;
importjava.io.Serializable;
/**
* 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
*/publicenum MarkerAnchor implementsSerializable {
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);
publicfloat xIconOffset;
publicfloat 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.

Balloons

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:

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.
*/publicstaticfinalString KEY_TEXT = "text";

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

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.

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

Shapes

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.

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.

Prerequisites:

TomtomMap tomtomMap object was created and configured. Route coordinates are
prepared.

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 = newIcon(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 andendIcon 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:

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.