@maptrip/map-tiles 1.0.8

package/README.md

@@ -0,0 +1,239 @@
+# map-tiles
+
+[MapTrip](https://maptrip.de) 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](mailto:support@infoware.de).
+
+## 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](mailto:support@infoware.de).
+
+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:
+
+```js
+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:
+
+```json
+{
+	"token": string,
+	"authorization": string,
+}
+
+```
+
+## Integration in your mapping API
+
+### LeafletJS
+
+Supported versions: 1.0.0 and newer (recommended: 1.9.x)
+
+Install [LeafletJS](https://leafletjs.com/) 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:
+
+```js
+import { MapTripLeafletGridLayer } from "dist/map-tiles.js";
+
+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](https://openlayers.org/) 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:
+
+```js
+import { MapTripOpenLayersSource } from "dist/map-tiles.js";
+
+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](https://developers.google.com/maps/documentation/javascript/overview)
+JS loader with `npm install @googlemaps/js-api-loader@~1.16.x`.
+
+```js
+import { MapTripGoogleMapType } from "dist/map-tiles.js";
+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:
+
+```js
+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_):
+
+```js
+let canvas = factory.getJsonTile(x, y, z, token);
+```
+
+You can also provide a callback which is called when the tile is rendered:
+
+```js
+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:
+
+```js
+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](mailto:support@infoware.de).
+
+## 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                       |
+| 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:
+
+```js
+const factory = VectorTileFactory.createFactory({
+  provider: "TomTom",
+  traffic: true,
+});
+```
+
+Here is an example of how you can increase the timeout to 10 seconds:
+
+```js
+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:
+
+```js
+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.