Developer
THIS SDK ISDEPRECATED.

We rolled out a new and better SDK for you.

CHECK IT OUT

Migrate from Google Maps to TomTom

For Web For iOS

Overview

This tutorial covers some very basic use cases to help you switch your Android app from Google's APIs to TomTom's as quickly as possible. It starts with basic environment setup, then dives into the code. At the very bottom of the page is a recommended reading list to allow you to build on the foundations provided by this tutorial.

This tutorial covers:

Prerequisites

Before you start writing code, prepare your environment:

  1. Install Android Studio. During installation, make sure that the component "Android Virtual Device" is selected.
  2. If possible, start a new project (minimum SDK API 19 – Android 4.4 “KitKat”) with an Empty activity. You can use your own project as long as it meets the minimum Android SDK API level requirement
  3. Update the Source Compatibility and Target Compatibility to 1.8 in the Project Structure dialog ( click File > Project Structure).
  4. Add the TomTom repository to your project's gradle.build file: 
    1allprojects {
    2    repositories {
    3        google()
    4        jcenter()
    5        maven {
    6            url "https://repositories.tomtom.com/artifactory/maps-sdk-legacy-android"
    7        }
    8    }
    9}
  5. If you don't have an API key visit a How to get a TomTom API key site and create one.
  6. Create a build config fields with the API keys, which will be used later in the application: 
    1android {
    2    compileSdkVersion 29
    3    defaultConfig {
    4        buildConfigField("String", "ROUTING_API_KEY", "\YOUR_KEY\")
    5    (...)

Initializing a map

Compare how the map is initialized using the Google and TomTom tools:

Google

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

  1. Add dependencies to your module's gradle.build file: 
    implementation 'com.google.android.gms:play-services-maps:17.0.0'
  2. Add a map fragment to the main activity: 
    1<fragment
    2    android:id="@+id/mapFragment"
    3    android:name="com.google.android.gms.maps.SupportMapFragment"
    4    android:layout_width="match_parent"
    5    android:layout_height="match_parent"/>
  3. Add a Google Android API key inside the application section of the manifest.xml file: 
    <meta-data android:name="com.google.android.geo.API_KEY" android:value="YOUR_KEY_GOES_HERE"/>

TomTom

To do the same thing in the TomTom Maps SDK for Android:

  1. Add dependencies to your module's gradle.build file: 
    implementation 'com.tomtom.online:sdk-maps:2.4725'
  2. Add a map fragment to the main activity layout and API keys for Maps and Traffic services: 
    1(...)
    2xmlns:tomtom="http://schemas.android.com/apk/res-auto"
    3tools:context=".MainActivity">
    4(...)
    5<fragment
    6    android:id="@+id/mapFragment"
    7    android:name="com.tomtom.online.sdk.map.MapFragment"
    8    tomtom:mapStyleSource="STYLE_MERGER"
    9    android:layout_width="match_parent"
    10    android:layout_height="match_parent"
    11    tomtom:mapsApiKey="YOUR_API_KEY"
    12    tomtom:trafficApiKey="YOUR_API_KEY"

Displaying a marker

The next step is to allow your user to interact with the map (for instance, displaying or moving a marker).

Google

  1. Implement the OnMapReadyCallback interface in your MainActivity class and override the onMapReady method.: 
    1@Override
    2    public void onMapReady(GoogleMap googleMap) {
    3    this.map = googleMap
    4    LatLng amsterdam = new LatLng(52.37, 4.90);
    5    googleMap.addMarker(new MarkerOptions().position(amsterdam).title("Amsterdam"));
    6    googleMap.animateCamera(CameraUpdateFactory.newLatLngZoom(amsterdam, 8));
    7}
  2. Inside the MainActivity onCreate method, get the appropriate map fragment instance and set a callback object on MainActivity so that the onMapReady method is called: 
    1SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
    2    .findFragmentById(R.id.mapFragment);
    3mapFragment.getMapAsync(this);

TomTom

  • Define field map in MainActivity:

    private TomtomMap map;
    private lateinit var map: TomtomMap

  • As with Google, you need to implement an OnMapReadyCallback interface in your MainActivity class and override the onMapReady method:

    1@Override
    2public void onMapReady(@NonNull TomtomMap tomtomMap) {
    3    this.map = tomtomMap;
    4    LatLng amsterdam = new LatLng(52.37, 4.90);
    5    SimpleMarkerBalloon balloon = new SimpleMarkerBalloon("Amsterdam");
    6    tomtomMap.addMarker(new MarkerBuilder(amsterdam).markerBalloon(balloon));
    7    tomtomMap.centerOn(CameraPosition.builder().focusPosition(amsterdam).zoom(7.0).build());
    8}
    1override fun onMapReady(tomtomMap: TomtomMap) {
    2    map = tomtomMap
    3    val amsterdam = LatLng(52.37, 4.90)
    4    val balloon = SimpleMarkerBalloon("Amsterdam")
    5    tomtomMap.addMarker(MarkerBuilder(amsterdam).markerBalloon(balloon))
    6    tomtomMap.centerOn(CameraPosition.builder().focusPosition(amsterdam).zoom(7.0).build())
    7}

Any interaction with the TomTom Map object needs to be performed after the onMapReady callback has been called, when the map is fully initialized.

  • Inside the MainActivity onCreate method, get the map fragment instance and set a callback object on MainActivity so that the onMapReady method is called:

    1MapFragment mapFragment = (MapFragment) getSupportFragmentManager().findFragmentById(R.id.mapFragment);
    2if(mapFragment != null) {
    3    mapFragment.getAsyncMap(this);
    4}
    (mapFragment as MapFragment).getAsyncMap(this)

Displaying traffic

Create two simple buttons to work with traffic on the map. One enables the traffic layer, and the other disables it.

Google

In Google there is only one method responsible for traffic visualization:

googleMap.setTrafficEnabled(true);

The method displays only traffic flow tiles.

TomTom

TomTom provides two services that offer traffic information:

  • 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 much slower than free flow, meaning that there are traffic jams.
  • Traffic incidents indicates specific traffic problems such as closed roads, rain, ice on the road, or accidents.

Create the buttons to handle traffic visualization and call the turnOnTrafficIncidents and turnOnTrafficFlowTiles methods on the map TrafficSettings object, choosing whether to display traffic flow tiles, traffic incident tiles, both, or none.

1@Override
2public void onCreate(Bundle savedInstanceState) {
3    btnTrafficOn = findViewById(R.id.btnTrafficOn);
4    btnTrafficOff = findViewById(R.id.btnTrafficOff);
5

6(...)
7@Override
8public void onMapReady(@NonNull TomtomMap tomtomMap) {
9    this.map = tomtomMap;
10    btnTrafficOn.setOnClickListener(v -> {
11        map.getTrafficSettings().turnOnTrafficIncidents();
12        map.getTrafficSettings().turnOnTrafficFlowTiles();
13    });
14

15    btnTrafficOff.setOnClickListener(v -> map.getTrafficSettings().turnOffTraffic());
1override fun onMapReady(tomtomMap: TomtomMap) {
2    map = tomtomMap
3    btnTrafficOn.setOnClickListener {
4        map.trafficSettings.turnOnTrafficIncidents()
5        map.trafficSettings.turnOnTrafficFlowTiles()
6        }
7    btnTrafficOff.setOnClickListener { map.trafficSettings.turnOffTraffic() }

Displaying a route/directions

The next step is to add a third button that shows a route.

Google

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

TomTom

TomTom Routing API allows the app to calculate a route between two points, add waypoints, and draw the route on the map with one call. To enable Routing API inside your application:

  1. Add a dependency to the module's gradle.build file:

    implementation 'com.tomtom.online:sdk-routing:2.4725'

  2. Now add a button for displaying the route to the main activity layout XML file:

    1<Button
    2android:id="@+id/btnRouteShow"
    3android:layout_width="wrap_content"
    4android:layout_height="wrap_content"
    5android:layout_marginBottom="8dp"
    6android:layout_marginEnd="8dp"
    7android:layout_marginStart="8dp"
    8android:text="@string/route_show"
    9app:layout_constraintBottom_toBottomOf="parent"
    10app:layout_constraintEnd_toEndOf="parent" />

  3. Finally, add a proper handler for our new button: Planning a route requires at least two location points (e.g.: Amsterdam and Hague). Create an instance of the RoutingApi object by calling OnlineRoutingApi.create method and pass a routing API key inside it. Then construct a route descriptor object where you can choose a route type (like fastest or shortest). Next, create a route calculation descriptor object which allows you to set additional routing parameters. Finally a route specification object can be created with the origin and destination points. When a route specification is prepared, it can be passed into a planRoute method in the routing api object.

  4. The planRoute takes a RouteCallback where it returns a route plan object. You can get FullRoute objects (which contains a route coordinates) from the routePlan.getRoutes() method, create a new RouteBuilder object from each of them, and add them to your map.

    1@Override
    2public void onCreate(Bundle savedInstanceState) {
    3    super.onCreate(savedInstanceState);
    4    btnRouteShow = findViewById(R.id.btnRouteShow);
    5

    6(...)
    7@Override
    8public void onMapReady(@NonNull TomtomMap tomtomMap) {
    9    btnRouteShow.setOnClickListener(showRouteListener);
    10(...)
    11private View.OnClickListener showRouteListener = new View.OnClickListener() {
    12    @Override
    13    public void onClick(View v) {
    14        LatLng amsterdam = new LatLng(52.37, 4.90);
    15        LatLng hague = new LatLng(52.07, 4.30);
    16        RoutingApi routingApi = OnlineRoutingApi.create(getApplicationContext(), BuildConfig.ROUTING_API_KEY);
    17

    18        RouteDescriptor routeDescriptor = new RouteDescriptor.Builder()
    19                .routeType(com.tomtom.online.sdk.routing.route.description.RouteType.FASTEST)
    20                .build();
    21        RouteCalculationDescriptor routeCalculationDescriptor = new RouteCalculationDescriptor.Builder()
    22                .routeDescription(routeDescriptor)
    23                .build();
    24        RouteSpecification routeSpecification = new RouteSpecification.Builder(amsterdam, hague)
    25                .routeCalculationDescriptor(routeCalculationDescriptor)
    26                .build();
    27

    28        routingApi.planRoute(routeSpecification, new RouteCallback() {
    29            @Override
    30            public void onSuccess(@NotNull RoutePlan routePlan) {
    31                for (FullRoute fullRoute : routePlan.getRoutes()) {
    32                    RouteBuilder routeBuilder = new RouteBuilder(
    33                            fullRoute.getCoordinates());
    34                    map.addRoute(routeBuilder);
    35                }
    36            }
    37

    38            @Override
    39            public void onError(@NotNull RoutingException e) {
    40                Toast.makeText(MainActivity.this, e.getLocalizedMessage(), Toast.LENGTH_LONG).show();
    41            }
    42        });
    43    }
    44};
    1override fun onMapReady(tomtomMap: TomtomMap) {
    2    map = tomtomMap
    3    btnRouteShow.setOnClickListener(showRouteListener)
    4(...)
    5private val showRouteListener = View.OnClickListener {
    6    val amsterdam = LatLng(52.37, 4.90)
    7    val hague = LatLng(52.07, 4.30)
    8    val routingApi = OnlineRoutingApi.create(applicationContext, BuildConfig.ROUTING_API_KEY)
    9    val routeDescriptor = RouteDescriptor.Builder()
    10            .routeType(com.tomtom.online.sdk.routing.route.description.RouteType.FASTEST)
    11            .build()
    12    val routeCalculationDescriptor = RouteCalculationDescriptor.Builder()
    13            .routeDescription(routeDescriptor).build()
    14    val routeSpecification = RouteSpecification.Builder(amsterdam, hague)
    15            .routeCalculationDescriptor(routeCalculationDescriptor)
    16            .build()
    17    routingApi.planRoute(routeSpecification, object : RouteCallback {
    18        override fun onSuccess(routePlan: RoutePlan) {
    19            for (fullRoute in routePlan.routes) {
    20                val routeBuilder = RouteBuilder(
    21                        fullRoute.getCoordinates())
    22                map.addRoute(routeBuilder)
    23            }
    24        }
    25

    26        override fun onError(error: RoutingException) {
    27            Toast.makeText(this@MainActivity, error.localizedMessage, Toast.LENGTH_LONG).show()
    28        }
    29    })
    30}

You can find full source code here: on github.

Summary

Using this tutorial, you should have converted an Android application from using Google Maps APIs to TomTom's. Now you have a map with fresh and accurate traffic information, on which you can easily plan many kinds of route. Great!