npm package: @mappingfactory/directions
Description: Michelin direction for JavaScript is a library to fetch routes from the Michelin routing API
Author: Michelin
Latest version: 3.3.0

# Michelin Directions Javascript API Client
### Michelin directions for JavaScript is a library to fetch routes from the Michelin routing API

## ✨ Features

- Thin & **minimal low-level HTTP client** to interact with Michelin's API
- Works both on the **browser** and **node.js**
- **UMD compatible**, you can use it with any module loader
- Built with Vanilla JavaScript without dependency

## 💡 Getting Started

First, install Michelin Directions JavaScript API Client via the [npm](https://www.npmjs.com/get-npm) package manager:

```bash
npm install @mappingfactory/directions
```

Then, initialise your client and use it.

```js
const michelinDirections = require("@mappingfactory/directions"); // ES-5
// or 
import michelinDirections from '@mappingfactory/directions'; // ES-6

const clientMd = michelinDirections("YourMichelinAPIKey");

const departure = {latitude: 48.82801, longitude: 2.235235};
const arrive = {latitude: 48.83379, longitude: 2.2433};
clientMd.setCoordinates(departure, arrive);

clientMd
  .search()
  .then(response => {
    console.log(response);
  })
  .catch(error => {
    console.log(error.json());
  });
```

You can use use the dist version if you want to use @michelin/directions with html for a browser usage: 

```html
<script type="text/javascript" src="./dist/michelin-directions.js"></script>
<script>
  const clientMd = michelinDirections("YourMichelinAPIKey");
  ...
</script>
```

## 🔧 Importable Methods 

- `michelinDirections([string] API_KEY)` return a new michelinDirections client.

## 🪄 Client Methods

Common methods you may want to use include:


### search()

**Description:**

Search directions using specified coordinates and other specified parameters

**Return:** 

A `Promise`
See [More informations](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)

**Example usage:**
```js
const departure = {latitude: 48.82801, longitude: 2.235235};
const arrive = {latitude: 48.83379, longitude: 2.2433};
clientMd.setCoordinates(departure, arrive);

clientMd
  .search()
  .then(response => {
    console.log(response);
  })
  .catch(error => {
    console.log(error.json());
  });
```

#### Error

`search()` can throw an `Error` which will be caught in `catch(error => {})`

**Error instance properties:**
- `message`: Error message.
- `code`: Error code.
- `status`: Error status.

**Error instance methods:**
- `json()`: Return instance as `json`.

**Error json() response example:**
```json
{
  code: "NoSegment",
  status: 400,
  message: "Bad Request error. NoSegment (lat=48.82801 lon=2.235235)."
}
```


## ⚙️ Client Options

Common options you may want to specify include:

| Name | Type | Description | Default value |
| --- | --- | --- | --- |
| `api_key` | `string` | Your required Michelin API key. | |
| `api_url` | `string` | The Michelin API used base url. | `"https://api.michelin.com"` |
| `http_request_method` | `string` - `enum` | HTTP request method used by client.<br><br>**Value can be:**<br> - `"POST"`<br> - `"GET"` | `"GET"` |


To update them, please use:

```js
clientMd.setOption('option_name', 'option_value');

// example: 
clientMd.setOption('api_key', 'AnotherMichelinAPIKey'); // Update api_key
clientMd.setOption('http_request_method', 'POST'); // http request method
``` 

## ⚙️ Client's formData  and important methods

⚠️ Assuming that there is a form implemented to capture the form data we can use the following methods.

- `getFormData()` - return the client's formData object
**Example usage:**
```js
 /**
   * Get formData (without null values)
   * @param {Object} fd
   * @returns {Object}
   */
  getFormData (fd) {
    fd = (typeof fd !== 'undefined') ? fd : this.formData
    const ret = Object.assign({}, fd)
    for (const [key, value] of Object.entries(ret)) {
      if (value === null) {
        delete ret[key]
      }
    }
    return ret
  }
```

- `setFormData({Object})` - sets Form Data works with the getFormData Method mentioned above
**Example Usage**
```js
//The formattedRequest would look like the JSON below
{
"alternatives": "false",
"car_type":"compact", 
"coordinates": "4.612244,51.76717;2.340014,49.159454;2.61367,49.164032",
"currency": "EUR",
"geometries": "polyline",
"language": "polyline",
"mentions": "all",
"mode": "car",
"motorization": "fuel",
"overview": "simplified"
}

        clientMd.setFormData(formattedRequest);
        clientMd
            .search()
            .then(responseData => {
            })
            .catch(error => {
            });
        e.preventDefault();
    });
```
- `setOption([string] key, [*] value)` - update client's option for a specific key
**Example usage:**
```js
  /**
   * Set option
   * @param {string} name
   * @param {any} val
   */
  setOption (name, val) {
    if (Object.prototype.hasOwnProperty.call(this.opts, name)) {
      this.opts[name] = val
    }
  }
```
- `getOptions()` - return the client's options object
- `getRequestUrl()` - return the client's http request url (for debug purposes)
**Example Usage**
```js
/**
   * Get request url
   * @param {Object} fd
   * @returns string
   */
  getRequestUrl (fd) {

  }
```
- `getRequestOptions()` - return the client's http request options (for debug purposes)
**Example Usage**
```js
getRequestOptions (fd) {
  reqOpts.body = body
  return reqOpts
}
```

## ⚙️ Sample Request Parameters
```js
{
"alternatives": "false",
"annotations":"",
"avoid": "",
"bearings": "",
"car_type":"compact", 
"continue_straight": "",
"coordinates": "4.612244,51.76717;2.340014,49.159454;2.61367,49.164032",
"currency": "EUR",
"electricity_consumptions_per_hundred_km": "",
"electricity_cost": "",
"fuel_consumptions_per_hundred_km": "",
"fuel_cost": "",
"fuel_type": ""'
"geometries": "polyline",
"language": "polyline",
"mentions": "all",
"mode": "car",
"motorization": "fuel",
"overview": "simplified",
"pois_corridor_options": "",
"radiuses": "",
"steps": "false",
"traffic": "ignore",
"type": "recommended",
"unit": "EUR",
"vehicle_adr_tunnel_restriction_code": "",
"vehicle_axle_weight": "",
"vehicle_commercial": "",
"vehicle_height": "",
"vehicle_length": "",
vehicle_load_type
"vehicle_max_speed": "",
"vehicle_type": "2",
"vehicle_weight": "",
"vehicle_width": "",
"waypoints": [
{
"name": "Rue de la Haye Gonore",
"town": "",
"country": "FRA",
"location": [
1.1348937,
49.5315046
],
"distance": 0
},
{
"name": "La Route du Blé en Beauce",
"town": "",
"country": "FRA",
"location": [
1.4780724,
47.8937003
],
"distance": 0
}
]
}
 
```
**Note:** Please review the Open API documentation for the updated request data.


## ⚙️ Sample Response Data 
```js{
"routes": [
{
"duration": 10600.8,
"distance": 215000.6,
"weight": 10600,
"weight_name": "duration",
"geometry": "{bimHat|ET`BHbABVBb@@^An@C`AEp@AdG",
"legs": [1 item],
"summary": "N154, N10",
"traffic_impact_duration": 0,
"highway_duration": 3983.8,
"highway_traffic_impact_duration": 0,
"highway_distance": 99054.5,
"type": "recommended",
"mentions": [156 items],
"route_identifier": "eyd2ZXJzaW9uJzogJ3VuaXF1ZV9kYXRhX3NldCcsICdyb3V0ZV9wYXRoJzogW3sncG9zaXRpb25fb25fZmlyc3Rfd2F9",
"toll_cost": [
{
"category": 1,
"unit": "EUR",
"value": 1.3
},
{
"category": 7,
"unit": "EUR",
"value": 6.8
}
],
"unit": "EUR",
"total_toll_cost": 2.2
}
],
"waypoints": [
{
"name": "Rue de la Haye Gonore",
"town": "",
"country": "FRA",
"location": [
1.1348937,
49.5315046
],
"distance": 0
},
{
"name": "La Route du Blé en Beauce",
"town": "",
"country": "FRA",
"location": [
1.4780724,
47.8937003
],
"distance": 0
}
],
"poi_descriptions": [
{
"name": "Hostellerie du Bois-Guibert",
"poi_id": "f8b768fb",
"poi_location": [
1.36694,
48.16867
],
"type": "accommodation"
},
{
"name": "B&B HOTEL Rouen Saint-Étienne-du-Rouvray",
"poi_id": "yueliq3w",
"poi_location": [
1.11205,
49.369
],
"type": "accommodation"
},
{
"name": "Kyriad Evreux - Netreville",
"poi_id": "cs1tvw4r",
"poi_location": [
1.18638,
49.03023
],
"type": "accommodation"
}
],
"code": "Ok",
"uuid": "21463e76-f6e1-459d-97f6-c689f0149c87"
}
```
**Note:** Please review the Open API documentation for the updated response data.


Then each parameters below have their own setter.

## 🧷 Client's formData parameters

**Note:** Below parameters are specified for the Michelin API 1.0.
You can find the [up to date API contract here](https://gitlab.com/michelinida/mapping-squad/internal-tools/openapi-spec-mapping-services/-/blob/master/external/omniroute.yaml).

**Warning:** Every parameters are optional except for `coordinate`.

---
### coordinates - <span style="color:#DC143C; font-size: 18px;">Required</span>

**Description:**

List of the waypoints of the route.

**Setter:**
```js
/**
 * Set coordinates
 * @param  {...{latitude: float, longitude: float}} coordinates
 */
setCoordinates (...coordinates) {
  //...
}
```

**Example usage:**
```js
const departure = {latitude: 48.82801, longitude: 2.235235};
const arrive = {latitude: 48.83379, longitude: 2.2433};
clientMd.setCoordinates(departure, arrive);
// setCoordinates  can take an infinite number of parameters
```
---
### waypoints

**Description:**

List of waypoints indicating which input coordinates should be treated as waypoints.
Each item in the list must be the zero-based index of an input coordinate, and the list must include 0 (the index of the first coordinate) and the index of the last coordinate.
The waypoints parameter can be used to guide the path of the route without introducing additional legs and arrive/depart instructions.

**Setter:**
```js
/**
 * Set waypoints
 * @param  {null|...int} waypoints
 */
setWaypoints (...waypoints) {
  //...
}
```

**Example usage:**
```js
clientMd.setWaypoints(0, 2);
// setWaypoints can take an infinite number of parameters but must have the same amount of parameters as the coordinates
```
---
### type - <span style="color:#2E8B57; font-size: 18px;">Recommended</span>

**Default value:** `"fastest"`

**Description:**

Optimization type to be used for the calculation of the route.
Available values for car mode: `"shortest"`, `"recommended"` and `"fastest"` (default value).
Available values for truck mode: `"shortest"`, `"fastest"` (default value) and `"eco"`.

⚠️ `"shortest"` value may not be implemented.

**Setter:**
```js
/**
 * Set type
 * @param {null|string|TYPE_ENUM} type
 */
setType (type) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {TYPE_ENUM}
 */
TYPE_ENUM = {
  shortest: 'shortest',
  recommended: 'recommended',
  fastest: 'fastest',
  economic: 'economic',
  quickest: 'quickest' 
}
```

**Example usage:**
```js
clientMd.setType(clientMd.TYPE_ENUM.recommended);
```
---
### mode

**Default value:** `"car"`

**Description:**

Travel mode to be used for the calculation of the route.

⚠️ `"motorcycle"`, `"bicycle"` and `"pedestrian"` values may not be implemented

**Setter:**
```js
/**
 * Set mode
 * @param {null|string|MODE_ENUM} mode
 */
setMode (mode) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {MODE_ENUM}
 */
MODE_ENUM = {
  motorcycle: 'motorcycle',
  car: 'car',
  truck: 'truck',
  bicycle: 'bicycle',
  pedestrian: 'pedestrian'
}
```

**Example usage:**
```js
clientMd.setMode(clientMd.MODE_ENUM.truck);
```
---
### geometries

**Default value:** `"polyline"`

**Description:**

The format of the returned geometry.

**Setter:**
```js
/**
 * Set geometries
 * @param {null|string|GEOMETRIES_ENUM} geometries
 */
setGeometries (geometries) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {GEOMETRIES_ENUM}
 */
GEOMETRIES_ENUM = {
  polyline: 'polyline',
  polyline6: 'polyline6',
  geojson: 'geojson'
}
```

**Example usage:**
```js
clientMd.setGeometries(clientMd.GEOMETRIES_ENUM.geojson);
```
---
### overview

**Default value:** `"simplified"`

**Description:**

Displays the requested type of overview geometry.

**Setter:**
```js
/**
 * Set overview
 * @param {null|string|OVERVIEW_ENUM} overview
 */
setOverview (overview) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {OVERVIEW_ENUM}
 */
OVERVIEW_ENUM = {
  full: 'full', // (the most detailed geometry available)
  simplified: 'simplified', // (default, a simplified version of the full geometry),
  none: 'none', // (no overview geometry).
  false: 'false' // For compatibility false may be used instead of none
}
```

**Example usage:**
```js
clientMd.setOverview(clientMd.OVERVIEW_ENUM.full);
```
---
### radiuses

**Description:**

The maximum distance a coordinate can be moved to snap to the road network in meters.
There must be as many radiuses as there are locations in the request.
Values can be any number greater than 0 or the string unlimited.
A NoSegment error is returned if no routable road is found within the radius.

**Setter:**
```js
/**
 * Set radiuses
 * @param  {null|...float} radiuses
 */
setRadiuses (...radiuses) {
  //...
}
```

**Example usage:**
```js
clientMd.setRadiuses(4000,4000);
// setRadiuses can take an infinite number of parameters but must have the same amount of parameters as the coordinates
```
---
### steps

**Default value:** `false`

**Description:**

Whether to return steps and turn-by-turn instructions

**Setter:**
```js
/**
 * Set steps
 * @param {null|boolean} steps
 */
setSteps (steps) {
  //...
}
```

**Example usage:**
```js
clientMd.setSteps(true);
```
---
### language

**Default value:** `"en-GB"`

**Description:**

The language to be used for result rendering.

**Setter:**
```js
/**
 * Set language
 * @param {null|string|LANGUAGE_ENUM} language
 */
setLanguage (language) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {LANGUAGE_ENUM}
 */
LANGUAGE_ENUM = {
  af_ZA: 'af-ZA',
  ar: 'ar',
  bg_BG: 'bg-BG',
  zh_TW: 'zh-TW',
  cs_CZ: 'cs-CZ',
  da_DK: 'da-DK',
  nl_NL: 'nl-NL',
  en_GB: 'en-GB',
  en_US: 'en-US',
  fi_FI: 'fi-FI',
  fr_FR: 'fr-FR',
  de_DE: 'de-DE',
  el_GR: 'el-GR',
  hu_HU: 'hu-HU',
  id_ID: 'id-ID',
  it_IT: 'it-IT',
  ko_KR: 'ko-KR',
  lt_LT: 'lt-LT',
  ms_MY: 'ms-MY',
  nb_NO: 'nb-NO',
  pl_PL: 'pl-PL',
  pt_BR: 'pt-BR',
  pt_PT: 'pt-PT',
  ru_RU: 'ru-RU',
  sk_SK: 'sk-SK',
  sl_SI: 'sl-SI',
  es_ES: 'es-ES',
  es_MX: 'es-MX',
  sv_SE: 'sv-SE',
  th_TH: 'th-TH',
  tr_TR: 'tr-TR'
}
```

**Example usage:**
```js
clientMd.setLanguage(clientMd.LANGUAGE_ENUM.fr_FR);
```
---
### mentions

**Default value:** `"main"`

**Description:**

Level of mentions to return.

**Setter:**
```js
/**
 * Set mentions
 * @param {null|string|MENTIONS_ENUM} mentions
 */
setMentions (mentions) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {MENTIONS_ENUM}
 */
MENTIONS_ENUM = {
  main: 'main',
  all: 'all'
}
```

**Example usage:**
```js
clientMd.setMentions(clientMd.MENTIONS_ENUM.all);
```
---
### alternatives

**Default value:** `false`

**Description:**

Whether to try to return alternative routes (true) or not (false).

**Setter:**
```js
/**
 * Set alternatives
 * @param {null|boolean} alternatives
 */
setAlternatives (alternatives) {
  //...
}
```

**Example usage:**
```js
clientMd.setAlternatives(true);
```
---
### bearings

**Description:**

Influences the direction in which a route starts from a waypoint.
Takes two comma-separated values per waypoint.
First value is an angle clockwise from true north between 0 and 360.
Second value is the range of degrees by which the angle can deviate (recommended value is 45° or 90°).

 ⚠️ If you are using `bearing` combinated with `radiuses`, make sure than `radiuses` is greater than 9 meters

**Setter:**
```js
/**
 * Set bearings
 * @param  {...{angle: integer, range: integer}} bearings
 */
setBearings (...bearings) {
  //...
}
```

**Example usage:**
```js
clientMd.setBearings({angle: 185, range: 45}, {angle: 350, range: 45});
// setBearings can take an infinite number of parameters but must have the same amount of parameters as the coordinates

```
---
### continue_straight

**Default value:** `true`

**Description:**

Sets the allowed direction of travel when departing intermediate waypoints.
If `true`, the route will continue in the same direction of travel.
If `false`, the route may continue in the opposite direction of travel.

**Setter:**
```js
/**
 * Set continue_straight
 * @param {null|boolean} continueStraight
 */
setContinueStraight (continueStraight) {
  //...
}
```

**Example usage:**
```js
clientMd.setContinueStraight(true);
```
---

### traffic

**Description:**

Consider or ignore traffic data during routing.

**Setter:**
```js
/**
 * Set traffic
 * @param {null|TRAFFIC_ENUM} traffic
 */
setTraffic (traffic) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {TRAFFIC_ENUM}
 */
TRAFFIC_ENUM = {
  // Consider all available traffic information during routing (closings and slowdowns)
  all: 'all',
  // Consider only traffic closings information during routing
  closings: 'closings',
  // Ignore current traffic data during routing
  ignore: 'ignore',
  // Consider truck-related traffic data during routing.
  enable_for_trucks: 'enable_for_trucks',
}
```

**Example usage:**
```js
clientMd.setTraffic('all');
```
---

### avoid

**Description:**

List of things to avoid when calculating a route.
*Only for truck mode*

**Setter:**
```js
/**
 * Set avoid
 * @param {null|string|AVOID_ENUM} avoid
 */
setAvoid (avoid) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {AVOID_ENUM}
 */
AVOID_ENUM = {
  tollroads: 'tollroads',
  motorways: 'motorways',
  ferries: 'ferries',
  unpavedroads: 'unpavedroads',
  bordercrossings: 'bordercrossings',
  motorways_bordercrossings: 'motorways_bordercrossings',
  low_emission_zones: 'low_emission_zones',
  tollgates_tollvignettes: 'tollgates_tollvignettes'
}
```

**Example usage:**
```js
clientMd.setAvoid(clientMd.AVOID_ENUM.motorways);
```
---
### motorization

**Default value:** `"fuel"`

**Description:**

The type of motor of the vehicle.
For Car : `"fuel"`, `"electric"`, `"fuel_cell"`, `"hybrid"`.
For Truck: `"fuel"`, `"electric"`.

**Setter:**
```js
/**
 * Set motorization
 * @param {string|MOTORIZATION_ENUM} motorization
 */
setMotorization (motorization) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {MOTORIZATION_ENUM}
 */
MOTORIZATION_ENUM = {
  fuel: 'fuel',
  electric: 'electric',
  fuel_cell: 'fuel_cell',
  hybrid: 'hybrid'
}
```

**Example usage:**
```js
clientMd.setMotorization(clientMd.MOTORIZATION_ENUM.hybrid);
```
---
### fuel_type

**Description:**

Fuel energy source.
It is used in conjunction with `car_type` parameter to estimate the fuel consumption in liters and the carbon dioxide emissions in kilograms.
It is used in conjunction with `fuel_consumptions_per_hundred_km` parameter value to estimate the carbon dioxide emissions in kilograms.

**Setter:**
```js
/**
 * Set fuel_type
 * @param {string|FUEL_TYPE_ENUM} fuelType
 */
setFuelType (fuelType) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {FUEL_TYPE_ENUM}
 */
FUEL_TYPE_ENUM = {
  gasoline: 'gasoline',
  diesel: 'diesel',
  e85: 'e85',
  lpg: 'lpg',
  ngv: 'ngv',
  h2: 'h2'
}
```

**Example usage:**
```js
clientMd.setFuelType(clientMd.FUEL_TYPE_ENUM.h2);
```
---
### car_type

**Description:**

Type of car for `"car"` `mode`.
It is used in conjunction with `fuel_type` parameter to estimate the fuel consumption in liters and the carbon dioxide emissions in kg.
It is ignored when `fuel_consumptions_per_hundred_km` parameter is specified.

**Setter:**
```js
/**
 * Set car_type
 * @param {null|string|CAR_TYPE_ENUM} carType
 */
setCarType (carType) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {CAR_TYPE_ENUM}
 */
CAR_TYPE_ENUM = {
  hatchback: 'hatchback',
  compact: 'compact',
  family: 'family',
  sedan: 'sedan',
  luxury: 'luxury'
}
```

**Example usage:**
```js
clientMd.setCarType(clientMd.CAR_TYPE_ENUM.luxury);
```
---
### fuel_consumptions_per_hundred_km

**Description:**

Fuel consumption in `urban`, `rural` and `highway` driving conditions.
It is used to estimate the fuel consumption in liters.
It is used in conjunction with `fuel_type` parameter to estimate the carbon dioxide emissions in kilograms.*Only for fuel vehicle engine*

**Setter:**
```js
/**
 * Set fuel_consumptions_per_hundred_km
 * @param {null|float} urban
 * @param {null|float} rural
 * @param {null|float} highway
 */
setFuelConsumptionsPerHundredKm (urban, rural, highway) {
  //...
}
```

**Example usage:**
```js
clientMd.setFuelConsumptionsPerHundredKm(1.2,1.5,1);
```
---
### fuel_cost

**Description:**

Cost of energy source in euros per liter (gasoline, diesel, E85 and LPG) or in euros per kilograms (NGV and H2).
*Only for fuel vehicle engine*

**Setter:**
```js
/**
 * Set fuel_cost
 * @param {null|float} fuelCost
 */
setFuelCost (fuelCost) {
  //...
}
```

**Example usage:**
```js
clientMd.setFuelCost(1.2);
```
---
### electricity_consumptions_per_hundred_km

**Description:**

Electricity consumption in `urban`, `rural` and `highway` driving conditions.
It is used to estimate the electricity consumption in kwh.
*Only for electric vehicle engine*

**Setter:**
```js
/**
 * Set electricity_consumptions_per_hundred_km
 * @param {null|float} urban
 * @param {null|float} rural
 * @param {null|float} highway
 */
setElectricityConsumptionsPerHundredKm (urban, rural, highway) {
  //...
}
```

**Example usage:**
```js
clientMd.setElectricityConsumptionsPerHundredKm(1.2,1.5,1);
```
---
### electricity_cost

**Description:**

Cost of energy source in euros per kwh.
*Only for electric vehicle engine*

**Setter:**
```js
/**
 * Set electricity_cost
 * @param {null|float} electricCost
 */
setElectricityCost (electricCost) {
  //...
}
```

**Example usage:**
```js
clientMd.setElectricityCost(1.2);
```
---
### vehicle_max_speed 

**Description:**

Maximum speed of the vehicle in kilometers per hour.
*Only for `"truck"` `mode`*

**Setter:**
```js
/**
 * Set vehicle_max_speed
 * @param {null|integer} vehicleMaxSpeed
 */
setVehicleMaxSpeed (vehicleMaxSpeed) {
  //...
}
```

**Example usage:**
```js
clientMd.setVehicleMaxSpeed(200);
```
---
### vehicle_weight

**Default value:** `0`

**Description:**

Weight of the vehicle in kilograms.
*Only for `"truck"` `mode`*

**Setter:**
```js
/**
 * Set vehicle_weight
 * @param {null|integer} vehicleWeight
 */
setVehicleWeight (vehicleWeight) {
  //...
}
```

**Example usage:**
```js
clientMd.setVehicleWeight(500);
```
---
### vehicle_axle_weight

**Default value:** `0`

**Description:**

Weight per axle of the vehicle in kilograms.
*Only for `"truck"` `mode`*
**Note:** A value of `0` means that weight restrictions per axle are not considered.

**Setter:**
```js
/**
 * Set vehicle_axle_weight
 * @param {null|integer} vehicleAxleWeight
 */
setVehicleAxleWeight (vehicleAxleWeight) {
  //...
}
```

**Example usage:**
```js
clientMd.setVehicleAxleWeight(250);
```
---
### vehicle_length

**Default value:** `0`

**Description:**

Length of the vehicle in meters.
*Only for `"truck"` `mode`*
**Note:** A value of `0` means that length restrictions are not considered.

**Setter:**
```js
/**
 * Set vehicle_length
 * @param {null|float} vehicleLength
 */
setVehicleLength (vehicleLength) {
  //...
}
```

**Example usage:**
```js
clientMd.setVehicleLength(4.228);
```
---
### vehicle_width

**Default value:** `0`

**Description:**

Width of the vehicle in meters.
*Only for `"truck"` `mode`*
**Note:** A value of `0` means that width restrictions are not considered.

**Setter:**
```js
/**
 * Set vehicle_width
 * @param {null|float} vehicleWidth
 */
setVehicleWidth (vehicleWidth) {
  //...
}
```

**Example usage:**
```js
clientMd.setVehicleWidth(1.720);
```
---
### vehicle_height

**Default value:** `0`

**Description:**

Height of the vehicle in meters.
*Only for `"truck"` `mode`*
**Note:** A value of `0` means that height restrictions are not considered.

**Setter:**
```js
/**
 * Set vehicle_height
 * @param {null|float} vehicleHeight
 */
setVehicleHeight (vehicleHeight) {
  //...
}
```

**Example usage:**
```js
clientMd.setVehicleHeight(1.497);
```
---
### vehicle_commercial

**Default value:** `false`

**Description:**

Vehicle is used for commercial purposes and thus may not be allowed to drive on some roads.
*Only for `"truck"` `mode`*

**Setter:**
```js
/**
 * Set vehicle_commercial
 * @param {null|boolean} vehicleCommercial
 */
setVehicleCommercial (vehicleCommercial) {
  //...
}
```

**Example usage:**
```js
clientMd.setVehicleCommercial(true);
```
---
### vehicle_load_type

**Description:**

Types of cargo that may be classified as hazardous materials and restricted from some roads.
*Only for `"truck"` `mode`*

**Setter:**
```js
/**
 * Set vehicle_load_type
 * @param {null|string|VEHICLE_LOAD_TYPE_ENUM} vehicleLoadType
 */
setVehicleLoadType (vehicleLoadType) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {VEHICLE_LOAD_TYPE_ENUM}
 */
VEHICLE_LOAD_TYPE_ENUM = {
  USHazmatClass1: 'USHazmatClass1', // (Explosives)
  USHazmatClass2: 'USHazmatClass2', // (Compressed Gas)
  USHazmatClass3: 'USHazmatClass3', // (Flammable Liquids)
  USHazmatClass4: 'USHazmatClass4', // (Flammable Solids)
  USHazmatClass5: 'USHazmatClass5', // (Oxidizers)
  USHazmatClass6: 'USHazmatClass6', // (Poison)
  USHazmatClass7: 'USHazmatClass7', // (Radioactive)
  USHazmatClass8: 'USHazmatClass8', // (Corrosives)
  USHazmatClass9: 'USHazmatClass9', // (Miscellenous)
  OtherHazmatExplosive: 'OtherHazmatExplosive', // (Explosives)
  OtherHazmatGeneral: 'OtherHazmatGeneral', // (Miscellaneous)
  OtherHazmatHarmfulToWater: 'OtherHazmatHarmfulToWater' // (Harmful to Water)
}
```

**Example usage:**
```js
clientMd.setVehicleLoadType(clientMd.VEHICLE_LOAD_TYPE_ENUM.USHazmatClass4);
```
---
### vehicle_adr_tunnel_restriction_code

**Description:**

ADR tunnel restrictions
*Only for `"truck"` `mode`*

**Setter:**
```js
/**
 * Set vehicle_adr_tunnel_restriction_code
 * @param {null|string|VEHICLE_ADR_TUNNEL_RESTRICTION_CODE_ENUM} vehicleAdrTunnelRestrictionCode
 */
setVehicleAdrTunnelRestrictionCode (vehicleAdrTunnelRestrictionCode) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {VEHICLE_ADR_TUNNEL_RESTRICTION_CODE_ENUM}
 */
VEHICLE_ADR_TUNNEL_RESTRICTION_CODE_ENUM = {
  b: 'b', // (Passage forbidden through tunnels of category B, C, D and E)
  c: 'c', // (Passage forbidden through tunnels of category C, D and E)
  d: 'd', // (Passage forbidden through tunnels of category D and E)
  e: 'e' // (Passage forbidden through tunnels of category E)
}
```

**Example usage:**
```js
clientMd.setVehicleAdrTunnelRestrictionCode(clientMd.VEHICLE_ADR_TUNNEL_RESTRICTION_CODE_ENUM.e);
```
---
### pois_corridor_options

**Description:**

Options that will be used to retrieve Points of Interest (POIs) along the route (will be provided as mentions POI Corridor).

This method accepts an object or an array of objects with the following properties:

- `poi_type` (required):<br>
  Sets the type of POIs to retrieve. Must be one of `"accommodation"`, `"reststop"`, `"servicestation"`, `"restaurant"`, `"booking"`, `"tourism"`, or `"evstation"`.
- `max_distance` (required):<br>
  Sets the maximum distance in meters between a POI and the route. Allows to determine the width of the corridor path to search. A valid value is an integer between 0 and 20000 (20 km).
- `max_time`:<br>
  Sets the max travel time for POI from the route, in seconds.
- `ranges`:<br>
  Sets the ranges for POI search. Consists of a semicolon-separated list of `{fromLegIndex},{fromRatioInLegIndex}-{toLegIndex},{toRatioInLegIndex};{fromLegIndex},{fromRatioInLegIndex}-{toLegIndex},{toRatioInLegIndex}`
- `limit`:<br>
  Sets the upper limit number of POIs to be included in the response. A valid value is an integer between 1 and 100.`distance`, `name` and `type`. The default value is `distance`. *Not yet implemented in corridor service (no impact).*
- `fields`:<br>
  Sets the list of fields expected in the POIs datasheets in the result. The value is a comma-separated string (e.g. "name,category,address"). *Not yet implemented in corridor service (no impact).*

**Setter:**
```js
/**
 * Set pois_corridor_options
 * @param {Array<{
 *   poi_type: 'accommodation' | 'reststop' | 'servicestation' | 'restaurant' | 'booking' | 'tourism' | 'evstation'
 *   max_distance?: number
 *   max_time?: number
 *   limit?: number
 *   ranges?: string
 * }>} poisCorridorOptions
 */
setPoisCorridorOptions (poisCorridorOptions) {
  //...
}
```

**Example usage:**
```js
clientMd.setPoisCorridorOptions({
  poi_type: 'servicestation',
  max_distance: 50,
  max_time: 300,
  limit: 20
});
```
---
### vehicle_type

**Default value:** `2`

**Description:**

The type of the vehicle. 
Value should be between 1 to 3.

**Setter:**
```js
/**
   * Set vehicle_type
   * @param {null|integer|VEHICLE_TYPE_ENUM} vehicleType
   */
  setVehicleType (vehicleType) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {VEHICLE_TYPE_ENUM}
 */
VEHICLE_TYPE_ENUM = {
  1: 1, // (Motorcycles/ Side-Cars/ Trikes)
  2: 2, // (Light vehicles - All cars with/without one/two axle trailers)
  3: 3 // (Intermediate vehicles - Pick-ups and Vans with/without one/two axle trailers)
}
```

**Example usage:**
```js
clientMd.setVehicleType(clientMd.VEHICLE_TYPE_ENUM[2]);
```
---
### annotations

**Description:**

Allows you to specify which metadata along the route that you want to have in the result
*Only for `"car"` and "motorcycle" `mode`*

**Setter:**
```js
/**
 * Set annotations
 * @param {Array.<string|ANNOTATION_ENUM>} annotations
 */
setAnnotations (annotations) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {ANNOTATION_ENUM}
 */
ANNOTATION_ENUM = {
  maxspeed: 'maxspeed',
  congestion: 'congestion',
  duration: 'duration',
  'consumption.fuel': 'consumption.fuel',
  'consumption.electricity': 'consumption.electricity'
}
```

**Example usage:**
```js
clientMd.setAnnotations([
  clientMd.ANNOTATION_ENUM.maxspeed,
  clientMd.ANNOTATION_ENUM.congestion,
  clientMd.ANNOTATION_ENUM['consumption.electricity']
]);
```

### currency

**Default value:** `"EUR"`

**Description:**

Available Options to sync with currency enum values.

**Setter:**
```js
/**
 * Set currency
 * @param {null|string|CURRENCY_ENUM} currency
 */
setCurrency (currency) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {CURRENCY_ENUM}
 */
CURRENCY_ENUM = {
  EUR: 'EUR',
  CAD: 'CAD',
  HKD: 'HKD',
  ISK: 'ISK',
  PHP: 'PHP',
  DKK: 'DKK',
  HUF: 'HUF',
  CZK: 'CZK',
  AUD: 'AUD',
  RON: 'RON',
  SEK: 'SEK',
  IDR: 'IDR',
  INR: 'INR',
  BRL: 'BRL',
  RUB: 'RUB',
  HRK: 'HRK',
  JPY: 'JPY',
  THB: 'THB',
  CHF: 'CHF',
  SGD: 'SGD',
  PLN: 'PLN',
  BGN: 'BGN',
  TRY: 'TRY',
  CNY: 'CNY',
  NOK: 'NOK',
  NZD: 'NZD',
  ZAR: 'ZAR',
  USD: 'USD',
  MXN: 'MXN',
  ILS: 'ILS',
  GBP: 'GBP',
  KRW: 'KRW'
}
```

**Example usage:**
```js
clientMd.setCurrency(clientMd.CURRENCY_ENUM.USD);
```
---
### unit

**Default value:** `"metric"`

**Description:**

Available Options to sync with unit enum values.

**Setter:**
```js
/**
 * Set unit
 * @param {null|string|UNIT_ENUM} unit
 */
setUnit (unit) {
  //...
}
```

***Enum:***
```js
/**
 * @readonly
 * @enum {UNIT_ENUM}
 */
UNIT_ENUM = {
  metric: 'metric',
  imperial: 'imperial'
}
```

**Example usage:**
```js
clientMd.setUnit(clientMd.UNIT_ENUM.imperial);
```
---


## 🥷 Developers

#### Project initialization

First you need to install dev dependencies running:

```bash
npm install
```

Then you need to initialize some devs dependencies running:

```bash
npm run dev:init
```

Create a `.env` file at the project's root and complete it adding:
**This configuration will be used in every tests**
```
API_KEY = 'YOUR_API_KEY'
API_URL = 'https://dev.api.michelingroup.com'
API_VERSION = 'v1'
```
**Note:** This environment variable will be used in every jest tests.

Finally, you can launch `dev:watch` script:

```bash
npm run dev:watch
```


Project use [editorconfig](https://editorconfig.org/) to helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs.
Please install the [plugin](https://editorconfig.org/#download) for your IDE if needed.
**Tips:**: `editorconfig` currently doesn't allow to specify a rule on to insert space pefore function parenthesis. But `lint` will need it to respect Standards.
If you're using Visual Studio Code, you can easily check `JavaScript › Format: Insert Space Before Function Parenthesis` in IDE settings.

#### Project informations

`lint`actually use [Standard](https://standardjs.com/) configuration with ECMAScript 12.

#### Publishing informations

Project use `semantic-release` to manage versioning and package publishing.

**semantic-release** uses the commit messages to determine the type of changes in the codebase. Following formalized conventions for commit messages, **semantic-release** automatically determines the next [semantic version](https://semver.org) number, generates a changelog and publishes the release.

By default **semantic-release** uses [Angular Commit Message Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format). The commit message format can be changed with the [`preset` or `config` options](docs/usage/configuration.md#options) of the [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer#options) and [@semantic-release/release-notes-generator](https://github.com/semantic-release/release-notes-generator#options) plugins.

Tools such as [commitizen](https://github.com/commitizen/cz-cli) or [commitlint](https://github.com/conventional-changelog/commitlint) can be used to help contributors and enforce valid commit messages.

The table below shows which commit message gets you which release type when `semantic-release` runs (using the default configuration):

| Commit message                                                                                                                                                                                   | Release type               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| `fix(pencil): stop graphite breaking when too much pressure applied`                                                                                                                             | Patch Release              |
| `feat(pencil): add 'graphiteWidth' option`                                                                                                                                                       | ~~Minor~~ Feature Release  |
| `perf(pencil): remove graphiteWidth option`<br><br>`BREAKING CHANGE: The graphiteWidth option has been removed.`<br>`The default graphite width of 10mm is always used for performance reasons.` | ~~Major~~ Breaking Release |

**Example**
```bash
git commit -m "fix: updating readme for clarity"
```
Will increment `<PATCH>` version value. If version was: `1.0.0`, it becomes `1.0.1`.

#### ⚠️ First release

Currently, the release on `NPM` is done as dry-run mode. To make the first release, you will need to:
- Update `package.json` scripts `"semantic-release": "semantic-release --dry-run"` removing `--dry-run` option
- Remove this `First release` section from `README.md`
- Commit your changes to master with the message `"fix: initial release"`
- Push your changes and merge it to branch `master`

#### Helpfull scripts

Then you will find the helpfull scripts below: 

| <div style="width: 190px;">Script</div> | Description | 
| --- | --- | 
| `npm run dev:init` | Initialize some devs dependencies (install husky). | 
| `npm run dev:watch` | Launch build everytime you update and save a file. Very uselly during development. | 
| `npm run test:lint` | Launch lint tests. | 
| `npm run test:jest` | Launch jest tests. | 
| `npm run test:jest:enums` | Launch jest tests testing setters on `target` enums.<br>**Example usage** `npm run test:jest:enums --target=ALL`<br><br>**target can be:**<br>- `ALL` : This will launch all tests. But it's actually very slow and not fiable (errors 500 may appear)<br>- `TYPE_ENUM`<br>- `MODE_ENUM`<br>- `GEOMETRIES_ENUM`<br>- `OVERVIEW_ENUM`<br>- `LANGUAGE_ENUM`<br>- `POI_TYPE_ENUM`<br>- `MENTIONS_ENUM`<br>- `TRAFFIC_ENUM`- `AVOID_ENUM`<br>- `MOTORIZATION_ENUM`<br>- `FUEL_TYPE_ENUM`<br>- `CAR_TYPE_ENUM`<br>- `VEHICLE_LOAD_TYPE_ENUM`<br>- `VEHICLE_ADR_TUNNEL_RESTRICTION_CODE_ENUM`<br>- `VEHICLE_TYPE_ENUM`<br>- `ANNOTATION_ENUM`<br>- `CONGESTION_ENUM`<br>- `CURRENCY_ENUM`<br>- `UNIT_ENUM` |
| `npm run test` | Launch lint and jest tests. | 
| `npm run build:webpack` | Launch webpack build. | 
| `npm run build` | Launch webpack build. | 
| `npm run pre-commit` | **Not to use directly**<br>Used by Husky as a pre-commit hook.<br>Launch `npm run test`. | 
| `npm run semantic-release` | **Not to use directly**<br>Used by Gitlab CI to publish module on npm. | 

## 🏷️ Versioning

Michelin Directions use the [Semantic Versioning](https://semver.org/) specification, given a version number as `<MAJOR>.<MINOR>.<PATCH>`

## 📄 License

**Michelin Directions Javascript API Client** is an open-sourced software licensed under the [MIT license](LICENCE.md).