Migrate from Google

VERSION 0.2.1455


This tutorial covers some fundamental use cases to help you switch your iOS app from Google’s SDK to TomTom’s as quickly as possible. It starts with the basic environment setup, then dives into the code.

Project set up

To use Maps SDK in your application you need to obtain a TomTom API key by following these instructions. Remember to keep your API key secure.

  1. Install Xcode if you don’t already have it.

  2. Create a new project or open an existing one. The application deployment target has to be set to at least 13.0.

  3. Install Cocoapods on your computer.

  4. Install the cocoapods-art tool on your computer.

  5. Add a reference to the cocoapods-art repository:

    pod repo-art add tomtom-sdk-cocoapods "https://repositories.tomtom.com/artifactory/api/pods/cocoapods"
  6. Create a Podfile in the project folder. The pod init command in the project folder can generate a basic podfile.

  7. At the top of the Podfile add the source of the SDK Cocoapods.

    1plugin 'cocoapods-art', :sources => [
    2 'tomtom-sdk-cocoapods'
  8. Add the modules that your project requires. This tutorial uses the TomTomSDKMapsDisplay and TomTomSDKOnlineRouting modules.

    1TOMTOM_SDK_VERSION = '{version}'
    3target 'YourAppTarget' do
    4 use_frameworks!
    5 pod 'TomTomSDKMapsDisplay', TOMTOM_SDK_VERSION
    6 pod 'TomTomSDKOnlineRouting', TOMTOM_SDK_VERSION
  9. Install the dependencies by executing the following command in the project folder.

    pod install
  10. To update the SDK version, run the command

    pod repo-art update tomtom-sdk-cocoapods
  11. Create a class with the TomTom API keys. These will be used later in the application.

    1private enum Keys {
    2 static let MAPS_KEY = "YOUR_MAPS_API_KEY"

Displaying a map


To display the map using the Google Maps SDK for iOS, you need to perform a few steps:

  1. Set the Google API before performing any request.
  2. Initialize the GMSMapView with the chosen specification.
    mapView = GMSMapView(frame: view.frame)
  3. Add the initialized GMSMapView to the parent view.

TomTom SDK

To do the same thing in the TomTom SDK for iOS:

  1. Set the valid TomTom API key.
    MapsDisplayService.mapsKey = Keys.MAPS_KEY
  2. Initialize the TomTomMapView. It is used to display a map in the view hierarchy.
    let mapView = TomTomMapView(frame: view.frame)
  3. Add the initialized TomTomMapView to the parent view.
  4. Most actions performed on the map are made using the TomTomMap object. It can be accessed only when the map is fully initialized. Read more about it in the Adding a map guide.
    1mapView.getMapAsync { tomtomMap in
    2 self.tomtomMap = tomtomMap


Displaying a marker

The next step is to allow your user to interact with the map. For instance, displaying a marker at the location where the user does a long click.


  1. In the Google SDK you need to set GMSMapViewDelegate to the GMSMapView.delegate property to observe gesture events on the map.
    mapView.delegate = self
  2. In our case, the long press action is observed and the following method is triggered.
    1func mapView(_: GMSMapView, didLongPressAt coordinate: CLLocationCoordinate2D) {
    2 displayMarker(at: coordinate)
  3. To display a marker at the chosen coordinates create the GMSMarker object. It defines the marker configuration. To add the marker to the map, assign the GMSMapView to the marker’s property.
    1private func displayMarker(at coordinate: CLLocationCoordinate2D) {
    2 let marker = GMSMarker(position: coordinate)
    3 marker.map = mapView

TomTom SDK

  1. To observe gesture events performed on the map, set the TomTomMapDelegate to the TomTomMap object.
    tomtomMap.delegate = self
  2. In this example the long click action is observed. To do it you need to override the following method of the TomTomMapDelegate. Read more about Events and gestures.
    1func tomTomMap(_: TomTomMap, didLongPressOn coordinate: CLLocationCoordinate2D) {
    2 displayMarker(at: coordinate)
  3. To display a marker at the chosen coordinates you have to create MarkerOptions. It is used to configure the appearance of the marker. Then add the MarkerOptions object to the TomTomMap. If this operation fails, the exception is thrown. Read more about working with markers in the Markers guide.
    1private func displayMarker(at coordinate: CLLocationCoordinate2D) {
    2 let markerOptions = MarkerOptions(coordinate: coordinate, pinImage: UIImage(named: "marker_pin_image")!)
    3 _ = try? tomtomMap.addMarker(options: markerOptions)


Displaying traffic


Google has only one method for traffic visualization. That method can only display traffic flow tiles. To show the traffic layer:

mapView.isTrafficEnabled = true

To hide the traffic layer:

mapView.isTrafficEnabled = false

TomTom SDK

The TomTom SDK provides two kinds of traffic information, traffic flow and traffic incidents.

  • Traffic flow shows the difference between current and free flow speed. Green indicates that the speeds are the same, meaning there are no traffic jams. Red indicates that traffic is slower than free flow, meaning that there are traffic jams.
  • Traffic incidents shows specific traffic problems such as closed roads, rain, ice on the road, or accidents.


Displaying a route/directions


Displaying a route in the Google Maps SDK for iOS is not straightforward. It boils down to interacting with the Directions API, gathering a list of route positions, then drawing a polyline from that list directly onto the map. This is too verbose and complex to show in this tutorial.

TomTom SDK

The TomTom Routing API allows the app to easily calculate a route between two points, add waypoints, and specify other route properties. The requested Route can then be simply drawn on the map. Detailed information about routing in the TomTom SDK can be found in the Routing module documentation. A good place to start is the Quickstart guide.

  1. Before using the TomTom Routing service you need to provide a valid TomTom API key.
    RoutingOnlineService.routingKey = Keys.ROUTING_KEY
  2. Initialize TomTomRoutingService. It is the entry point for the routing service.
    routingService = TomTomRoutingService()
  3. Build your routing request using RoutingOptionsBuilder. You can configure the request to fit your requirements. Read more about routing properties in the TomTom Routing API documentation.
    1let amsterdamCoordinate = CLLocationCoordinate2DMake(52.3764527, 4.9062047)
    2let berlinCoordinate = CLLocationCoordinate2DMake(52.5069751, 13.3631919)
    3let hagueCoordinate = CLLocationCoordinate2DMake(52.078663, 4.288788)
    4let routingOptions = RoutingOptionsBuilder(origin: amsterdamCoordinate, destination: berlinCoordinate)
    5 .with(waypointCoordinates: [hagueCoordinate])
    6 .with(routeType: .efficient)
    7 .with(travelMode: .bus)
    8 .build()
  4. Perform a request using the previously-built RoutingOptions as a parameter. A result is returned via the provided closure.
    1routingService.planRoute(options: routingOptions) { result in
    2 switch result {
    3 case let .success(response):
    4 if let route = response.routes?.first {
    5 self.drawRoute(route)
    6 }
    7 case .failure:
    8 // failure case
    9 break
    10 }
  5. Finally, use the Route calculated by the routing service to draw it on the map. The RouteOptions class can be used to customize the appearance of the route. Read more about adding a route to the map here.
    1private func drawRoute(_ route: TomTomSDKRoute.Route) {
    2 let routeOptions = RouteOptions(coordinates: route.geometry)
    3 _ = try? tomtomMap.addRoute(routeOptions)

Showing user location

To access user location you have to configure the following purpose strings in the Xcode build setting or in Info.plist: NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, or NSLocationAlwaysUsageDescription. The correct key must be included or authorization requests will immediately fail and the map will not be able to get the user location.


To show user location on the map in Google Maps SDK for iOS you have to enable location on GMSMapView.

mapView.isMyLocationEnabled = true

To show the location button set the following property.

mapView.settings.myLocationButton = true

TomTom SDK

To show the user location on the map, change the TomTomMap.locationIndicatorType to either userLocation or .navigationChevron. By default, the CLLocationManager is used as the source of location updates. However, you can also provide your own source. Read more about user location in the Showing the user’s location guide.

tomtomMap.locationIndicatorType = .userLocation

By default the center button is hidden, so to show it you need to change its visibility using TomTomMapView.

mapView.currentLocationButtonVisibilityPolicy = .visible