Migrate to the latest version | TomTom SDK for iOS

This tutorial explains the difference between implementing core functionality in the new TomTom SDKs and in the legacy version. The tutorial covers:

Project set up
Displaying a map
Showing user location
Fuzzy search
Adding a marker
Drawing a route

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.

Install Xcode if you don’t already have it.
Create a new project or open an existing one. The application deployment target has to be set to at least 13.0.
Install Cocoapods on your computer.
Install the cocoapods-art tool on your computer.
Add a reference to the cocoapods-art repository:
```
pod repo-art add tomtom-sdk-cocoapods "https://repositories.tomtom.com/artifactory/api/pods/cocoapods"
```
Create a Podfile in the project folder. The pod init command in the project folder can generate a basic podfile.
At the top of the Podfile add the source of the SDK Cocoapods.
```
1plugin 'cocoapods-art', :sources => [
2   'tomtom-sdk-cocoapods'
3]
```
Add the modules that your project requires. This tutorial uses the TomTomSDKMapsDisplay, TomTomSDKSearch, and TomTomSDKOnlineRouting modules.
```
1TOMTOM_SDK_VERSION = '{version}'
2
3target 'YourAppTarget' do
4  use_frameworks!
5  pod 'TomTomSDKMapsDisplay', TOMTOM_SDK_VERSION
6  pod 'TomTomSDKSearch', TOMTOM_SDK_VERSION
7  pod 'TomTomSDKOnlineRouting', TOMTOM_SDK_VERSION
8end
```
Install the dependencies by executing the following command in the project folder.
```
pod install
```
To update the SDK version, run the command
```
pod repo-art update tomtom-sdk-cocoapods
```
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"
3    static let SEARCH_KEY = "YOUR_SEARCH_API_KEY"
4    static let ROUTING_KEY = "YOUR_ROUTING_API_KEY"
5}
```

Displaying a map

Legacy SDK

To display a map in the TomTom Legacy SDK, you have to perform following steps:

Add the TTMapView field to the class.
```
private var mapView: TTMapView!
```
Initialize the TTMapView in a ViewController class, using TTMapConfiguration to provide a valid TomTom API key and other optional properties.
```
1let mapConfig = TTMapConfigurationBuilder.create()
2    .withMapKey(Keys.MAPS_KEY)
3    .build()
4mapView = TTMapView(frame: view.frame, mapConfiguration: mapConfig)
```
Add the initialized TTMapView to the parent view.
```
view.addSubview(mapView)
```
At this point the map will be displayed. Map initialization is an asynchronous process. To perform operations on the map it has to be fully initialized. To be informed when it is ready to be used, set TTMapViewDelegate to the TTMapView and override the onMapReady(TTMapView) method..
```
mapView.delegate = self
```
```
1func onMapReady(_: TTMapView) {
2    showUserLocation()
3}
```

New TomTom SDKs

Map initialization in the new TomTom SDKs is very similar.

Prepare a property to hold the TomTomMap instance.
```
private var tomtomMap: TomTomMap!
```
Set the TomTom API key to MapsDisplayService before using the map.
```
MapsDisplayService.mapsKey = Keys.MAPS_KEY
```
Initialize the TomTomMapView object, which displays a map in the view hierarchy. It can be used to configure the map.
```
1let tomtomMapView = TomTomMapView(frame: view.frame)
2let amsterdam = CLLocationCoordinate2DMake(52.36218, 4.88891)
3tomtomMapView.cameraOptions = CameraOptions(position: amsterdam)
```
Add the initialized TomTomMapView to the parent view.
```
view.addSubview(tomtomMapView)
```
At this point, the map will be displayed. To interact with the map it has to be fully initialized. Use TomTomMapViewDelegate to observe when the map is ready to be used. It gives the TomTomMap instance of the initialized map, which is used to perform operations such as adding a marker or drawing a route.
```
tomtomMapView.delegate = self
```
```
1func tomTomMapView(_ mapView: TomTomMapView, onMapReady _: TomTomMap) {
2    showUserLocation(mapView: mapView)
3}
```

Globe view

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.

Legacy SDK

To show user location in the Legacy SDK you need to set the TTMapView.isShowsUserLocation property.

mapView.isShowsUserLocation = true

If you then want to show the center button, you have to add the TTControlView to the TTMapView and initialize a default center button.

1let controlView = TTControlView(frame: mapView.frame)
2controlView.mapView = mapView
3mapView.addSubview(controlView)
4controlView.initDefaultCenterButton()

New TomTom SDKs

To show user location on the map, you need to 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

Fuzzy search

This part of the tutorial describes a simple fuzzy search implementation. For more detailed information about searches see the Search module documentation. A good place to start is Search quickstart guide.

With both SDKs, you need to use use an UITextField to get the search term from the user and the UITableView to display search results. However, their implementation is out of the scope of this tutorial, which only covers functionality within the SDK.

Legacy SDK

The entry point to the Search services is through the TTSearch interface. Create the property TTSearch and initialize it with the valid TomTom API key.
```
private var searchService: TTSearch!
```
```
searchService = TTSearch(key: Keys.SEARCH_KEY)
```
The fuzzy search request is built using TTSearchQuery. To initialize it use its builder - TTSearchQueryBuilder.
```
1let searchQuery = TTSearchQueryBuilder.create(withTerm: query)
2    .withMinFuzzyLevel(2)
3    .withTypeAhead(true)
4    .build()
```
Use the prepared TTSearchQuery to perform the request. The results are returned using a closure that was provided to the request method.
```
1searchService.search(with: searchQuery) { response, error in
2    if let error = error {
3        self.handleAPIError(error.localizedDescription)
4    } else if let results = response?.results {
5        self.handleSearchResults(results)
6    }
7}
```

Current TomTom SDKs

In the new TomTom SDKs, the entry point to the search service is the TomTomSearchService class. Prepare a property to hold its instance.
```
private var searchService: TomTomOnlineSearchService!
```
Before accessing the TomTom search service you have to set the TomTom API key. Then initialize the TomTomSearchService object.
```
SearchOnlineService.searchKey = Keys.SEARCH_KEY
searchService = TomTomOnlineSearchService()
```
Fuzzy search requires a FuzzySearchQuery. It provides the request with the necessary parameters. Initialize it using its builder - FuzzySearchQueryBuilder.
```
1let fuzzySearchQuery = FuzzySearchQueryBuilder(query: query)
2    .with(minFuzzyLevel: 2)
3    .with(typeahead: true)
4    .build()
```
Use the prepared FuzzySearchQuery to perform the fuzzy search request. The results are returned using the closure that was provided to the request method.
```
1searchService.fuzzySearch(query: fuzzySearchQuery) { searchResponse, error in
2    if let error = error {
3        self.handleAPIError(error.localizedDescription)
4    } else if let searchResponse = searchResponse {
5        self.handleSearchResults(searchResponse.results)
6    }
7}
```

Adding a marker

This section explains how to add a marker at a selected location using each of the SDKs.

Legacy SDK

To add a marker to the map, first create a TTAnnotation object to specify its properties. Then add the TTAnnotation to the TTMapView via TTAnnotationManager.

1func displayMarker(at position: CLLocationCoordinate2D) {
2    let annotation = TTAnnotation(coordinate: position)
3    mapView.annotationManager.add(annotation)
4}

New TomTom SDKs

Adding a marker works in a similar way in the new TomTom SDKs. Configure the marker using the MarkerOptions class. The initialized MarkerOptions object has to be added to the TomTomMap. Note that if adding a marker fails, an exception will be thrown. Read more about markers in the Markers guide.

1func displayMarker(at position: CLLocationCoordinate2D) {
2    let markerOptions = MarkerOptions(coordinate: position, pinImage: UIImage(named: "marker_pin_image")!)
3    let marker = try? tomtomMap.addMarker(options: markerOptions)
4}

center

Drawing a route

The last part of this tutorial explains how to plan a route between two locations and draw it on the map.

Legacy SDK

The entry point for routing service in the Legacy SDK is the TTRoute interface. Initialize it with the calid TomTom API key.
```
private var routeService: TTRoute!
```
```
routeService = TTRoute(key: Keys.ROUTING_KEY)
```
Build and perform the request. Specify the route parameters using TTRouteQuery. Use TTRouteQueryBuilder to apply the chosen parameters. Then provide the configured specification to the routing call. Possible routes are returned inside the closure provided to the request method.
```
1let routeQuery = TTRouteQueryBuilder.create(withDest: destinationLocation, andOrig: departureLocation)
2    .withRouteType(.fastest)
3    .withTravelMode(.car)
4    .build()
5routeService.plan(with: routeQuery) { result, error in
6    if let error = error {
7        self.handleAPIError(error.localizedDescription)
8    } else if let result = result {
9        self.handleRouteResults(result)
10    }
11}
```
Draw the calculated route on the map. You can define the appearance of the route using the TTMapRouteStyleBuilder class. The TTMapRoute is a representation of the path to add to the map. You must provide it with a list of coordinates. You can also specify the design, but this is optional. All the routes will then be shown in the route overview.
```
1guard let route = result.routes.first else { return }
2let routeStyle = TTMapRouteStyleBuilder()
3    .withFill(.red)
4    .build()
5let mapRoute = TTMapRoute(coordinatesData: route, with: routeStyle, imageStart: nil, imageEnd: nil)
6mapView.routeManager.add(mapRoute)
7mapView.routeManager.showAllRoutesOverview()
```

New TomTom SDKs

In the new TomTom SDKs the entry point to the routing service is the TomTomRoutingService class. Prepare a property to hold its instance.
```
private var routingService: TomTomRoutingService!
```
Before accessing the TomTom Routing service you have to set the TomTom API key. Then initialize the TomTomRoutingService object.
```
RoutingOnlineService.routingKey = Keys.ROUTING_KEY
routingService = TomTomRoutingService()
```
Build and perform the route request. The request requires departure and destination coordinates. You can also provide additional parameters. Add them all using the RoutingOptionsBuilder class, which is used to build the RoutingOptions object. RoutingOptions is then used to perform the routing request. As with the legacy SDK, routing results are returned in the provided closure. Read more about routing in the Planning a route guide.
```
1let routingOptions = RoutingOptionsBuilder(origin: departure, destination: destination)
2    .with(routeType: .fast)
3    .with(travelMode: .car)
4    .build()
5routingService.planRoute(options: routingOptions, completion: { result in
6    switch result {
7    case let .success(routingResponse):
8        self.handleRoutingResponse(routingResponse)
9    case let .failure(error):
10        self.handleAPIError(error.localizedDescription)
11    }
12})
```
Use the result of the call to draw a route on the map. To do this, get the route that you want to draw from the RoutingResponse. Use the Route to build a RouteOptions object. This is also the place to specify visual properties for the route. Then add the RouteOptions to the TomTomMap. Note that if adding a route to the map failed an exception will be thrown. When you display all of the routes, you can also specify the padding from the edges of the map. Read more about adding a route to the map in the Routes guide.
```
1guard let route = routingResponse.routes?.first else { return }
2var routeOptions = RouteOptions(coordinates: route.geometry)
3routeOptions.color = .red
4_ = try? tomtomMap.addRoute(routeOptions)
5tomtomMap.zoomToRoutes(padding: 50)
```

Adding a route