Developer

Migrate from version 4 - the Services library

Deprecation notice

February 01, 2025

  • Maps SDK for Web V6 has been deprecated.
  • The SDK CDN endpoints and Plugins CDN endpoints will be withdrawn following a 12 months deprecation period.
  • The planned withdrawal date is February 01, 2026.
  • Following withdrawal, requests to the CDN endpoints will return a 404 HTTP status code.
  • Please note: For customers whose contracts extend beyond February 01, 2026, the service will continue to operate until the end of your contractual period. If you have any questions or need further assistance, please contact us.


Explore our new Maps SDK for JavaScript, currently in Public Preview.

Overview of the tutorial

This tutorial covers basic use cases to help you switch our services. For example, switching the Routing API or Search API services from version 4 of the Maps SDK for Web to our new version. We will use code examples to explain the main differences between the SDKs. In the new SDK, ** services** are not part of the map library. We now provide a separate library to only include services.

You can check how to migrate map displaying here: Migrate from version 4 - the Maps library

Prerequisites

To start using the latest version of TomTom Maps SDK for Web you need the following:

  • The Services library
    The Maps SDK for Web can be used in three ways:
  • API Key - If you don't have an API Key visit the How to get a TomTom API Key site and create one.
  • Add the following to the <head> element of your HTML document: 
    <!-- Replace version in the URL with desired library version -->
    <script src="https://api.tomtom.com/maps-sdk-for-web/cdn/6.x/<version>/services/services-web.min.js"></script>
    Maps and services use the same namespace and will automatically attach themselves to the tt object. Services will be accessible using tt.services.

Displaying a route/directions

Here we have the code to display a route from point A to point B on the map.

Version 4 of the Maps SDK for Web

1tomtom
2  .routing()
3  .key("<your-api-key>")
4  .locations("37.7683909618184,-122.51089453697205:37.769167,-122.478468")
5  .go()
6  .then(function (routeJson) {
7    var route = tomtom.L.geoJson(routeJson, {
8      style: { color: "#00d7ff", opacity: 0.6, weight: 6 },
9    }).addTo(map)
10    map.fitBounds(route.getBounds(), { padding: [5, 5] })
11  })

Latest version of the Maps SDK for Web

1tt.services
2  .calculateRoute({
3    key: "<your-api-key>",
4    locations: "-122.510601,37.768014:-122.478468,37.769167",
5  })
6  .then(function (response) {
7    var geojson = response.toGeoJson()
8    map.addLayer({
9      id: "route",
10      type: "line",
11      source: {
12        type: "geojson",
13        data: geojson,
14      },
15      paint: {
16        "line-color": "#00d7ff",
17        "line-width": 8,
18      },
19    })
20    var bounds = new tt.LngLatBounds()
21    geojson.features[0].geometry.coordinates.forEach(function (point) {
22      bounds.extend(tt.LngLat.convert(point))
23    })
24    map.fitBounds(bounds, { padding: 20 })
25  })

Performing a fuzzy search

Version 4 of the Maps SDK for Web

1tomtom
2  .fuzzySearch()
3  .key("<your-api-key>")
4  .query("pizza")
5  .go()
6  .then(function (result) {
7    console.log(result)
8  })

Latest version of the Maps SDK for Web

1tt.services
2  .fuzzySearch({
3    key: "<your-api-key>",
4    query: "pizza",
5  })
6  .then(function (result) {
7    console.log(result)
8  })

Differences in APIs

Here is an overview of some of the most important updates within our top-level namespace.

Common factory functions renamed

Some of the common functions changed. Here are some examples:

Version 4Current version
tomtom.key(key, [value])

You need to pass the API Key directly to the service.

   `tt.services.fuzzySearch({key: API-KEY, ...});`
tomtom.localeService()

You need to pass the language directly to the service. For the map, you can also change the language after initialization by doing:

   `map.setLanguage('en');`

The following table lists the services from the version 4 of the SDK and their equivalents in the latest one.

Version 4Current version
tomtom.additionalData()tt.services.additionalData()
tomtom.alongRouteSearch()tt.services.alongRouteSearch()

No equivalent

tt.services.autocomplete()

tomtom.reachableRange()tt.services.calculateReachableRange()
tomtom.routing()tt.services.calculateRoute()
tomtom.categorySearch()tt.services.categorySearch()
tomtom.copyright()tt.services.copyrights()
tomtom.copyrightCaption()tt.services.copyrightsCaption()
tomtom.crossStreetLookup()tt.services.crossStreetLookup()

No equivalent

tt.services.evChargingStationsAvailability()

tomtom.fuzzySearch()tt.services.fuzzySearch()
tomtom.geocode()tt.services.geocode()
tomtom.geometrySearch()tt.services.geometrySearch()

No equivalent

tt.services.incidentViewport()

tomtom.matrixRouting()tt.services.matrixRouting()
tomtom.nearbySearch()tt.services.nearbySearch()

No equivalent

tt.services.poiCategories()

tomtom.poiSearch()tt.services.poiSearch()
tomtom.reverseGeocode()tt.services.reverseGeocode()
tomtom.staticMapImage()tt.services.staticImage()
tomtom.structuredGeocode()tt.services.structuredGeocode()
tomtom.traffic()tt.services.incidentDetails()
tomtom.trafficFlowSegmentData()tt.services.trafficFlowSegmentData()