# ROOTE Map

Canonical URL: https://doc.roote.ai/map



ROOTE Map is publicly available at [map.roote.ai](https://map.roote.ai/).

<Card title="Open ROOTE Map" description="Explore mobility data on the public ROOTE map." href="https://map.roote.ai/" />

## Direct access [#direct-access]

Use the standard URL:

```text
https://map.roote.ai/
```

Without parameters, the map determines its initial view in this order:

1. Authorized geolocation.
2. Last saved view.
3. Approximate location.
4. Global fallback view.

## Open with an address or place [#open-with-an-address-or-place]

Use the `q` parameter when the integration knows a textual location rather than exact coordinates. It accepts an address, city, or place to search.

```text
https://map.roote.ai/?q=Place+de+la+République+Paris
```

Spaces can be encoded as `+` or `%20`. Accented and other special characters should be URL encoded.

```javascript
const url = new URL("https://map.roote.ai/");
url.searchParams.set("q", "Place de la République Paris");

console.log(url.toString());
```

## Position the camera with coordinates [#position-the-camera-with-coordinates]

Use `lat`, `lon`, and optionally `zoom` to control the map camera.

```text
https://map.roote.ai/?lat=48.8555&lon=2.3447&zoom=14
```

<Callout title="Camera only" type="info">
  This format controls the map camera only. It does not automatically create a search origin, a search pin, a mobility mode, or a nearby search.
</Callout>

The `coord=48.8555,2.3447` format is not used. The recommended coordinate format is `lat` together with `lon`.

## Restore a complete search [#restore-a-complete-search]

Use `search_lat`, `search_lon`, `search_label`, `zoom`, and `modes` to restore a complete mobility-search context.

```text
https://map.roote.ai/?search_lat=44.8416106&search_lon=-0.5810938&search_label=Bordeaux&zoom=12&modes=scooter
```

This opens ROOTE Map with Bordeaux as the search origin and restores the scooter mobility context.

`search_lat` and `search_lon` are used to:

* restore the search origin;
* position the search pin;
* calculate distances;
* launch the initial nearby search when a mobility mode is present;
* initialize the camera when `lat` and `lon` are absent.

<Callout title="Avoid unnecessary duplication" type="info">
  In the common case, it is not necessary to duplicate the same coordinates in both `lat`/`lon` and `search_lat`/`search_lon`.
</Callout>

## Mobility modes [#mobility-modes]

| Value     | Meaning                |
| --------- | ---------------------- |
| `bicycle` | Bicycle                |
| `scooter` | Kick scooter           |
| `moped`   | Moped or motor scooter |
| `car`     | Car                    |
| `station` | Station                |

Pass multiple modes as comma-separated values:

```text
modes=bicycle,scooter,car
```

Unknown mode values are ignored.

<Callout title="Map and REST use different contracts" type="warn">
  `station` is a supported ROOTE Map mode value. Do not merge it with the REST `/v1/nearby` mobility-mode contract: REST represents stations through the `include` result family, while ROOTE Map represents them in URL state with `station`.
</Callout>

## Control camera and search separately [#control-camera-and-search-separately]

Camera coordinates and search-origin coordinates can coexist.

```text
https://map.roote.ai/?lat=43.6045&lon=1.4440&zoom=13&search_lat=44.8416&search_lon=-0.5811&search_label=Bordeaux&modes=bicycle
```

In this example:

* the camera opens over Toulouse;
* the search origin remains Bordeaux;
* distances remain calculated from Bordeaux;
* the search context remains associated with Bordeaux.

## Priority rules [#priority-rules]

| Situation                             | Behavior                                       |
| ------------------------------------- | ---------------------------------------------- |
| `lat` and `lon` present               | They control the camera.                       |
| `search_lat` and `search_lon` present | They control the search origin.                |
| `lat` and `lon` absent                | The search origin also initializes the camera. |
| User pans the map                     | The search context is preserved.               |

This separation lets an integration show another geographic area without silently changing the origin used for distances and the mobility-search context.

## Embed ROOTE Map [#embed-roote-map]

Use an iframe to embed the standard map:

```html
<iframe
  title="ROOTE Map"
  src="https://map.roote.ai/"
  width="100%"
  height="600"
  loading="lazy"
  allow="geolocation"
  style="border: 0;"
></iframe>
```

An iframe can also restore a complete search context:

```html
<iframe
  title="ROOTE Map — Trottinettes à Bordeaux"
  src="https://map.roote.ai/?search_lat=44.8416106&amp;search_lon=-0.5810938&amp;search_label=Bordeaux&amp;zoom=12&amp;modes=scooter"
  width="100%"
  height="600"
  loading="lazy"
  allow="geolocation"
  style="border: 0;"
></iframe>
```

Inside HTML attribute values, encode `&` as `&amp;`.

## Geolocation in iframes [#geolocation-in-iframes]

The iframe attribute `allow="geolocation"` allows the embedded map to request the user's location.

Geolocation remains subject to:

* user consent;
* browser permissions;
* the parent site's permissions policy.

The `allow="geolocation"` attribute does not bypass browser permission.

## URL parameter reference [#url-parameter-reference]

| Parameter      | Role                               |
| -------------- | ---------------------------------- |
| `q`            | Search an address, city, or place. |
| `lat`          | Camera latitude.                   |
| `lon`          | Camera longitude.                  |
| `zoom`         | Camera zoom.                       |
| `search_lat`   | Search-origin latitude.            |
| `search_lon`   | Search-origin longitude.           |
| `search_label` | Human-readable search label.       |
| `modes`        | Comma-separated mobility modes.    |

<Callout title="Camera view or mobility context?" type="info">
  Use `lat` and `lon` when you only want to restore **what the user is looking at**. Use `search_lat` and `search_lon` when you want to restore **what the user's mobility search is about**.
</Callout>