Map examples
Map examples
Map Display
The TomTomOnlineSDKMaps contains variety of options, like various 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.
[self.mapView setTilesType:self.mapTiles];
![]() Raster tiles. |
![]() Vector tiles. |
Traffic layers
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:
self.mapView.trafficTileStyle = [TTRasterTileType setStyle:TTRasterStyleRelative];
Traffic raster type style
Online Traffic flow tiles style types are represented in the SDK as an enum. The available raster traffic flow styles are the following:
TTRasterStyleRelative,
TTRasterStyleAbsolute,
TTRasterStyleRelativeDelay,
TTRasterStyleReducedSensitivity
You can change back to vector traffic tiles by using the method:
self.mapView.trafficTileStyle = [TTVectorTileType setStyle:TTVectorStyleRelative];
Vector traffic flow type style
Online Traffic flow tiles style types are represented in the SDK as an enum. The available raster traffic flow types are the following:
TTVectorStyleRelative,
TTVectorStyleAbsolute,
TTVectorStyleRelativeDelay
You can turn on/off traffic flow by using the method:
self.mapView.trafficFlowOn = self.trafficOn;
Traffic incidents
Online Traffic incidents style types are represented in the SDK as an enum. The available traffic incidents options are the following:
TTTrafficIncidentsStyleRaster
self.mapView.trafficIncidentsStyle = TTTrafficIncidentsStyleRaster;
You can turn on/of traffic flow by using the method:
self.mapView.trafficIncidentsOn = self.incidentsOn;
![]() 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. |
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 here.
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 international 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. As a result, each country can show this area as a part of his country. List of the supported views can be found here.
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
|
Custom styles
Allow your user to create and provide the map with one or more custom styles for vector map tiles.
Modify default TomTom style
The best way to create a custom style is to modify the default TomTom style for vector maps using the Maputnik editor. You can find the json map style in the resources directory. The tutorial on how to modify the style is available for all Maps SDKs (for Android, iOS and Web) here link. Note, that after step 9 of the linked tutorial, you need to save the json file and place it in resources directory of your app project.
Provide your style You can provide an external map style file on the server and provide the URL. Sprites and fonts should be stored locally in the application. Currently, we don’t support loading resources and fonts from a server.
Sample use case: You want to display a night styled map at night or in a tunnel.
To change the style of the map:
NSString* customStyle = [[NSBundle mainBundle] pathForResource:@"style" ofType:@"json"];
[self.mapView setStylePath:customStyle];
![]() Basic style |
![]() Night custom style |
Map manipulation
When you use the TomTomOnlineSDKMaps 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:
[self.mapView centerOnCoordinate:self.currentLocation withZoom:10];
![]() Map centered on Amsterdam with 10 zoom level |
![]() Map centered on GPS 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 perspectived.
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.
Perspective ratio can be changed fluent in value - false to true.
[self.mapView setPerspective3D: self.perspective3D];
![]() 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.
To receive events you need to register id<TTMapViewDelegate> on map
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.
- (void)mapView:(TTMapView *)mapView didPanning:(CLLocationCoordinate2D)coordinate {
- (void)mapView:(nonnull TTMapView *)mapView didDoubleTap:(CLLocationCoordinate2D)coordinate {
- (void)mapView:(nonnull TTMapView *)mapView didLongPress:(CLLocationCoordinate2D)coordinate {
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 these information in your own manner.
![]() Receive callbacks after the map panning |
![]() Receive callbacks after the map panning |
![]() Receive callbacks after the map panning |
Enable and disable gestures
You can disable gestures such as zooming, scrolling and rotating in your application by setting up an integer mask on properties like below:
Disable zooming gesture
self.mapView.disableGesturesMask = TTOptionGesturesDisableZoom;
Disable the rotating gesture
self.mapView.disableGesturesMask = TTOptionGesturesDisableRotate;
Disable the scrolling gesture
self.mapView.disableGesturesMask = TTOptionGesturesDisableScroll;
You can turn off more than one gesture by setting up the mask on properties like below:
// Disable scrolling and zooming gestures
self.mapView.disableGesturesMask = TTOptionGesturesDisableScroll | TTOptionGesturesDisableZoom;
If you want to enable gestures, setup the integer mask on a property like below:
self.mapView.disableGesturesMask = TTOptionGesturesDisableNone;
Map annotations
Annotations
You can place custom images on the map using TTAnnotation. You can do that with a TTAnnotationManager which can be obtained from TTMapView. Use a one of factory method from TTAnnotation to create an annotation, then pass it to manager.
You can display icons using a two of different types:
-
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 TTAnnotationAnchorBottom
-
Draggable markers – allow your users to drag and drop a marker around the map
Mixing icons of focal and decal 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. For performance purposes, it is recommended to use the same tag for same images so they can be reused from cache.
Sample use case: In your app, you want to display a number of annotations, to mark places on the map. Use the code snippet below to display a single annotation at specific coordinates on the map
![]() Focal annotations examples |
![]() Decal annotations examples |
TTAnnotation *annotation = [TTAnnotation annotationWithCoordinate:coordinate];
[self.mapView.annotationManager addAnnotation:annotation];
TTAnnotation *annotation = [TTAnnotation annotationWithCoordinate:coordinate];
annotation.isDraggable = true;
[self.mapView.annotationManager addAnnotation:annotation];
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:
TTAnnotationImage *annotationGif = [TTAnnotationImage initGIFWithName:@"gif_annotation"];
TTAnnotation *annotation = [[TTAnnotation alloc] initWithCoordinate:coordinate annotationImage:annotationGif anchor:TTAnnotationAnchorCenter type:TTAnnotationTypeFocal];
[self.mapView.annotationManager addAnnotation:annotation];
Annotation anchor
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. You can change this behavior by TTAnnotationAnchor enumeration. E.g. if you want to use a crosshair annotation image, you should set the anchor to TTAnnotationAnchorCenter
Annotation selected
You can implement an observable of annotation selected event. You can do that with the global delegate TTAnnotationDelegate for all annotations that has to be registered on TTAnnotationManager as following
Annotation click listener
Maps SDK allows to observe annotation selected event. There is one global delegate TTAnnotationDelegate for all annotations that has to be registered on TTAnnotationManager as followed.
self.mapView.annotationManager.delegate = self;
- (void)annotationManager:(id<TTAnnotationManager>)annotationManager annotationSelected:(TTAnnotation *)annotation {
//handle annotation selected event
}
It is also possible to receive Annotations’s dragging delegate. As an example you can handle delegate:
- (void)annotationManager:(id<TTAnnotationManager>)manager draggingAnnotation:(TTAnnotation *)annotation stateDrag:(TTAnnotationDragState)state {
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.
To display a balloon, attach a callout to a TTAnnotation. The map can display only one annotation at a time
A callout can be triggered in two ways:
-
Automatically, if the annotation is tapped on the map
-
Calling TTAnnotationManager:selectAnnotation
There can be only one selected annotation on the map at a time.
A callout can be closed in the following ways:
-
Automatically, if a user taps on the map
-
Automatically, if a user taps on another annotation
-
Calling TTAnnotationManager:deselectAnnotation if the annotation is attached to the map, it is removed from the map
A callout is an instance of UIView that implements the TTCalloutView protocol. You can use one of the built-in callout views, such as the default TTCalloutViewSimple, or make your own custom balloon.
Default Balloons
The default behavior for an annotation is to display an instance of TTCalloutViewSimple containing the annotation’s coordinates. You can change the following properties:
-
TTAnnotation:canShowCallout determines if the annotation can display a callout. The default value is YES. If it is set to NO, the annotation can still be selected but no callout will appear.
-
TTAnnotation:selectable: determines if the annotation can be selected at all. The default value is YES. If it is set to NO, then no callout will be displayed.
To change the default text of a simple callout, register your delegate on the annotation manager and override the viewForSelectedAnnotation method
self.mapView.annotationManager.delegate = self;
- (UIView<TTCalloutView> *_Nonnull)annotationManager:(id<TTAnnotationManager>)annotationManager viewForSelectedAnnotation:(TTAnnotation *)selectedAnnotation {
return [[TTCalloutViewSimple alloc] initWithText:@"Welcome to TomTom"];
}

Custom Balloons
Although you can use default callouts, SDK also allows you to create fully customizable ones. A callout is nothing more than a Cocoa UIView implementing the TTCalloutView protocol. Callouts can be built by either Interface Builder or programmatically.
This is an example of a custom callout:
self.mapView.annotationManager.delegate = self;
@interface MyCalloutView : UIView <TTCalloutView>
@property (nonatomic, strong) TTAnnotation *annotation;
@end
- (UIView<TTCalloutView> *_Nonnull)annotationManager:(id<TTAnnotationManager>)annotationManager viewForSelectedAnnotation:(TTAnnotation *)selectedAnnotation {
MyCalloutView<TTCalloutView> *callout = [[[NSBundle mainBundle] loadNibNamed:@"MyCalloutView" owner:self options:nil] firstObject];
return callout;
}

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.
A TTMapView supports several shape overlays. These are:
-
TTCircle
-
TTPolygon
-
TTPolyline
Shape overlays are immutable i.e. once they have been created, their shapes cannot be changed (although you may change their visibility and color). 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 be conscientious about performance and how many shape overlays they are using. You should use as few shapes as possible, and hide or dispose of ones that are not being displayed.
Code examples are below:
TTPolygon *polygon = [TTPolygon polygonWithCoordinates:coordinates count:POLYLINE_POINTS opacity:1.0 color:color colorOutline:color];
[self.mapView.annotationManager addOverlay:polygon];
TTPolyline *polyline = [TTPolyline polylineWithCoordinates:coordinates count:(NSUInteger) (POLYLINE_POINTS / 1.5) opacity:(float) 1.0 width:(float) 8.0 color:color];
[self.mapView.annotationManager addOverlay:polyline];
TTCircle *circle = [TTCircle circleWithCenterCoordinate:centroid radius:5000 width:10.0 color:color fill:true colorOutlet:[UIColor redColor]];
[self.mapView.annotationManager addOverlay:circle];
![]() Circle |
![]() Polygon |
![]() Polyline |
Click delegate
You can implement an observable of shape clicked event. You can do that with the global delegate TTAnnotationDelegate for all shapes that has to be registered on TTAnnotationManager as following
Maps SDK allows to observe shape selected event. There is one global delegate TTAnnotationDelegate for all shapes that has to be registered on TTAnnotationManager as followed.
self.mapView.annotationManager.delegate = self;
- (void)annotationManager:(id<TTAnnotationManager>)annotationManager touchUpPolyline:(TTPolyline *)polyline {
}
- (void)annotationManager:(id<TTAnnotationManager>)annotationManager touchUpPolygon:(TTPolygon *)polygon {
}
- (void)annotationManager:(id<TTAnnotationManager>)annotationManager touchUpCircle:(TTCircle *)circle {
Route display
You can display a route on the map and customize its origin and destination icons.
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:
TTMapView *mapView
object was created and configured. Route coordinates are prepared.
You should also add your start and end route icons to assets, you can call it as you want, e.g. “Start” end “End”.
Icons are added to the route when TTMapRoute
object is created, using imageStart
and imageEnd
fabric methods.
"Start" and "End" here are names of icons from assets. And then pass mapRoute
object to addRoute
method of mapView.routeManager
object, e.g.:
TTMapRoute *mapRoute = [TTMapRoute routeWithCoordinatesData:fullRoute imageStart:[UIImage imageNamed:@"ic_map_route_departure"] imageEnd:[UIImage imageNamed:@"ic_map_route_destination"]];
mapRoute.extraData = fullRoute.summary;
[self.mapView.routeManager addRoute:mapRoute];
If you don’t call imageStart
and imageEnd
methods there will be no icons on the route.
You can specify only start icon by calling only imageStart
or only end icon by calling only
imageEnd
. You can use different images from assets for different routes.