@mappingfactory/sdk-js

<h1 align="center"> @mappingfactory/sdk-js </h1> 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](#development-environment-setup) - [Installation](#installation) - [Search](#search) - [Direction API](#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: ```shell 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: ```shell 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. ```shell 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: ```html <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: ```js 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: ```js 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: ```js 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: ```javascript // 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? | <kbd>Optional</kbd> 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: ```javascript 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? | <kbd>Optional</kbd> 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? | <kbd>Optional</kbd> 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[]? | <kbd>Optional</kbd> 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? | <kbd>Optional</kbd> Default : `5` | Code example `search.geocoding({ address: "1 rue de la paix", limit:10 })` | `?address=1%20rue%20de%20la%20paix&limit=10` | | bounds | object? | <kbd>Optional</kbd> 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? | <kbd>Optional</kbd> 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: ```javascript 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: ```javascript ... // 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 : ```javascript // 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: ```javascript // 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: ```javascript // 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 | | --------------------------------------- |