Build Different

Android Project Setup for the TomTom Maps SDK

Developer Portal
Apr 14, 2020 • Last edit on Nov 30, 20229 min read
Laptop displaying a TomTom map in dark mode with San Francisco skyline in background

This article will guide you through the process of setting up a basic Android project that integrates the TomTom Maps SDK for Android and TomTom API services.

To illustrate the project setup process, we'll create a basic app that displays a map with the user’s current position marked. The app uses the TomTom Search API to let a user search for a point of interest by entering text and returns useful results even if the search includes spelling errors or inexact addresses. The results will be marked on the map for the user to browse.

This example Android application provides a jumping off point for many potential location-aware apps using TomTom location services.

Getting Started

The TomTom Maps SDK for Android is supported on devices running Android version 4.4 (KitKat) or later. I’m going to use Android Studio as my IDE and Java as the development language. Kotlin is also supported.

To use the TomTom SDK and API services, you need a free developer account. Sign up or log in at This account will be used to manage the API keys for the application, and you’ll need an API key with what you build today.

In the TomTom developer portal, go to your dashboard. When you create a new application entry, you’ll be prompted for a name for the application and for the services the application needs. Enter any name you like. You can select any of the API services that apply to your application, but they must be selected to work with your application.

For this example, select Maps API and Search API, as indicated in the screenshot. The Maps SDK contains classes that will handle making the web calls and rendering the map.


Click “Create App” to create the application entry.

Once you’ve saved the application, the dashboard will show an entry for it, and if you click on the entry, you’ll see the “Consumer API Key.” You’ll need this value to authorize API access in your app. We'll show you how to use the key in your app in a moment.

Android Project Setup

Create a new project in Android Studio. From the “Choose your Project” window, select “Empty Activity” and click “Next,” then enter a name for the project and modify any other project details as needed.

Note that the API version must be no lower than 4.4 (KitKat). Click “Finish” to create the project.

We’ve created the project, but there’s still some configuration to do before diving into the code.

In the left pane in Android Studio, you’ll see two entries for build.gradle, one for Project and the other for Module. Double-click on the build.gradle file for the project, which contains a section for allprojects. Within allprojects you’ll see an entry for repositories, which already contains a couple of entries. We’ll add a third entry so the IDE can retrieve components of the SDK, as shown below in bold:

1allprojects {
2 repositories {
3 google()
4 jcenter()
5 maven {
6 url ''
7 }
8 }

Save and close the file.

Now open the build.gradle file for the module. In the dependencies block, add entries referencing both the Maps and Search SDKs. We only need those two here, but I show other possible entries for other SDK components, commented out.

The number at the end of these strings is the SDK version. I’m using 2.4782. Note that when you’re using more than one component, the SDK versions must be the same for all components. We also need to enable multidex in the implementation to avoid a limitation about including libraries that we’d otherwise encounter.

1//library required to display map
6//library required for search
11//library required for routing
16//library required for traffic
21//library required for geofencing
26//extention library for map custom style and ui support
31//extention library for rx-java2
36//extention library for kotlin support
41//extention library for displaying static map
46//extention library for driving features

Next, we’ll add a section called compileOptions to the android section of the file, to set sourceCompatibility and targetCompatibility for Java Version 1.8. We also need to set the multidex setting to true. The additions are shown in bold:

1android {
2 compileSdkVersion 29
3 buildToolsVersion "29.0.2"
4 defaultConfig {
5 applicationId "com.example.tomtommapstestapp"
6 minSdkVersion 19
7 targetSdkVersion 29
8 multiDexEnabled true
9 versionCode 1
10 versionName "1.0"
11 testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
12 }
13 buildTypes {
14 release {
15 minifyEnabled false
16 proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), ''
17 }
18 }
20 compileOptions {
21 sourceCompatibility JavaVersion.VERSION_1_8
22 targetCompatibility JavaVersion.VERSION_1_8
23 }

With this done, the configuration is complete. You can compile the application. Just take an extra look to make sure you don’t encounter any errors resulting from mistyping.

Now that we’ve completed the setup, let’s write more of the actual code.

Building the UI

The application already has a layout file named activity_main.xml. This is where we’ll define the application UI. Remove the “Hello World” text element and add a <fragment /> element for the map view instead:

2 android:id="@+id/map_fragment"
3 android:name=""
4 android:layout_width="match_parent"
5 android:layout_height="match_parent"
6 tools:layout="@layout/map_view"
7 tomtom:mapsApiKey="maps.api.key"
8 />

Note that we have added the API KEY for map visualization and traffic in the XML for the Fragment layout. You can also declare the API KEY by using the map properties builder as explained in the documentation here:

If you run the application now, you’ll see a map of the earth in which you can zoom and scroll.


The UI will need additional elements for text entry for the search and to show the results as a list. I added an EditText element for the text entry and a ListView to show the list of search results.

In the, we need a few variables to hold references to the map object, the search service, the search results, and the adapter for the list view:

1TomtomMap tomtomMap;
2SearchService tomtomSearch;
3ImmutableList<FuzzySearchResult> lastSearchResult;
4ResultListAdapter adapter;

After the activity’s content view is initialized, in onCreate we use a reference to the map fragment to request a map object. When the map is ready, our callback is called and given a reference to the map. We save the reference since we’ll need it for other calls to the map. Notice a pattern throughout this code: requests being asynchronous and being notified of their completion with results in callbacks.

1MapFragment mapFragment = (MapFragment)getSupportFragmentManager().findFragmentById(;
2Log.d(TAG, "Request map from map fragment");
3mapFragment.getAsyncMap(new OnMapReadyCallback() {
4 @Override
5 public void onMapReady(@NonNull TomtomMap map) {
6 Log.d(TAG, "Map retrieved");
7 tomtomMap = map;
8 tomtomMap.setMyLocationEnabled(true);
9 //Set the map view somewhere near San Jose
10 tomtomMap.centerOn(37, -121, 8);
11 }

We use the SearchServiceManager class to create our SearchService object. As with the map object, we use a callback to get the SearchService object:

1Log.d(TAG, "Requesting search service");
2ServiceConnection serviceConnection = SearchServiceManager.createAndBind(getBaseContext(),
3 new SearchServiceConnectionCallback() {
4 @Override
5 public void onBindSearchService(SearchService searchService) {
6 Log.d(TAG,"Search service retrieved");
7 tomtomSearch = searchService;
8 }
9 });

We want the search results to be based on the part of the map the user is viewing. When the user presses the search button, the coordinates for the map center can be found by calling getCenterOfMap() on the map object.

The center coordinates and the text the user enters in the search box are both added to a FuzzySearchQuery object, and the fuzzy search service will look for relevant results. The query object is passed to the Search object that was created earlier.

Search is performed asynchronously. When it completes, the code receives a callback with the search response.

1EditText searchEditText = findViewById(;
2searchEditText.setOnEditorActionListener((v, actionId, event) -> {
3 LatLng mapCenter = tomtomMap.getCenterOfMap();
5 FuzzySearchQuery searchQuery = FuzzySearchQueryBuilder.create(v.getText().toString())
6 .withPosition(mapCenter)
7 .build();
8, new FuzzySearchResultListener() {
9 @Override
10 public void onSearchResult(FuzzySearchResponse fuzzySearchResponse) {
11 ImmutableList<FuzzySearchResult> results = fuzzySearchResponse.getResults();
12 showSearchResults(results);
13 }
14 @Override
15 public void onSearchError(SearchError searchError) {
16 }
17 });

For a successful search, we’ll display a list of the results on the screen using ListView functionality. We only need to let the adapter for the ListView know that the data to display has been updated. If there is an unsuccessful search we get back an empty result set. If this happens we show a brief notification to let the user know.

We also want markers for the search results to be placed on the map, so we’ll use the Maps SDK’s MarkerBuilder class to create an object that represents a marker on the map. Once the object is built, we can show it on the map by calling addMarker on our map object.

1void showSearchResults(ImmutableList<FuzzySearchResult> resultList)
3 Log.i(TAG, resultList.toString());
4 this.lastSearchResult = resultList;
5 adapter.notifyDataSetChanged();
7 tomtomMap.clear();
8 if(this.lastSearchResult.size() == 0)
9 {
10 Toast.makeText(getBaseContext(), "No locations found",
11 Toast.LENGTH_SHORT).show();
12 return;
13 }
15 for(int i=0;i<lastSearchResult.size();++i)
16 {
17 LatLng geoposition = lastSearchResult.get(i).getPosition();
18 Poi poi = lastSearchResult.get(i).getPoi();
19 MarkerBuilder markerBuilder = new MarkerBuilder(geoposition)
20 .icon(Icon.Factory.fromResources(getBaseContext(),
21 R.drawable.ic_favourites))
22 .markerBalloon(new SimpleMarkerBalloon(poi.getName()))
23 .tag(lastSearchResult.get(i).getAddress())
24 .iconAnchor(MarkerAnchor.Bottom)
25 .decal(true);
26 tomtomMap.addMarker(markerBuilder);
27 }

If someone clicks on an item on the ListView, the map needs to re-center on that item. The centerOn method was used at map initialization to center the map on San Jose, and we can use it again to center the map on the item the user selected:

1searchResultList.setOnItemClickListener(new AdapterView.OnItemClickListener() {
2 @Override
3 public void onItemClick(AdapterView<?> parent, View view, int position, long id) {
4 FuzzySearchResult result =
5 (FuzzySearchResult)searchResultList.getItemAtPosition(position);
6 LatLng geoposition = result.getPosition();
7 tomtomMap.centerOn(geoposition);
8 }

Deploy the application and try searching for a category, such as “airports” or “hospitals.” You should see several results listed, and be able to click on any of them to have the map focus on it. If you see this, you’ve successfully created and configured an application that uses the TomTom Maps SDK and services.


Next Steps

We created a basic Android project that’s configured to use the TomTom Maps SDK and its Search API. Using the SDK, you can build a variety of applications, from ones with customized maps, to ones for tracking assets, for querying traffic information, and for searching an area for points of interest.

Using the same steps, you could create an application that uses TomTom’s other services.

Visit the TomTom Developer Portal and sign up for your free API key to get building.

For more information on the TomTom Maps SDK for Android, visit

Happy mapping!

Get the developer

No marketing fuff. Tech content only.
Thanks for contacting us

We will reach out to you soon.
Blog cards
tomtom tech news