Sorry, you need to enable JavaScript to visit this website.

Documentation

Documentation

Map initialization

The main class with represents a Map is a MapView. MapView is wrapped by MapFragment.
To display map, MapFragment needs to be attached to layout.

The basic steps for adding a map are:

  1. Follow steps described in "Getting started" section.

  2. Add MapFragment to your Activity (either using the code or layout
    file).

  3. Implement the OnMapReadyCallback and use onMapReady method to get
    the TomtomMap object.

  4. Use the TomtomMap object to set the map properties (e.g. map mode,
    tiles types).

OnMapReadyCallback:

import android.support.annotation.NonNull;

/**
 * Callback interface executed when the map is ready to be used.
 * The instance of this interface is set to {@link MapFragment},
 * and the {@link OnMapReadyCallback#onMapReady(TomtomMap)} is triggered
 * when the map is fully initialized and not-null.
 */
public interface OnMapReadyCallback {
    /**
     * Called when the map is ready to be used.
     */
    void onMapReady(@NonNull TomtomMap tomtomMap);
}

 

Adding the MapFragment to XML file:

<fragment
    android:id="@+id/map_fragment"
    android:name="com.tomtom.online.sdk.map.MapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    />

 

Sample implementation of the OnMapReadyCallback:

private final OnMapReadyCallback onMapReadyCallback =
        new OnMapReadyCallback() {
            @Override
            public void onMapReady(TomtomMap map) {
                //Map is ready here
                tomtomMap = map;
                tomtomMap.setMyLocationEnabled(true);
                tomtomMap.collectLogsToFile(SampleApp.LOGCAT_PATH);
            }
        };

MapView initialization.

In some cases, it may be required to use 'MapView' directly, instead of having 'MapFragment'.
In such a case, you need to pass lifecycle events to 'MapView', as shown below:

@Override
/** @inheritDoc */
public void onStart() {
    super.onStart();
    mapView.onStart();
}

@Override
/** @inheritDoc */
public void onResume() {
    super.onResume();
    mapView.onResume();
}

@Override
/** @inheritDoc */
public void onPause() {
    mapView.onPause();
    callbackContainer.removeAllCallbacks();
    super.onPause();
}

@Override
public void onStop() {
    mapView.onStop();
    super.onStop();
}

@Override
public void onDestroy(){
    mapView.onDestroy();
    super.onDestroy();
}

 

When using Maps SDK for Android, it is required that TomTom logo is always visible.
By default, TomTom logo is located at the bottom left corner of the map.
However, you can easily customise its position to meet your app design by define LogoView
style in style.xml in your app.

Sample use case 1: Your app has a bottom panel which covers the TomTom logo and you need to place the logo in top right corner.
To change TomTom logo’s position:

<style name="LogoView" parent="BaseLogoView" >
    <item name="android:layout_gravity">bottom|left</item>
</style>

 

Map layers

Maps SDK offers a number of map tile layers including raster tiles layer,
vector tiles layer, traffic flow and incident overlays. You can choose the type of the
baseline tile type (raster or vector) suitable to your mobile app and decide what kind of
other layers (e.g. traffic layers) your users will benefit from.

Styles and data sources for map layers are defined in JSON file: mapssdk-default-style.json
which is bundled with the SDK.

Following layer sets are included in the style (listed in order from background to foreground):

  1. Background - color and pattern shown in places where there is no other map data.

  2. Raster map - the baseline tile layer in the raster format.

  3. Raster overlay for hybrid maps - the layer showing streets, labels and icons on the transparent background.

  4. Vector map – lines and polygons, the baseline tile layer in the vector format.

  5. Traffic flow - raster or vector overlay for showing traffic flow tiles. Traffic flow speed relative to free-flow, highlighting areas of congestion.

  6. Traffic incidents - raster overlay for showing traffic incident tiles.

  7. Routes - for displaying planned and alternative routes.

  8. Vector map – labels and icons which are rendered on top of most other layers for better
    geopolitical names and street names readability.

  9. GPS accuracy indicator - circle reflecting the GPS inaccuracy area.

  10. Current location marker.

It is possible to change visibility of selected layer sets by calling relevant methods in SDK.
Check out Map examples for ideas how this can be implemented. Please refer to SDK Map Examples
documentation for a description of methods and their parameters description.
There is no mechanism to change neither the styles nor the order of layers by means of calling SDK methods.

Traffic flow tiles

Map SDK offers showing traffic flow overlay for both raster and vector map tiles. Both type of overlays
can be turned on and off separatelly however most sensible would be turning on the same type of overlay
as the map tiles.

Traffic flow can show different information depending on the selected mode. One can select mode
from the following list:

  1. absolute - reflects free-flow speed,

  2. relative (default) - speed relative to free-flow,

  3. relative-delay - relative speed values different from the ones for free-flow,

  4. reduced-sensitivity - displays relative speeds but larger difference from freeflow (depending on FRC) is required for segment to change the color.

It is important to note that raster traffic flow is available on zoom levels 0..20
while vector traffic flow is available on zoom levels 11..20.

Online resources caching

To display the map some external resources are needed by the map renderer:
map style and map tiles.

Map style itself (.json file describing map layers display properties and rendering order)
and assets needed by the style are bundled with SDK library.
Style assets include sprites (sets of icons) displayed on the map and fonts.

When the map viewer is focused at particular spot, map tiles provided by
remote online server are needed to display the map. When a part of the map
is displayed for the first time, needed tiles are downloaded from the server.
Resources downloaded from the server are stored (cached) in an offline
database for further use. The server communicates maximum tile resource lifetime
by means of "Cache-Control" HTTP header. Expiration time
is stored in the offline database together with the tile resource.
If a tile resides in the cache it can be displayed even if internet
connection is not available. When the object in the cache expires, the server is
asked again about the object. If a newer version of the object is available,
it is downloaded and
the cache contents are refreshed. If the old resource is still valid, its lifetime
is prolonged.
Cache size is limited to 50MB of disk space. When the limit is reached,
least recently used tile resources are discarded.

Custom style

You can change the appearance of your map by providing a JSON file containing rendering properties of map elements. Such style file has to:

A basic style is provided as a part of Cumstom Style Resources package.

Styles compliant with Mapbox Style Specification can be edited using style editors like maputnik. Before a style can be edited in maputnik:

  • service key placeholders have to be replaced with actual service keys,

  • sprite and glyph locations have to be replaced by ones that can be reached by maputnik,

  • TomTom-specific tags have to be removed from tile source links or replaced with default values,

  • (optional) visibility of layers can be altered to your preferences.

All these changes, with the exception of layer visibility, have to be reverted before the modified style can be used with the SDK. Custom Style Resources contain a Python script - convertStyle.py - which simplifies this process. Detailed usage instructions can be found in a dedicated section below.

Layer sets

Layers tied to the same data source are treated by the SDK as a layer set. The ID (name) of the data source is used as the name of related layer set. Layer sets listed in Table 1 are required for the SDK to function. If any of these layer sets is absent or does not meet the requirements mentioned below it will be replaced with a default layer set created at runtime.






Table 1. Mandatory layer sets
Map view element Default source name Required layer type Required layer count Source type

Active route polyline

tomtom-active-route

line

2

GeoJSON

Inactive route polyline

tomtom-inactive-route

line

2

GeoJSON

Route start icon

tomtom-start-route

symbol

1

GeoJSON

Route end symbol

tomtom-end-route

symbol

1

GeoJSON

Vehicle icon

tomtom-chevron

symbol

2

GeoJSON

GPS inaccuracy radius

tomtom-gpsradius

circle

2

GeoJSON

Position indicator

tomtom-position

symbol

2

GeoJSON

Two layers for route polyline define the outline and fill styles. Two layers for chevron, GPS radius and position define the styles of two versions of associated objects - normal (active) and dimmed (inactive).

There is a number of layer sets that are important, but not strictly required. They are responsible for providing style and data sources for maps - vector and raster, traffic flow and incidents as well as hybrid overlay. These sets will not be replaced by default ones at runtime.



Table 2. Layer sets important for rendering elements of the map
Map view element Default source name

Vector map

vectorTiles

Raster map

tomtom-raster

Traffic flow

tomtom-flow

Traffic incidents

tomtom-incidents

Hybrid overlay

tomtom-hybrid

User-defined layer set

You can create your own layer sets to replace the default ones. If you use names different than the defaults listed in the tables above, you need to tell the SDK which map view element your custom layer set corresponds to. If names of the layer sets are not delivered, the SDK tries to reach layer sets by using default names.

Source URIs for map layer sets have fixed format - they contain placeholders for API keys and optional parameters. It is not recommended to change them.

Style API

When your custom style is ready, place the JSON file in the /assets/styles/ directory in your Android Studio project or upload it to an online location that your application will be able to access. You can then use your new style in your application.

Even though online style locations are supported, glyphs and sprites have to be stored locally.

Sample use case 1: You want to display a night-themed map with inverted logo colors at night or while in a tunnel.

tomtomMap.getUiSettings().setStyleUrl("asset://styles/night.json");
tomtomMap.getLogoSettings().applyInvertedLogo();

Sample use case 2: You want to switch back to basic style for map and logo.

tomtomMap.getUiSettings().setStyleUrl("asset://styles/mapssdk-default-style.json");
tomtomMap.getLogoSettings().applyDefaultLogo();



image

Basic style

image

Custom night style

Using convertStyle.py

The convertStyle.py script is distributed as a part of the Cumstom Style Resources bundle. It can be executed with one of two commands: 'maputnik' and 'tomtom'. When executed with the 'maputnik' command, it replaces TomTom-specific elements of the base style (-b|--base parameter) with values provided in script’s parameters or in Info.plist or AndroiManifest.xml. when executed with the 'tomtom' command, it reverts changes related to TomTom-specific elements while leaving user’s modification intact.

For the script to work properly, the same base file has to be used for both conversions.
Detailed usage instructions
python2 convertStyle.py <common parameters> <command=maputnik|tomtom> <command-specific parameters>

# All parameters are required unless specified otherwise

common parameters:
  -w WDIR, --wdir WDIR  Working directory. Root of relative paths.
                        [optional, default = "."]
  -S, --silent          Silent mode. No messages will be printed.
  -b BASE, --base BASE  Path to the base for the new style.
  -o OUTPUT, --output OUTPUT
                        Path to the output file.

commands:
    maputnik            Convert a base style so that it can be edited in
                        maputnik.
    tomtom              Convert a style edited in maputnik so that it works
                        with your application using TomTom SDK.

maputnik parameters:
  -k KEYS, --keys KEYS  Path to Info.plist or AndroiManifest.xml.
  -s SPRITES, --sprites SPRITES
                        Online location of sprites.
  -g GLYPHS, --glyphs GLYPHS
                        Online location of glyphs.
  -v {all,none,intact,predefined}, --visibility {all,none,intact,predefined}
                        Change visibility of layers. 'intact' leaves the base
                        style's settings intact, 'predefined' makes vector
                        layers visible and all other layers invisible.
                        [optional, default = "predefined"]

tomtom parameters:
  -e EDITED, --edited EDITED
                        Path to the style edited in maputnik.
Sample workflow
  1. Upload glyphs and sprites to an online location accessible by maputnik.

  2. Use convertStyle.py to create a style that can be edited in maputnik.

    python2 convertStyle.py -b mapssdk-default-style.json -o my_style_prepared_for_maputnik.json maputnik -k path/to/app/AndroiManifest.xml -g http://link.to.glyphs.com -s http://link.to.sprites.com
  3. Upload my_style_prepared_for_maputnik.json to maputnik.

  4. Edit the style in maputnik.

  5. Export the style in maputnik, saving it as my_style_exported_from_maputnik.json.

  6. Use convertStyle.py to prepare the style edited in maputnik to for use with TomTom SDK.

    python2 convertStyle.py -b mapssdk-default-style.json -o my_style_prepared_for_sdk.json tomtom -e my_style_exported_from_maputnik.json