@mappingfactory/sdk-js
TypeScript icon, indicating that this package has built-in type declarations

1.0.5 • Public • Published

@mappingfactory/sdk-js

Advanced SDK for Michelin's Navigation and Mapping Services.

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

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:

```shell
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

Name Type Description
apiKey string Your Michelin API key
locale string? Optional
Default : en-US

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

Name Type Description API Query API Query
address string URL-encoded free formed text containing the address to geocode. Code example
search.geocoding({ address: "1 rue de la paix" }) column
?address=1%20rue%20de%20la%20paix
filter string? Optional
List of filters applied to restrict the search to certain parameters, separated by semicolons.
Code example
search.geocoding({ address: "1 rue de la paix", filter: "country:BE,NL,LU" })
Note
Actually only country filter is available, but this feature will be implemented to allow future filters.
No check will be done on key/value.
?address=1%20rue%20de%20la%20paix&filter=country:BE,NL,LU
language string? Optional
Default : en-US
Code example
search.geocoding({ address: "1 rue de la paix", language: "en-US" })
?address=1%20rue%20de%20la%20paix&language=en-US
countries string[]? Optional
This parameter is used to prioritize a list of countries on the search.
Code example
search.geocoding({ address: "1 rue de la paix", countries:["BE", "NL", "LU"] })
?address=1%20rue%20de%20la%20paix&filter=country:BE,NL,LU
limit string|number? Optional
Default : 5
Code example
search.geocoding({ address: "1 rue de la paix", limit:10 })
?address=1%20rue%20de%20la%20paix&limit=10
bounds object? Optional
Contains :
sw_corner - object
ne_corner - object
Code example
search.geocoding({ address: "1 rue de la paix", bounds: { sw_corner: { latitude: 37.7749, longitude: -122.4194 }, ne_corner: { latitude: 37.7888, longitude: -122.3991 } } })
Note
proximity parameter and bounds parameter are mutually exclusive. proximity parameter takes precedence when both are passed.
?address=1%20rue%20de%20la%20paix&bounds=37.7749,-122.4194;37.7888,-122.3991
proximity object? Optional
Contains :
latitude - number
longitude - number
Code example
search.geocoding({ address: "1 rue de la paix", proximity: { latitude: 37.7749, longitude: -122.4194 } })
Note
proximity parameter and bounds parameter are mutually exclusive. proximity parameter takes precedence when both are passed.
?address=1%20rue%20de%20la%20paix&proximiy=37.7749,-122.4194

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

Event Name Description Parameters (callbacks)
opened Triggered when the list of suggestions is displayed. None.
closed Triggered when the list of suggestions is closed. None.
clear Triggered when when the search input is emptied by the user None.
search Triggered when a query is sent for results. data (Object): The query object
noResults Triggered if no suggestion is proposed after the input entry. None.
selected Triggered when a suggestion is selected by the user. data (Object): The result object
success Triggered when the results have been fetched. data (Object[]): An array of data
error Triggered when an error occurs when making the request. error (Error): The error object

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

Name Type Description API Call Configuration
input Object This parameter allows you to specify options for the input field.
input.id (optional) string Id to use for the input (default: msdk-input)
input.name (optional) string Name to use for the input (default: msdk-input-name)
input.class (optional) string Class to use for the input (default: michelin-search__autocomplete-input)
input.classNames (optional) string Additional class names to use for the input (default: ``)
input.placeholder (optional) string Placeholder to use for the input (default: ``)
input.autoComplete (optional) boolean Whether or not to automatically fill the input with the selected result (default: false)
Search Parameters Object
countries string[] It is used to specify a list of countries for the search field. Its values have to be a list of codes based upon the ISO 3166-1 alpha-2 format like. Validation: Ensure that the country code is correct. filter=country:BE,NL,LU
include_poi boolean If this parameter is true, API will search for both addresses and POI. The results may or may not contain the POIs basing on the query. If the value is false, it will only search for addresses. Default value: true include_poi=true
language string The language to be used for result. Example: language=en-GB. Validation: Ensure that the language code is correct. LANGUAGE={parameters.language}
limit number The maximum number of result items to be included in the response. Default value: 5 limit=2
bounds object? Optional Contains: sw_corner - object ne_corner - object Allow to restrict the results within the given geographic bounding box represented by southwest and northeast corners. It is an object with two properties: sw_corner (South West Corner) and ne_corner (North East Corner). Note: proximity parameter and bounds parameter are mutually exclusive. proximity parameter takes precedence when both are passed. Based on the code example in the description column ?address=1%20rue%20de%20la%20paix&bounds=37.7749,-122.4194; 37.7888,-122.3991
proximity object? Optional Contains: latitude - number longitude - number Allow to favour the closest results to the given geographical coordinates. The use of this parameter is recommended as it provides more accurate results. Note: proximity parameter and bounds parameter are mutually exclusive. proximity parameter takes precedence when both are passed. Based on the code example in the description column ?address=1%20rue%20de%20la%20paix&proximiy=37.7749,-122.4194
autofill boolean Enable or disable browser autofill functionality. Default: False
debounce number Responsible for setting delay time duration that counts after typing is done for the request to start. This attribute will set the fire rate limit (in milliseconds) on the keyup event callback. Default: 300
threshold number Responsible for setting the threshold value of the minimum character length where the request can start. Default: 3
dropdown Responsible for the results list element rendering, interception, and customizing
dropdown.tag (optional) string Default: ul dropdown: { tag: 'ul', id: 'msdk-dropdown', class: 'michelin-search__autocomplete-dropdown', classNames: '', noResultsOpen: true, position: 'bottom', }
dropdown.id (optional) string Default: msdk-dropdown
dropdown.class (optional) string Default: michelin-search__autocomplete-dropdown
dropdown.position (optional) string Default: bottom
dropdown.classNames (optional) string A list of class names that will be added on top of the .class
dropdown.allowTab (optional) boolean Default: true
dropdown.noResultsOpen (optional) boolean Default: false
dropdownItem (optional) Responsible for the result item element rendering, interception, and customizing
dropdownItem.tag (optional) string Default: li dropdownItem: { tag: 'li', id: 'msdk-dropdown-item', class: 'michelin-search__autocomplete-dropdown-item', classNames: '', highlight: true, }
dropdownItem.id (optional) string Default: msdk-dropdown-item
dropdownItem.classNames (optional) string A list of class names that will be added on top of the .class
dropdownItem.class (optional) string Default: michelin-search__autocomplete-dropdown-item
dropdownItem.highlight (optional) boolean Default: true
dropdownItem.highlightTag (optional) string Default: mark
dropdownItem.highlightClass (optional) string Default: michelin-search__autocomplete-dropdown-item--highlight
dropdownItem.truncateDetails (optional) boolean Default: true

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

Name Type Description Mandatory Allowed Values
currency string The currency for cost-related information. Optional Any valid currency code (e.g., "USD", "EUR", "GBP")
unit string The unit of measurement. Optional "m" (meters), "km" (kilometers), "mi" (miles), "ft" (feet)
vehicleType string The type of vehicle. Optional Any valid vehicle type
annotations string Allows to specify which metadata to have in the result. Only for "truck" mode. Optional Any valid value in ('maxspeed', 'congestion', 'duration')
vehicleCommercial string The commercial name of the vehicle. Optional Any valid commercial name
url string The URL for the API request. Optional Any valid URL
http_request_method string The HTTP request method. Optional "GET", "POST", "PUT", "DELETE"
alternatives boolean Indicates if alternative routes should be included. Optional true, false
avoid string Specifies features to avoid along the route. Optional Any feature to avoid
car_type string The type of car for the route. Optional Any valid car type
coordinates array The coordinates for the waypoints. Mandatory Array of valid coordinates
electricity_consumptions_per_hundred_km string Electricity consumption per 100 km. Optional Any valid electricity consumption value
electricity_cost number The cost of electricity per unit. Optional Any valid cost value
fuel_consumptions_per_hundred_km string Fuel consumption per 100 km. Optional Any valid fuel consumption value
fuel_cost number The cost of fuel per unit. Optional Any valid cost value
fuel_type string The type of fuel for the vehicle. Optional Any valid fuel type
geometries string The type of geometries for the route. Optional "polyline", "geojson", "encodedpolyline"
language string The language for route instructions. Optional Any valid language code (e.g., "en", "fr", "es")
mentions string Additional mentions for the route. Optional Any additional mention
mode string The mode of transportation. Optional Any valid mode of transportation
motorization string The motorization of the vehicle. Optional Any valid motorization type
overview string The type of overview for the route. Optional "simplified", "full", "false"
pois_corridor_options string POI corridor options for the route. Optional Any valid POI corridor option
steps boolean Indicates if steps should be included in the route. Optional true, false
traffic string The type of traffic data to consider. Optional Any valid traffic type
type string The type of the route. Optional Any valid route type
vehicle_adr_tunnel_restriction_code string ADR tunnel restriction code. Optional Any valid ADR tunnel restriction code
vehicle_axle_weight string The axle weight of the vehicle. Optional Any valid axle weight value
vehicle_commercial string The commercial type of the vehicle. Optional Any valid commercial type
vehicle_height string The height of the vehicle. Optional Any valid height value
vehicle_length string The length of the vehicle. Optional Any valid length value
vehicle_load_type string The load type of the vehicle. Optional Any valid load type
vehicle_max_speed string The maximum speed of the vehicle. Optional Any valid maximum speed value
vehicle_type string The type of the vehicle. Optional Any valid vehicle type
vehicle_weight string The weight of the vehicle. Optional Any valid weight value
vehicle_width string The width of the vehicle. Optional Any valid width value
waypoints array The waypoints for the route. Optional Array of valid waypoints

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.

Package Sidebar

Install

npm i @mappingfactory/sdk-js

Weekly Downloads

0

Version

1.0.5

License

MIT

Unpacked Size

966 kB

Total Files

9

Last publish

Collaborators

  • siddharthvitthaldas
  • ketannaravane
  • ksahay
  • michelinmappingfactory