# Finding charging locations

> Show drivers where they can charge on an embeddable map covering your own network and every location Road reaches through roaming.

Your drivers can charge at your own stations and at every location Road reaches through [roaming](/docs/roaming). The **Road map widget** is an embeddable JavaScript library that puts that coverage on your own site, so drivers can see and search the locations open to them. A live preview is at [mapsdk.road.io](https://mapsdk.road.io/).

The same location data is available over the [Map API](/docs/platform/reference/map-api) if you would rather build your own interface.

## Embedding

To embed the map, the below widget needs to be pasted into the HTML of the website, the configuration parameters are explained in a section below. For the widget to draw properly, the container DOM node needs to have height specified for the widget to fill its full height.

```html
<!doctype html>
<html>
<head>
    <style>.container {
        position: relative;
        top: 0;
        width: 100%;
        min-height: 100vh;
        height: 100vh;
        /* min-height: -webkit-fill-available; */
        background: #f5f5f5;
    }</style>
    <script defer="defer" src="https://mapsdk.road.io/sdk.js"></script>
    <script>window.ROADIO_MAP_SDK = {configuration}</script>
</head>
<body>
<div class="container">
    <div style="height: 100%" id="road-map-widget"></div>
</div>
</body>
</html>
```

### Configuration

The configuration dictionary assigned to `window.ROADIO_MAP_SDK` supports following keys:

**Starting from version 2, a public key must be provided when initialising the widget.** Please contact your account manager to get an authorisation key.

| Field Name                  | Required | Version(s) | Context | Description                                                                                                                                                                                      | Default Value           |
| :-------------------------- | :------- | :--------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------- |
| `version`                   | No       | Both       | Both    | Which version of the map SDK do you wish to use.                                                                                                                                                 | `v1`                    |
| `domNode`                   | Yes      | Both       | Both    | Reference to a valid DOM element where the map will be rendered.                                                                                                                                 | `-`                     |
| `gestureHandling`           | No       | Both       | Both    | Google Maps SDK parameter controlling how gestures (scroll, pinch, etc.) interact with the map. Allowed values: `greedy`, `cooperative`, `none`, `auto`. We suggest a default value of `greedy`. | `-`                     |
| `language`                  | No       | Both       | Both    | Language of the widget. Supported values: `en`                                                                                                                                                   | `en`                    |
| `position {lat,lng}`        | No       | Both       | Both    | Initial latitude/longitude to centre the map on load. If not provided, defaults to visitor's IP-based location.                                                                                  | Visitor IP location     |
| `enableZoomControls`        | No       | Both       | Both    | Whether to display zoom (+/-) controls in the bottom-right corner.                                                                                                                               | `false`                 |
| `enableSidebar`             | No       | Both       | Both    | Enables sidebar with location/cluster information when selected.                                                                                                                                 | `false`                 |
| `enablePlacesSearch`        | No       | Both       | Both    | Enables address search input at the top of the map.                                                                                                                                              | `true`                  |
| `provider`                  | Yes      | Both       | Both    | Provider reference within the Road platform.                                                                                                                                                     | `-`                     |
| `locationId`                | No       | Both       | Both    | If provided, the map will zoom to the given `locationId` and open its sidebar (if enabled). Overrides `position`.                                                                                | `-`                     |
| `theming {}`                | No       | Both       | Both    | Controls widget look and feel with keys: `brandColor`, `backgroundColor`, `textColor`, `borderColor`. Accepts HEX values (e.g. `#ff3d00`).                                                       | `-`                     |
| `authorization`             | Yes      | v2         | Both    | The public authorisation key to search for locations.                                                                                                                                            | `-`                     |
| `limitToLocationIds`        | No       | v2         | Both    | Constrains the map to only show the locations with the configured IDs.                                                                                                                           | All available locations |
| `preferredOperators`        | No       | v2         | Both    | Ensures that the selected operator appear at the top of the operator selector dropdown                                                                                                           |                         |
| `showNoAdditionalFeeFilter` | No       | v2         | msp     | Used to configure whether we enable the user to filter out stations that come with additional fees.                                                                                              |                         |
| `showPublishingModeFilter`  | No       | v2         | cpo     | Used to configure whether we enable the user to filter out public or private stations.                                                                                                           |                         |
| `showOperatorOnly`          | No       | v2         | both    | Include a quick filter option to find a specific operator.                                                                                                                                       |                         |

Full example:

```javascript
window.ROADIO_MAP_SDK = {
  domNode: document.getElementById("async-road-embed-map"),
  gestureHandling: 'greedy',
  language: 'en',
  position: {
    lat: 52.377956,
    lng: 4.897070
  },
  enableZoomControls: true,
  preferredOperators: ['E-Flux', 'Road B.V'],
  showOperatorOnly: 'E-Flux',
  authorization: '8921ad68-727d-4f95-ae8a-7a738371417b',
  version: 'v2',
  enableSidebar: true,
  enablePlacesSearch: true,
}
```

### React

A `React` component is made available to make it even easier to embed the `Road` map into your existing application. You can find the documentation for the component [here](https://www.npmjs.com/package/@road-labs/map-sdk).

Example usage of the component:

```typescript
import React from 'react';
import { App } from '@road-labs/map-sdk';
import '@road-labs/map-sdk/dist/index.css';

const MyMap: React.FC<{}>  = (props) => {
  return (
    <App
      height={600}
      authorization="8921ad68-727d-4f95-ae8a-7a738371417b"
      context="msp"
      gestureHandling="greedy"
      apiRoot="https://api.road.io"
      googleApiKey="your-google-maps-api-key"
      language="en"
      preferredOperators={["operator1", "operator2"]}
    />
  );
}
```