Web

The web tutorial gets you set up with a “batteries included” UI and sane defaults (if a bit customized for Stadia Maps at the moment). This document covers ways you can customize it to your needs.

Distance formatting

The built-in navigation UI formats the distance to the next maneuver and the remaining trip distance using the settings on <ferrostar-map>.

Set system to choose the units:

metric: meters and kilometers.
imperial: feet and miles.
imperialWithYards: yards and miles.

The default is metric. Number formatting follows the browser’s locale.

Use maxDecimalPlaces to control the maximum number of digits after the decimal point for fractional larger-unit distances. Defaults to 2. Shorter distances are formatted as whole smaller units, and only larger-unit values up to 10 units receive fractional digits. Larger values are formatted without fractional digits.

const ferrostarMap = document.getElementById("ferrostar");

ferrostarMap.system = "imperial";
ferrostarMap.maxDecimalPlaces = 2;

If you want to use your own code to handle navigation instead of the integrated search box, you can do so by the following steps:

You can disable the integrated search box with the useIntegratedSearchBox attribute.

<ferrostar-core
  id="core"
  valhallaEndpointUrl="https://api.stadiamaps.com/route/v1"
  styleUrl="https://tiles.stadiamaps.com/styles/outdoors.json"
  profile="bicycle"
  useIntegratedSearchBox="false"
></ferrostar-core>

Use your own search box/geocoding API

The HTML, JS, and CSS for this is out of scope of this guide, but here’s an example (without UI) showing how to retrieve the latitude and longitude of a destination using the Nominatim API (note their usage policy before deploying):

const destination = "One Apple Park Way";

const { lat, lon } = await fetch("https://nominatim.openstreetmap.org/search?q=" + destination + "&format=json")
  .then((response) => response.json())
  .then((data) => data[0]);

Get routes manually

Once you have your waypoint(s) geocoded, create a list of them like this:

const waypoints = [{ coordinate: { lat: parseFloat(lat), lng: parseFloat(lon) }, kind: "Break" }];

The asynchronous getRoutes method on FerrostarCore will fetch routes from your route provider (ex: a Valhalla server). Here’s an example:

const core = document.getElementById("core");
const routes = await core.getRoutes(locationProvider.lastLocation, waypoints);
const route = routes[0];

Once you have a route, it’s time to start navigating!

core.startNavigation(route, config);

Location providers

The “batteries include” defaults will use the web Geolocation API automatically. However, you can override this for simulation purposes.

`BrowserLocationProvider`

BrowserLocationProvider is a location provider that uses the browser’s geolocation API.

// Request location permission and start location updates
const locationProvider = new BrowserLocationProvider();
locationProvider.requestPermission();
locationProvider.start();

// TODO: This approach is not ideal, any better way to wait for the locationProvider to acquire the first location?
while (!locationProvider.lastLocation) {
  await new Promise((resolve) => setTimeout(resolve, 100));
}

`SimulatedLocationProvider`

TODO: Documentation

The Ferrostar Book

Web