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

Migration guide

Migration guide

Use style from Style Merger

Starting with version 2.4.537, we are switching bundled-in styles and sprite, to using TomTom hosted styles and sprites. More information about the new approach is available in Map Initialization. Thanks to integration with Merged Style method provided by Map Display API you can generate and use one style for map and traffic display. The main benefits of TomTom hosted display resources are as following:

  • It makes application download size MB smaller in comparison to using bundled-in resources.

  • It allows you to get the newest look and feel of the map and traffic.

Maps SDK will work with the bundled-in style until June 2021 but we recommend to switch to using hosted assets sooner.

Until version 2.4.537, the style in the SDK has been included in the map package and consisted of layers from: Vector tiles, Traffic Flow, Traffic Incidents and Raster tiles. The approach of using a single style that contains multiple Traffic Flow tiles types was deprecated. After the deprecation period is over, it will not be possible to switch between Traffic Flow tiles types without reloading the style. Until deprecation is over in June 2021, the default map style which contains both raster and vector tiles is using SDK_BUNDLED, as a default value for the enum MapStyleSource.

Deprecated methods include UiSettings with all of its methods and TrafficSettings:

  • UiSettings:
    setMapLayersType(MapLayersType mapLayersType)
    getMapLayersType()
    setMapTilesType(MapTilesType mapTilesType)
    getMapTilesType()

  • TrafficSettings:
    turnOnVectorTrafficFlowTiles()
    turnOnRasterTrafficFlowTiles()
    turnOnVectorTrafficFlowTiles(TrafficFlowType.VectorTrafficFlowType trafficFlowTilesStyle)
    turnOnRasterTrafficFlowTiles(TrafficFlowType.RasterTrafficFlowType trafficFlowTilesStyle)
    turnOnVectorTrafficIncidents()
    turnOnRasterTrafficIncidents()
    isTrafficVectorFlowEnabled()
    isTrafficRasterFlowEnabled()
    getTrafficVectorFlowStyle()
    getTrafficRasterFlowStyle()

We encourage you to switch to the Merged Style method. It offers the following advantages to a proposed solution:

  • Each style has its own sprite sheet and is now fully independent.

  • A user can mix and match all sources of tiles in any manner as styles and sprite sheets are now merged on the server side. The selection of a particular style combination is done by providing custom Style Merger URL parameters.

  • It is easier to style traffic in the Map Styler as it can be easily loaded together with a map by using a merged version of the styles. However, the style from the Style Merger can only be used as a base for a custom style. Using this edited style and the Style Merger at the same time is not possible.

  • SDKs do not merge styles in runtime (e.g., it is required to have some hard-coded values to put traffic below the label layers in a map).

In case you have your own custom style that is not compliant with the TomTom sourcing names convention, you will use LayerSetConfiguration, which provides custom IDs for sources in the style.
LayerSetConfiguration should only be used with the MapStyleSource set to STYLE_MERGER.

Map initialization with the Style Merger endpoint using Merged Style functionality is described in section "Map properties". To the new functionality you need to implement a builder as described in the following example:
MapStyleSource is used to determine if the default and loaded style should support Style Merger. Setting it to STYLE_MERGER results in the default style only supporting vector tiles:

MapProperties.Builder()
    .mapStyleSource(MapStyleSource.STYLE_MERGER)
    .build()

When MapStyleSource.STYLE_MERGER is selected, the method related to directly switching between raster and vector tiles will throw an exception. MapProperties can be also be declared in the XML by adding the following line:

tomtom:mapStyleSource="STYLE_MERGER"

to the snippet:

<fragment
   android:id="@+id/map_fragment"
   android:name="com.tomtom.online.sdk.map.MapFragment"
   android:layout_width="match_parent"
   android:layout_height="match_parent"
   tomtom:mapBackgroundColor="@color/solid_black"
   tomtom:styleUrl="http://your-server:port/style/example-merged.json"
   tomtom:mapStyleSource="STYLE_MERGER" />

In case you have your own custom style that is not compliant with the TomTom sourcing names convention, you will use LayerSetConfiguration which provides custom IDs for sources in the style.

LayerSetConfiguration should be used only with the MapStyleSource set to STYLE_MERGER.

val layerSetConfiguration = LayerSetConfiguration.Builder()
    .mapTilesConfiguration(MAP_TILES_SOURCE_ID)
    .trafficIncidentsTilesConfiguration(TRAFFIC_INCIDENTS_SOURCE_ID)
    .trafficFlowTilesConfiguration(TRAFFIC_FLOW_SOURCE_ID)
    .build()
MapProperties.Builder()
    .mapStyleSource(MapStyleSource.STYLE_MERGER)
    .layerSetConfiguration(layerSetConfiguration)
    .build()

or

_

tomtomMap.getUiSettings().setStyleUrl(
        "asset://styles/custom-traffic.json",
        new LayerSetConfiguration.Builder()
        .mapTilesConfiguration(MAP_TILES_SOURCE_ID)
        .trafficFlowTilesConfiguration(TRAFFIC_FLOW_SOURCE_ID)
        .trafficIncidentsTilesConfiguration(TRAFFIC_INCIDENTS_SOURCE_ID)
        .build()
);
tomtomMap.uiSettings.setStyleUrl(
    "asset://styles/custom-traffic.json",
    LayerSetConfiguration.Builder()
        .mapTilesConfiguration(MAP_TILES_SOURCE_ID)
        .trafficFlowTilesConfiguration(TRAFFIC_FLOW_SOURCE_ID)
        .trafficIncidentsTilesConfiguration(TRAFFIC_INCIDENTS_SOURCE_ID)
        .build()
)

Traffic flow tiles

IMPORTANT: The Maps SDK should be initialized with the style from Style Merger which only supports vector tiles and one type of the flow overlay. The approach of using a single style that contains multiple Traffic Flow tiles types was deprecated. After the deprecation period is over, it will not be possible to switch between Traffic Flow tiles types without reloading the style.

The Maps Display API provides support for the traffic flow overlay which can be displayed for both raster and vector tiles. The Style obtained from the Style Merger endpoint contains only one type of the Traffic Flow. To display other types of Traffic Flow it is required to reload the style to one which contains another Traffic Flow type.

The complete list of supported Traffic Flow types is listed below:

  1. absolute: Free-flow speed.

  2. relative (default): Speed relative to free-flow.

  3. relative-delay: Speed relative to free-flow, but only when different.

  4. reduced-sensitivity: Speed relative to free-flow, but with wider speed ranges.

Traffic incident tiles

Maintaining the currency of traffic incident tiles

IMPORTANT: The Maps SDK should be initialized with the style from Style Merger which only supports vector tiles. The approach of using a single style that contains both Raster and Vector tiles was deprecated. After the deprecation period is over, it will not be possible to switch between Raster and Vector Traffic Incidents without reloading the style.

Traffic incident data provided as map tiles by the Vector Incident Tiles and Raster Incident Tiles services is updated periodically to reflect the current state of traffic as closely as possible. It might happen that the traffic data changes between two requests to the service. In this situation, always requesting the most recent data may lead to inconsistencies in the visual representation of traffic. Adjacent tiles may show traffic in different states.

The traffic incident tile services provide a way to synchronize tiles between Requests. If the ID of a traffic model is supplied in a Request’s URL, the traffic model specified by that ID is used to fulfill the Request. The Traffic Incident Viewport service provides the ID of the most recent traffic model shared between all tiles within the provided viewport. The Maps SDK automatically synchronizes traffic incident tiles displayed on the map and maintains their currency by periodically requesting a traffic model ID for the current viewport.

The Maps SDK requests a current traffic model ID from the Traffic Incident Viewport service every 30 seconds as long as the visibility of at least one traffic incident layer is set to true. If the new ID and the current one are different, new traffic incident tiles are requested from the respective service. All regular charges apply.

Default style

Layer groups in the default style

IMPORTANT: The Maps SDK should be initialized with the style from Style Merger which only supports vector tiles. The approach of using a style that contains both raster and vector tiles was deprecated. After the deprecation period is over the default style will not contain raster layer groups.

In order to display raster tiles, you can check out our Map Tiles example.

The default style delivered with the SDK contains the following layer groups (background to foreground):

  1. Background: Color and pattern displayed in places where there is no other map data.

  2. Vector map: The baseline tile layer in vector format.

  3. Raster map: The baseline tile layer in raster format.

  4. Raster overlay for hybrid maps: Streets, labels, and icons on a transparent background.

  5. Traffic flow: Raster and vector traffic flow tile overlays.

  6. Traffic incidents: Raster and vector traffic incident tile overlays.

  7. Routes :Planned and alternative routes.

  8. Vector map labels and icons – Rendered on top of most other layers for better readability.

  9. GPS inaccuracy indicator - A circle indicating the GPS inaccuracy area.

  10. Position indicator - A static location marker.

  11. Chevron - An animated location marker.