Getting Started

Our JavaScript API lets you embed Trimble’s trusted commercial-vehicle specific maps and routing in your own web applications. The API can be used on its own or as a plug-in for open-source mapping libraries including Leaflet and OpenLayers.

This guide is intended to give you an overview of how to build and customize maps and take advantage of industry standard PC*MILER routing, geocoding and location data. It is designed for people familiar with JavaScript and object-oriented programming.

For more detailed information about all of the functions, please see our API Documentation.

What Can You Do?

Our JavaScript maps can be the foundation of a limitless range of map-centric solutions for work. You can visualize precise information about any location; interactively plan commercial vehicle routes; and generate turn-by-turn driving directions and total miles.

A Basic Map

The easiest way to learn about our maps is to see a basic example. This code will produce a map centered on the lower 48 states of the U.S.

<!DOCTYPE html>
<html>
  <head>
    <style>
      html,
      body,
      #map {
        margin: 0;
        padding: 0;
        height: 100%;
      }
    </style>
    <script src="https://maps.alk.com/api/1.2/alkmaps.js"></script>
    <script>
      var map;
      var lon = -96,
        lat = 35,
        zoom = 3;
      function init() {
        ALKMaps.APIKey = "YOUR_KEY_HERE";
        map = new ALKMaps.Map("map");
        var lonLat = new ALKMaps.LonLat(lon, lat).transform(
          new ALKMaps.Projection("EPSG:4326"),
          map.getProjectionObject()
        );
        map.setCenter(lonLat, zoom);
      }
    </script>
  </head>
  <body onLoad="init()">
    <div id="map" style="width:100%; height:100%"></div>
  </body>
</html>

Default Controls

Default Controls

The map comes with several controls enabled by default. These controls allow the user to pan and zoom via the mouse or keyboard. A scale control is also drawn in the lower right-hand corner of the map to provide a visual indication of the current scale of the map.

Please note that all map controls will inherit their projection from the map. For example, a mouse position control on a map in spherical mercator will display its coordinates in meters rather than degrees. You change this by setting the displayProjection parameter of the map to the desired projection.

var map = new ALKMaps.Map("map", {
  displayProjection: new ALKMaps.Projection("EPSG:4326")
});

For more information on what controls are and the different types available, see the Controls section of this guide.

Interactive Samples

Throughout this guide, you will see interactive examples where you can modify code to visualize its effect on the map. Below is the interactive version of the code above. You can easily change the zoom level or longitude and latitude. Press the Update Map button to refresh the map and the Reset button to return the code to the original state.

Breaking Down the Elements

We recommend declaring the document type as HTML5 using <!doctype html> which will make your document much more cross-browser compliant. The DOCTYPE will be ignored by some older browsers, but it won’t cause them to fail. In order to account for quirks in these older browsers, we must also explicitly set the height of the HTML and BODY elements as well as our map container.

The Toolkit

You must include a script tag reference to the maps toolkit JavaScript file in HTML.

<script src="https://maps.alk.com/api/1.2/alkmaps.js"></script>

The API Key

In order for the toolkit to work properly, you declare a variable containing your API key before calling any objects in the toolkit. Go here if you would like to contact us about purchasing a key.

ALKMaps.APIKey = “YOUR_KEY_HERE”; In version 1.2 you also have the option of being able to specify your API key in the query string of the ALKMaps.js reference.

<script src="https://maps.alk.com/api/1.2/alkmaps.js?key=YourAPIKeyHere"></script>

The Map

The first element needed is the map. The map is created by creating a new instance of ALKMaps.Map and passing in the DOM id of the container that will hold the map.

map = new ALKMaps.Map("map");

The HTML element that will serve as the map container needs to have an explicit width and height set via CSS either in an associated stylesheet or inline on the element. These values can either be percentages or absolute values and can be changed at any time in the page lifecycle. Due to way browsers report sizing, using only min-width and min-height will cause the map to not render properly.

The Center

Once the map is created, you’ll need to set the center and zoom level of the map. This is required so the map knows what area to draw.

var center = new ALKMaps.LonLat(-96, 35).transform(
  new ALKMaps.Projection("EPSG:4326"),
  map.getProjectionObject()
);
map.setCenter(center, 3);
Last updated November 21, 2019.