Transition to v4

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.

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.

Required updates

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

1. Update the version reference to:

<link  href="https://maps-sdk.trimblemaps.com/v4/trimblemaps-4.2.1.css" rel="stylesheet">

<script src="https://maps-sdk.trimblemaps.com/v4/trimblemaps-4.2.1.js"></script>

2. Update the method for passing your API Key to:

TrimbleMaps.setAPIKey ('YOUR_KEY_HERE');

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. The following methods have changed between versions, and should be replaced in your code when upgrading to v4.

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.1.css" rel="stylesheet" />
<script src="https://maps-sdk.trimblemaps.com/v4/trimblemaps-4.2.1.js"></script>

Methods

TrimbleMaps.setAPIKey("YOUR_KEY_HERE");
TrimbleMaps.setAPIToken("YOUR_TOKEN_HERE");
TrimbleMaps.setworkerUrl = 'https://maps-sdk.trimblemaps.com/v4/trimblemaps-4.2.1-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.1.css" rel="stylesheet" />
    <script src="https://maps-sdk.trimblemaps.com/v4/trimblemaps-4.2.1.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>