v4 upgrade guide

With the March 2025 release of version 4, the Trimble Maps JavaScript SDK has transitioned to a TypeScript-based library with rendering engine updates. It uses WebGL2 to render high-performance maps with complex visual effects. The improved capabilities of WebGL2 allow for smoother interactions and more detailed visual representations.

See v4 examples

Map rendering engine change

• v3 uses a proprietary rendering engine with Trimble’s SDK, and is typically integrated with older Mapbox GL JS versions.
• v4 now uses MapLibre, which is based on Mapbox GL JS but is a community-supported fork. Map rendering capabilities are similar but may have differences in specific features and API implementations.

Required updates

While v4 is backwards compatible with v3, there are differences that may require slight changes in your implementation. This page describes the updates that may be required.

Two changes are required in order to migrate to v4 from v3.

1. Update the version reference.

<script src="https://maps-sdk.trimblemaps.com/v4/trimblemaps-{{version number, e.g. 4.2.1}}.js"></script>

<link rel='stylesheet' href='https://maps-sdk.trimblemaps.com/v4/trimblemaps-{{version number, e.g. 4.2.1}}.css' />

2. Update the method for passing your API Key.

v3 initialization

TrimbleMaps.APIKey = 'YOUR API KEY HERE';
const map = new TrimbleMaps.Map({
    container: 'map',
    style: TrimbleMaps.Common.Style.BASIC,
    region: TrimbleMaps.Common.Region.WW,
    language: TrimbleMaps.Common.Language.EN,
    center: [-74.5, 40],
    zoom: 9
});

v4 initialization

TrimbleMaps.setAPIKey('YOUR API KEY HERE');
const map = new TrimbleMaps.Map({
    container: 'map',
    style: TrimbleMaps.Common.Style.TRANSPORTATION,
    region: TrimbleMaps.Common.Region.WW,
    language: TrimbleMaps.Common.Language.EN,
    center: [-74.5, 40],
    zoom: 9
});

The initialization code structure remains mostly the same. Both libraries use a Map constructor.

API compatibility

Maps SDK v4 supports all current functions used in our applications. Custom layers, styles, and plugins are compatible or have alternatives in Maps SDK v4.

All global “getters” and “setters” have been removed from TrimbleMaps. As a result, the following methods have changed between versions, and should be replaced in your code when upgrading to v4.

Other changes

Map touch zoom and scroll behavior

• v3: Supports default touch zoom and scroll behaviors.
• v4: Similar touch zoom and scroll behaviors, but minor differences may exist due to updates and optimizations in SDK v4.

Default map interactivity and event handling

• v3: Provides default event handling for common map interactions (e.g., click, hover, drag).
• v4: Maintains compatibility with v3 SDK event handling. Users should review any specific changes or optimizations in event handling provided by SDK v4.

Map animation and transition effects:

• v3: Includes default animation and transition effects for map movements (e.g., zooming, panning).
• v4: Continues to support animation and transition effects, with potential updates and optimizations.

v3 comparison to v4

Map controls and interactions

Control classes and methods to add controls remain the same (NavigationControl).

v3 and v4

map.addControl(new TrimbleMaps.NavigationControl());

Layers and sources

There are no significant changes in how sources and layers are added in terms of API methods and parameters. Ensure compatibility of data formats and sources used within SDK v4.

v3 and v4

Trimble Maps SDK v4:
map.addSource('example-source', {
    type: 'geojson',
    data: {
        type: 'FeatureCollection',
        features: [...]
    }
});

map.addLayer({
    id: 'example-layer',
    type: 'circle',
    source: 'example-source',
    paint: {
        'circle-color': '#FF0000',
        'circle-radius': 6,
        'circle-stroke-width': 2,
        'circle-stroke-color': '#FFFFFF'
    }
});

Events handling

Event handling methods (on) and event object (e) remain the same.

v3 and v4:

map.on('click', function(e) {
    console.log('Clicked at:', e.lngLat);
});

Map styling

v3 and v4

• Styling uses the Mapbox Style Specification (JSON format).
• Supports custom styles.

style: 'trimblemaps://styles/v4/bsr_2',

Changes

• The styling mechanism remains consistent with the v3 Style Specification.
• Ensure style URLs and custom style implementations are compatible with v4 SDK.
• Compatibility Notes: SDK v4 intends to be directly compatible with styles that are compatible with SDK v3. This means that styles designed for SDK v3 should load and display correctly in SDK v4 without requiring modification to the style URLs.

Content Layers

Content Layers in v4 SDK

• Traffic
• Road Surface
• Weather Cloud
• Weather Radar
• Weather Alerts
• POI
• CustomRoad
• Truck Restriction
• Traffic Incidents
• Traffic Cameras

const trafficLayer = new TrimbleMaps.Traffic();
const pointsOfInterest = new TrimbleMaps.PointsOfInterest();
 const weatherCloud = new TrimbleMaps.WeatherCloud();
 const weatherRadar = new TrimbleMaps.WeatherRadar();
 const weatherAlert = new TrimbleMaps.WeatherAlert();
 const roadSurface = new TrimbleMaps.RoadSurface();
 const customRoad = new TrimbleMaps.CustomRoad();
 map.on('load', () => {
        trafficLayer.addTo(map);
        pointsOfInterest.addTo(map);
        weatherCloud.addTo(map);
        weatherRadar.addTo(map);
        weatherAlert.addTo(map);
        roadSurface.addTo(map);
        customRoad.addTo(false);
});   });

 customRoad.setVisibility(false);
 trafficLayer.setVisibility(false);


// Similarly we can toggle the visibility of all content layers like below

trafficLayer.toggleVisibility();
customRoad.toggleVisibility();
weatherCloud.toggleVisibility();
pointsOfInterest.toggleVisibility();
weatherRadar.toggleVisibility();
weatherAlert.toggleVisibility();
roadSurface.toggleVisibility();

// Or get the visibility of the content layer.

trafficLayer.isVisible();
customRoad.isVisible();
weatherCloud.isVisible();
pointsOfInterest.isVisible();
weatherRadar.isVisible();
weatherAlert.isVisible();
roadSurface.isVisible();

workerCount

In Trimble Maps, workerCount is a configuration that allows you to control the number of web workers used for parsing and managing vector tiles. Web workers are separate JavaScript threads that can run concurrently with the main application thread. This helps improve performance by offloading tasks to background threads.

By default, workerCount is 1 except for the Safari browser where it is set to half the number of CPU cores (capped at 3).

Make sure to set this property before creating any map instances for it to have effect.

Here’s how you can use workerCount in TrimbleMaps:

TrimbleMaps.setAPIKey("YOUR_KEY_HERE");
TrimbleMaps.setWorkerCount(2);
const map = (window.map = new TrimbleMaps.Map({
  container: "map",
  zoom: 12.5,
  center: [-77.01866, 38.888],
  //center: [-0.12,51.5],
  region: TrimbleMaps.Common.Region.NA,
  //region: TrimbleMaps.Common.Region.WW,

  style: TrimbleMaps.Common.Style.TRANSPORTATION,
  language: TrimbleMaps.Common.Language.AR,
  hash: true,
}));

const nav = new TrimbleMaps.NavigationControl();
map.addControl(nav, "top-right");

map.on("load", function () {
  // Add layers, markers, interactions, etc.here
});

Why use workerCount?

Increasing the number of web workers improves parsing and rendering performance, especially when working with complex vector tile data or when rendering multiple layers. Web workers allow tasks to be processed concurrently without blocking the main UI thread, which helps maintain a smooth user experience.

Considerations before using workCount

Increasing workerCount beyond what the device can handle might lead to diminished performance or even crashes on low-end devices or in environments with limited computational resources. In addition, using more workers can increase the number of concurrent requests to fetch vector tile data. Ensure your server can handle the increased load if applicable.

We recommend you adjust workerCount based on performance testing and user feedback to find the optimal balance between responsiveness and resource usage for your specific application.

maxParallelImageRequests

maxParallelImageRequests sets the maximum number of images (raster tiles, sprites, icons) to load in parallel, which affects performance in raster-heavy maps. This is particularly useful when you have a large number of markers or layers that load images, such as icons or tiles, and you want to manage the performance impact on the client side. The default value is 16.

Here’s an example of how you can use maxParallelImageRequests in Trimble Maps.

TrimbleMaps.setAPIKey("YOUR_KEY_HERE");
TrimbleMaps.setMaxParallelImageRequests(18);
const map = (window.map = new TrimbleMaps.Map({
  container: "map",
  zoom: 12.5,
  center: [-77.01866, 38.888],
  //center: [-0.12,51.5],
  region: TrimbleMaps.Common.Region.NA,
  //region: TrimbleMaps.Common.Region.WW,

  style: TrimbleMaps.Common.Style.TRANSPORTATION,
  language: TrimbleMaps.Common.Language.AR,
  hash: true,
}));

This setting helps in scenarios where:

• There are many markers or layers with icons that are loaded dynamically.
• You want to avoid overwhelming the client with too many concurrent image requests, which can degrade performance.

The actual impact and performance gains will depend on various factors such as network conditions, device capabilities, and the size of the images being requested. Adjust maxParallelImageRequests accordingly based on performance testing and user experience

Samples for v4

CDN reference

<link href="https://maps-sdk.trimblemaps.com/v4/trimblemaps-4.2.2.css" rel="stylesheet" />
<script src="https://maps-sdk.trimblemaps.com/v4/trimblemaps-4.2.2.js"></script>

Methods

TrimbleMaps.setAPIKey("YOUR_KEY_HERE");
TrimbleMaps.setAPIToken("YOUR_TOKEN_HERE");
TrimbleMaps.setworkerUrl = 'https://maps-sdk.trimblemaps.com/v4/trimblemaps-4.2.2-csp-worker.js';

Example page

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link href="https://maps-sdk.trimblemaps.com/v4/trimblemaps-4.2.2.css" rel="stylesheet" />
    <script src="https://maps-sdk.trimblemaps.com/v4/trimblemaps-4.2.2.js"></script>
    <style>
      body {
        margin: 0;
        padding: 0;
      }
      #map {
        position: absolute;
        top: 0;
        bottom: 0;
        width: 100%;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>

    <script>
      TrimbleMaps.setAPIKey("68B06901AF7DA34884CE5FB7A202A743");
      const map = new TrimbleMaps.Map({
        container: "map", // container id
        style: TrimbleMaps.Common.Style.TRANSPORTATION, //hosted style id
        center: [-75, 40], // starting position
        zoom: 9, // starting zoom
      });
    </script>
  </body>
</html>