map-tiles

MapTrip is a GPS navigation software for trucks, waste management and emergency vehicles.

This project allows you to use MapTrip map tiles in third-party mapping APIs like LeafletJS, OpenLayers or Google Maps. For all supported APIs, there is a class with which you can add our maps to the respective API.

To use this API, you need a MapTrip API key. If you are already a user and do not have an API key, please contact our support team.

Authorization

In order to utilize the functionalities provided by the map-tiles package, you need a token obtained through your MapTrip API key. If you don't already have an API key, please contact our support team.

Tokens are granted with a validity period of up to 30 days. After that timeframe, you have to generate a new token. To get a new token, initiate a POST request with your API Key and a new duration to https://api.maptrip.de/v1/authenticate/apikey:

fetch("https://api.maptrip.de/v1/authenticate/apikey", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    apikey: "YOUR_API_KEY",
    duration: 2592000,
  }),
});

The response body will include the key token in the schema:

{
	"token": string,
	"authorization": string,
}

Integration in your mapping API

LeafletJS

Supported versions: 1.0.0 and newer (recommended: 1.9.x)

Install LeafletJS with npm install leaflet@~1.9.x. To use MapTrip map tiles in LeafletJS, you create an instance of MapTripLeafletGridLayer and add it to the layers of a map:

import { MapTripLeafletGridLayer } from "@maptrip/map-tiles";

import L from "leaflet";
import "leaflet/dist/leaflet.css";

const layer = new MapTripLeafletGridLayer({
  provider: "TomTom",
  token: "Insert your MapTrip token here",
});

L.map("map", {
  center: [50.94017, 6.95988],
  zoom: 13,
  layers: [layer],
});

MapTripLeafletGridLayer can be configured with all properties listed in the section Properties, and also with these:

• token: A valid and non-expired token for your account, see section Authorization (required)
• attribution: The copyright notes to show in the map
• minZoom: The minimum zoom level for the map (must not be smaller than 2)
• maxZoom: The maximum zoom level for the map (must not be larger than 18)

OpenLayers

Supported versions: 7.0.0 and newer (recommended: 8.2.x)

Install OpenLayers with npm install ol@~8.2.x. To create a map application with OpenLayers and MapTrip map tiles, you create an instance of MapTripOpenLayersSource and add it to the layers of a map:

import { MapTripOpenLayersSource } from "@maptrip/map-tiles";

import Map from "ol/Map.js";
import View from "ol/View.js";
import TileLayer from "ol/layer/Tile.js";
import * as olProj from "ol/proj";
import "ol/ol.css";

new Map({
  layers: [
    new TileLayer({
      source: new MapTripOpenLayersSource({
        provider: "TomTom",
        token: "Insert your MapTrip token here",
      }),
    }),
  ],
  view: new View({
    projection: "EPSG:3857",
    center: olProj.fromLonLat([6.95988, 50.94017]),
    zoom: 13,
  }),
  target: "map",
});

MapTripOpenLayersSource can be configured with all properties listed in the section Properties, and also with these:

• token: A valid and non-expired token for your account, see section Authorization (required)

Google Maps

Supported versions: 1.16.1 and newer

Install the Google Maps JavaScript API JS loader with npm install @googlemaps/js-api-loader@~1.16.x.

import { MapTripGoogleMapType } from "@maptrip/map-tiles";
import { Loader } from "@googlemaps/js-api-loader";

new Loader({
  apiKey: "Insert your Google Maps API key here",
})
  .importLibrary("maps")
  .then(({ Map }) => {
    const map = new Map(document.getElementById("map"), {
      zoom: 13,
      center: { lat: 50.94017, lng: 6.95988 },
      mapTypeId: "MapTrip",
      mapTypeControlOptions: {
        mapTypeIds: ["roadmap", "satellite", "MapTrip"],
      },
    });

    let mapType = new MapTripGoogleMapType({
      token: "Insert your MapTrip token here",
      name: "MapTrip",
      provider: "TomTom",
    });
    map.mapTypes.set("MapTrip", mapType);
  })
  .catch((e) => {
    console.error("Failed to import Google Maps API:", e);
  });

MapTripGoogleMapType can be configured with all properties listed in the section Properties, and also with these:

• token: A valid and non-expired token for your account, see section Authorization (required)
• name: The name Google Maps will show in the map types selection

Other Maps

If you use an API that is not in the list above, you can integrate the tiles yourself. To do this, you need to find out how you can integrate your own function that provides the tiles.

This function will be called with the x, y and z indexes of all tiles. To create a tile for an index, you can use our factory class. This is initialized with the map provider you want to use:

import { VectorTileFactory } from "@maptrip/map-tiles";

const factory = VectorTileFactory.createFactory({ provider: "TomTom" });

Using this factory, you can create tiles by providing their x, y and z indexes and your MapTrip token (see Authorization):

let canvas = factory.getJsonTile(x, y, z, token);

You can also provide a callback which is called when the tile is rendered:

let canvas = factory.getJsonTile(x, y, z, token, () => {
  canvas.className = "loaded";
});

Please refer to the documentation of your API to see how you can implement your own tiles provider.

Map Data Providers

The maps can be rendered with map data from various providers. To do this, set the property provider to one of the strings TomTom, HERE or OpenStreetmap when creating a factory:

const factory = VectorTileFactory.createFactory({
  provider: "TomTom",
});

Which data you are allowed to use depends on your MapTrip license. If in doubt, please contact our support team.

MapTrip Detour Profiles

You can use the MapTrip Detour Editor to create your own profiles that change the map data. For example, you can block or prioritize roads and even delete or add new roads.

Deleting or adding new roads affect the map when you specify your profile: Deleted roads are no longer visible and newly created roads are shown in the map.

Use the endpoint GET /detour/file/all of the MapTrip Server API to query the profile string of all your Detour files created in the editor or with the API.

Let's assume the response looks like this:

[
  {
    "id": 12345,
    "name": "My Detour File",
    "version": 10,
    "profile": "olrclient_MapTrip_xxxxx_56789_My Detour File"
  }
]

In this case you have to provide the profile olrclient_MapTrip_xxxxx_56789_My Detour File to show it in the map:

const layer = new MapTripLeafletGridLayer({
  provider: "TomTom",
  detourProfile: "olrclient_MapTrip_xxxxx_56789_My Detour File",
  token: "Insert your MapTrip token here",
});

Properties

You can specify a third parameter with properties when creating the factory. These values are available:

| Property | Description | Default Value | | ----------------- | ------------------------------------------------------------------------------------------------- | ------------------------ | | provider | The map data provider (TomTom, HERE or OpenStreetmap) | OpenStreetmap | | baseMap | Set to false for a traffic overlay which can be used on top of e.g. an aerial view | true | | traffic | Add traffic flows to the map tiles (only available for TomTom and HERE maps) | false | | timeout | Load timeout for tiles in milliseconds. Increase this if you have a very slow internet connection | 5000 | | parallelDownloads | The number of tiles that are loaded in parallel | 12 | | detourProfile | The name of a MapTrip Detour Profile, see MapTrip Detour | | | renderingConfig | Set a custom rendering configuration to customize layers, colors, line widths etc. | RENDERING_CONFIG_DEFAULT |

This factory initializes a factory with TomTom data and traffic flows:

const factory = VectorTileFactory.createFactory({
  provider: "TomTom",
  traffic: true,
});

Here is an example of how you can increase the timeout to 10 seconds:

const factory = VectorTileFactory.createFactory({
  provider: "OpenStreetmap",
  timeout: 10000,
});

If you want to display traffic flows on a bitmap map (e.g. aerial images), you can use a factory that only renders traffic and no base map:

const factory = VectorTileFactory.createFactory({
  provider: "HERE",
  baseMap: false,
  traffic: true,
});

It will create tiles which have a transparent background and semi-transparent traffic flows. To use them, you mapping API has to be able to use both base layers and overlays.

History

• 1.2.1: Fixed a bug in MapTripLeafletGridLayer type implementation
• 1.2.0: Added TypeScript declaration file
• 1.1.1: Added rendering config for foot_path layer
• 1.1.0: Added MapTrip detour profiles
• 1.0.8: First public version