@mappingfactory/sdk-js v1.0.5

What is @mappingfactory/sdk-js

The @mappingfactory/sdk-js is a comprehensive software development kit that is intended to replace the current Legacy SDK. Its primary goal is to harness Michelin's navigation and mapping services, delivering advanced features such as route calculation and map display to boost the Mapping Factory division's capabilities.

Get Started

Table of Contents

• Development environment setup
• Installation
• Search
• Direction API

Development Environment Setup

To run this project locally, navigate to the Project Directory and follow these steps:

Install Dependencies:

Use npm to install the project's dependencies:

npm install

Build the Project for Development:

Build the project using the following command. This will compile and bundle the JavaScript files and other assets:

npm run build:dev

Start the Development Server:

To preview the project locally, you can use npx serve. This will start a local server, and you can access the project in your browser at the following URL: http://localhost:3000.

npx serve

Installation

You can install the @mappingfactory/sdk-js package using one of the following methods:

Option 1: Using jsDelivr CDN

Include the following script tag in your HTML file to load the @mappingfactory/sdk-js library from the jsDelivr CDN:

<script src="https://cdn.jsdelivr.net/npm/@mappingfactory/sdk-js{version}/dist/michelin-sdk.min.js"></script>

Note: Replace {version} with the desired version of the library.

Usage in a script tag

const { MichelinSDKClient } = window.MichelinSDK

const sdk = new MichelinSDKClient({
  apiKey: "YOUR_API_KEY"
})

```


### Option 2: Using npm

If you prefer to use `npm` and manage dependencies with a package manager, you can install the `@mappingfactory/sdk-js` package by running the following command:

```bash
npm install @mappingfactory/sdk-js

Note: After installation, you can use the package in your JavaScript project.

CommonJS (CJS) Module

If you are using CommonJS (CJS) modules, import the @mappingfactory/sdk-js package as follows:

const { MichelinSDKClient } = require('@mappingfactory/sdk-js');

Warning about Node usage

If you are using a version of Node older than version 18, fetch is not included by default and the SDK might throw an error. To fix this, you can use a polyfill like isomorphic-fetch and import it before using the SDK:

const fetch = require('isomorphic-fetch');
const { MichelinSDKClient } = require('@mappingfactory/sdk-js');

ECMAScript Module (ESM)

If you are using ECMAScript modules (ESM), import the @mappingfactory/sdk-js package as follows:

import { MichelinSDKClient } from '@mappingfactory/sdk-js';

Note: Make sure your project's build setup supports CJS or ESM modules based on your preference.

Michelin SDK

Search

The Search class of the MichelinSDKClient, which offers functionality for searching and geocoding locations using the Michelin API, will be discussed in this section. The SDK enables you to carry out location searches using a variety of criteria and retrieve results in an approachable format.

Setting up the MichelinSDKClient

To use the MichelinSDKClient's Search class, you need to use the loadSearchLibrary function that will create an instance of the Search class. Here's a basic setup:

// Replace 'YOUR_API_KEY' with your actual Michelin API key
const apiKey = 'YOUR_API_KEY';

const sdk = new MichelinSDKClient({ apiKey });

// Load and initialize the Search class
const search = await sdk.loadSearchLibrary();

// You can also access the Search class directly from the MichelinSDKClient instance after initialization using `loadSearchLibrary`
const search = sdk.Search;

Available Options

Geocoding

The Michelin SDK provides a function that allows you to convert a free text address into geographic coordinates (latitude and longitude). To perform a geocoding search, use the geocoding method of the Search class:

const address = 'Paris, France';
const options = {
  limit: 5,
  language: 'en-US',
  // Add more options if needed
};

try {
  const result = await search.geocoding({ address, ...options });
  console.log(result);
} catch (error) {
  console.error('Geocoding failed:', error.message);
}

In this example, we perform a geocoding search for the address "Paris, France" with additional options such as limiting the results to 5 and specifying the language as English (en-US).

Available Options

Autocomplete Widget

The MichelinSDKClient provides an autocomplete widget that allows users to search for locations and select them from a dropdown list. To generate the autocomplete widget, use the autocomplete method of the Search class:

const element = document.getElementById('autocomplete');
const options = {
  debounce: 300,
  allowTab: true,
  input: {
    placeholder: 'Search for a location',
  },
  dropdown: {
    noResultsOpen: true,
    position: 'right',
  },
  dropdownItem: {
    highlight: true,
  },
  // Add more options if needed
};

try {
  const autocomplete = await search.autocomplete(element, options);

  autocomplete._on('selected', (result) => {
    console.log('Selected location:', result);
  });
} catch (error) {
  console.error('Autocomplete initialization failed:', error.message);
}

In this example, we generate an autocomplete widget for the HTML element with the ID "autocomplete" and provide additional options like debounce time, placeholder text, and auto-fill behavior.

The _on('selected') method allows you to listen for the event when the user selects a location from the autocomplete dropdown. When a location is selected, the associated callback function will be executed, and the selected location information will be logged to the console.

Events supported

This chapter covered the basic usage of the MichelinSDKClient's Search class and its functionalities, including geocoding and the autocomplete widget. By integrating the MichelinSDKClient into your applications, you can provide enhanced location search capabilities and enrich your user experience.

Available Options

Direction API

The Michelin Directions API allows developers to access routing and directions information for different modes of transportation, such as driving, walking, or cycling. The DirectionWrapper class provides a simplified way to interact with this API by handling API key authentication and setting various route options.

Setting up the DirectionWrapper

To use the MichelinSDKClient's DirectionWrapper class, you need to use the loadDirectionLibrary function that will create an instance of the DirectionWrapper class and returns the Mapping Directions API Client to make requests. Here's a basic setup:

...
// Replace 'YOUR_API_KEY' with your actual Michelin API key
const apiKey = 'YOUR_API_KEY';

const sdk = new MichelinSDKClient({ apiKey });

// Load and initialize the `DirectionWrapper` class and resolve the promise with the Direction wrapper
const directionWrapper = await sdk.loadDirectionLibrary();

// You can access the `DirectionWrapper` class directly from the MichelinSDKClient instance
const direction = sdk.Direction;

Setting Direction Options

The DirectionWrapper provides methods to set various options that affect the route calculation and direction retrieval process. These options include transportation mode, waypoints, geometries, duration, language, and more :

// Set options for route calculation using the `DirectionWrapper` class
const formData = {
  coordinates: [
    { latitude: 48.8566, longitude: 2.3522 }, // Paris, France
    { latitude: 51.5074, longitude: -0.1278 }, // London, UK
  ],
  mode: 'fastest',
  language: 'en',
};

sdk.Direction.setFormData(formData);

Using a map with the DirectionWrapper

The DirectionWrapper class can be used with a map to visualize the route and direction information. Here's an example of how to use the setMap, setTraceWidth, setTraceColor, showTrace, and getTraceVisibility methods to display the route on a map:

// Load and initialize the `DirectionWrapper` class and resolve the promise with the Direction wrapper
const directionWrapper = await sdk.loadDirectionLibrary();

// Load and initialize the `MapLibreWrapper` class and resolve the promise with the MapLibre Client
const maplibregl = await sdk.loadMapLibreLibrary();

// Set up the map
const map = new maplibregl.Map({
  container: 'map',
  style: 'my-map-style.json',
  center: [2.3522, 48.8566],
  zoom: 5,
});

// Set the map for the `DirectionWrapper` class
sdk.Direction.setMap(map);

map.on('load', async () => {
  // Get the direction information (We assume in this example that the `formData` has already been set)
  const dataSource = await directionWrapper.client.search();

  // Show the trace on the map for the default layer
  const route = dataSource.routes[0];
  sdk.Direction.showTrace({
    visible: true,
    route,
  });

  // Set the trace width and color for the default layer
  sdk.Direction.setTraceWidth({
    width: 5,
  });
  sdk.Direction.setTraceColor({
    color: '#ff0000',
  });

  // Get the visibility of the trace for the default layer
  const traceVisible = sdk.Direction.getTraceVisibility();

  if (traceVisible) {
    console.log('Trace is visible!');

    sdk.Direction.removeTrace(); // This will remove the default trace from the map
    console.log('Trace has been removed from the map!');
  }
});

Now here is an example if you have multiple routes and want to display them on the map:

// Load and initialize the `DirectionWrapper` class and resolve the promise with the Direction wrapper
const directionWrapper = await sdk.loadDirectionLibrary();

// Load and initialize the `MapLibreWrapper` class and resolve the promise with the MapLibre Client
const maplibregl = await sdk.loadMapLibreLibrary();

// Set up the map
const map = new maplibregl.Map({
  container: 'map',
  style: 'my-map-style.json',
  center: [2.3522, 48.8566],
  zoom: 5,
});

// Set the map for the `DirectionWrapper` class
sdk.Direction.setMap(map);

map.on('load', async () => {
  // Get the direction information (We assume in this example that the `formData` has already been set)
  const dataSource = await directionWrapper.client.search();

  const firstRoute = dataSource.routes[0];
  const lastRoute = dataSource.routes[dataSource.routes.length - 1];

  // Show the trace on the map for a specific layer, if the layer do not exists it will be created
  sdk.Direction.showTrace({
    visible: true,
    route,
    layerId: 'first-route',
  });

  // Set the trace width and color for a specific layer
  sdk.Direction.setTraceWidth({
    width: 5,
    layerId: 'first-route',
  });

  sdk.Direction.setTraceColor({
    color: '#ff0000',
    layerId: 'first-route',
  });

  // Here we show the trace on the map for `last-route` layer, with defaults values for color and width
  sdk.Direction.showTrace({
    visible: true,
    route,
    layerId: 'last-route',
  });

  // Get the visibility of the trace for the default layer
  const firstRouteVisible = sdk.Direction.getTraceVisibility('first-route');
  const lastRouteVisible = sdk.Direction.getTraceVisibility('last-route');

  if (firstRouteVisible && lastRouteVisible) {
    console.log('All routes traces are visible!');

    // Remove the last-route trace from the map
    sdk.Direction.removeTrace('last-route');
  }

  // Now let's toggle the visibility of the first route trace based on a button we have in the DOM

  const button = document.getElementById('btn');

  button.addEventListener('click', () => {
    // We first get the current visibility of the trace
    const isVisible = sdk.Direction.getTraceVisibility('first-route');

    // And then we toggle the visibility of the trace, if you do not pass a `route` parameter, the DirectionWrapper will use the last route used
    sdk.Direction.showTrace({
      visible: !isVisible,
      layerId: 'first-route',
    });
  });
});

• The setMap method saves a reference of the map and creates a new maplibre layer for the route and start point.
• The setTraceWidth and setTraceColor methods allows you to set the width and color of the route and start point.
• You can remove a trace from the map using the removeTrace method.
• Finally, the showTrace method toggles the visibility of the route on the map and updates the data source of the map with the direction information. You can also check if the trace is visible on the map using the getTraceVisibility method.

Available Options

Retrieving Directions

Once the options are set, you can request directions and route information using the Michelin Directions API:

try {
  // Replace 'YOUR_API_KEY' with your actual Michelin API key
  const apiKey = 'YOUR_API_KEY';

  const sdk = new MichelinSDKClient({ apiKey });

  // Load and initialize the `DirectionWrapper` class and resolve the promise with the Direction wrapper
  const directionWrapper = await sdk.loadDirectionLibrary();

  // Set options for route calculation using the `DirectionWrapper` class
  const formData = {
    coordinates: [
      { latitude: 48.8566, longitude: 2.3522 }, // Paris, France
      { latitude: 51.5074, longitude: -0.1278 }, // London, UK
    ],
    mode: 'fastest',
    language: 'en',
  };
  sdk.Direction.setFormData(formData);

  const directions = await directionWrapper.client.search(); // This will uses the `formData` set above by the `DirectionWrapper` function `setFormData`
  console.log('Directions:', directions);
} catch (error) {
  console.error('Failed to retrieve directions:', error.message);
}

Roadsheet API

The Michelin Roadsheet API enables developers to generate detailed navigation instructions for a given route, complementing the Directions API. The RoadSheetWrapper class ensures a hassle-free interaction with this API, managing form data and offering customizable navigation icons.

Setting up the RoadSheetWrapper

To leverage the RoadSheetWrapper via the MichelinSDKClient, you should call the loadRoadsheetLibrary function. This function instantiates the RoadSheetWrapper class and returns the Roadsheet Client that facilitates request-making:

...
// Replace 'YOUR_API_KEY' with your genuine Michelin API key
const apiKey = 'YOUR_API_KEY';

const sdk = new MichelinSDKClient({ apiKey });

// Load and initialize the `RoadSheetWrapper` class and return the Roadsheet Client upon resolving the promise
const roadsheetWrapper = await sdk.loadRoadsheetLibrary();
/**
 * The RoadsheetWrapper is also accessible directly from the MichelinSDKClient instance : `sdk.Roadsheet`
 */

const routePoints = {routes: [{...}], waypoints: [{...}, {...}, {...}]};

const html = await roadsheetWrapper.client.getHtml(routePoints.routes[0], routePoints.waypoints, routePoints.language);

Configuring Roadsheet Options

The RoadSheetWrapper class provides methods to specify various options for your roadsheet generation, allowing developers to customize icons, units, language, date, and other elements:

// Define options for your roadsheet using the `RoadSheetWrapper` class
const formData = {
  language: 'en-GB',
  startDate: Date.now(),
  disabledManeuvers: ['merge', 'continue'],
  primaryMentions: ['road_sign', 'toll_collection'],
  maxSecondaryMentions: 0,
};

sdk.Roadsheet.setFormData(formData);

By setting these options, developers can generate a roadsheet tailored to the specific needs and preferences of their application's users.

The RoadSheetWrapper exposes the @mappingfactory/roadsheet members : client: The Roadsheet Client icons: The Roadsheet Icons utils: The Roadsheet Utils static class You can access them directly from the MichelinSDKClient instance : sdk.Roadsheet.client, sdk.Roadsheet.icons, sdk.Roadsheet.utils

MapLibre API

The Michelin MapLibre API offers developers the ability to integrate powerful map visualization capabilities into their applications. Using the MapLibreWrapper class, one can seamlessly embed maps by leveraging the MapLibre GL library without the overhead of manual integrations.

Setting up the MapLibreWrapper

To employ the MapLibreWrapper through the MichelinSDKClient, you'll want to invoke the loadMapLibreLibrary function. This function spawns an instance of the MapLibreWrapper class and bestows you with the MapLibre Client designed for rendering and controlling map views:

// Replace 'YOUR_API_KEY' with your actual Michelin API key
const apiKey = 'YOUR_API_KEY';

const sdk = new MichelinSDKClient({ apiKey });

// Kickstart the `MapLibreWrapper` class and retrieve the MapLibre Client once the promise is resolved
const mapLibreClient = await sdk.loadMapLibreLibrary();

// You can now directly interface with the `MapLibreWrapper` through the MichelinSDKClient instance
const maplibre = sdk.MapLibre;

Note: This integration utilizes MapLibre, an open-source mapping library. If you're familiar with MapLibre, you can use it as usual within this context. For comprehensive details or if you're new to MapLibre, consult their official documentation here.

License

Licensed under the MIT License.