Route planner

A "plan your route" form under a map: the visitor fills in where they start (or uses their location), picks a travel mode, and sees the route on the map with the distance, the travel time, the steps and a link to open the route in Google Maps or Apple Maps. The page doesn't reload. (from v5.0.0)

{exp:reinos_maps:map}
    {maps:add_marker address="Domplein, Utrecht"}
    {maps:route_planner address:to="Domplein, Utrecht" travel_modes="cycling|walking|driving"}
{/exp:reinos_maps:map}

See the examples.

How it works

The route is calculated on the server by the route provider and cached like any other route, so the visitor's IP address never reaches the provider.

The destination, the travel modes, the unit, the language and avoid are fixed by the tag and signed: the planner only plans routes to the destination of your template, so nobody can use it to plan other routes on your API key. The visitor only chooses where to start and one of your travel modes.

The planner can be turned off, or set to answer only with routes that are already in the cache, in the settings, with a rate limit per IP address (default 10 routes per minute).

TIP

Every start address of a visitor is a new route for the route provider, and is saved in the cache. With Google Maps that is a paid request per route, see the rate limit in the settings. OpenRouteService has a free key, see Route providers.

"Use my location" is shown only when the browser supports it on a secure (https) page. The visitor's location is rounded to about 1 meter before the route is requested.

Tag parameters

address:to

The address of the destination, geocoded when the page is built.

address:to="" [REQUIRED] if latlng:to is empty

latlng:to

The latitude and longitude of the destination.

latlng:to="52.0907,5.1214" [REQUIRED] if address:to is empty

travel_modes

The travel modes the visitor can choose from, separated by a |. The first one is selected. With one travel mode the choice is not shown. transit is only supported by Google Maps.

travel_modes="driving|cycling|walking" [OPTIONAL]

unit

The unit of the distance: km or mi.

unit="km" [OPTIONAL]

lang

The language of the steps.

lang="en" [OPTIONAL]

avoid

Avoid tolls, highways or ferry (driving only), separated by a |.

avoid="" [OPTIONAL]

steps

Show the turn-by-turn steps under the summary (built-in HTML).

steps="yes" [OPTIONAL]

links

The links to open the route in another app: google, apple or both, separated by a |. Leave it empty for no links (built-in HTML). Apple Maps has no cycling routes, a cycling route opens with the default travel mode there.

links="google|apple" [OPTIONAL]

stroke:color, stroke:opacity, stroke:weight

The line of the route on the map.

stroke:color="#131540" stroke:opacity="0.6" stroke:weight="6" [OPTIONAL]

class

An extra class on the planner (built-in HTML).

class="" [OPTIONAL]

id

The id of the planner element. With markup="no" it is the id of the element with your own HTML. Without an id the planners are numbered: maps_route_planner_1, maps_route_planner_2, ...

id="" [OPTIONAL]

markup

no to write the HTML of the planner yourself, see Your own HTML. The tag then only connects your HTML to the map.

markup="yes" [OPTIONAL]

Texts

Every text of the planner can be changed with a param, e.g. to translate it:

Param	Default
label:from	From
label:locate	Use my location
label:my_location	My location (shown in the field after "Use my location")
label:travel_mode	Travel mode (for screen readers)
label:driving, label:cycling, label:walking, label:transit	Car, Bike, Walk, Public transport
label:submit	Plan route
label:google, label:apple	Open in Google Maps, Open in Apple Maps
text:summary	[distance], [duration]
text:loading	Planning the route...
text:not_found	The address was not found.
text:no_route	No route was found.
text:locate_error	Your location is not available.
text:error	The route cannot be planned right now, please try again later.

{maps:route_planner
    address:to="Domplein, Utrecht"
    travel_modes="cycling|walking"
    lang="nl"
    label:from="Vertrekpunt"
    label:locate="Gebruik mijn locatie"
    label:cycling="Fiets"
    label:walking="Lopen"
    label:submit="Plan route"
    text:summary="[distance] in [duration]"
}

Your own HTML

With markup="no" you write the planner yourself, anywhere on the page (e.g. in a sidebar outside the map tag). Give the element the id of the tag, and mark the parts with the data- attributes below. Only the form with a from field is required, leave out any other part you don't need:

<div id="planner">
    <form data-maps-route-form>
        <input name="from" placeholder="Where do you start?" required>
        <button type="button" data-maps-route-locate hidden>Use my location</button>
        <select name="travel_mode">
            <option value="cycling">Bike</option>
            <option value="walking">Walk</option>
        </select>
        <button>Plan</button>
    </form>

    <p data-maps-route-status></p>

    <div data-maps-route-result hidden>
        <h3><span data-maps-route-distance></span> · <span data-maps-route-duration></span></h3>
        <ul data-maps-route-steps>
            <template data-maps-route-step>
                <li><strong data-maps-route-step-instruction></strong> <em data-maps-route-step-distance></em></li>
            </template>
        </ul>
        <a data-maps-route-link="google" target="_blank" rel="noopener">Open in Google Maps</a>
    </div>
</div>

{exp:reinos_maps:map}
    {maps:route_planner address:to="Domplein, Utrecht" travel_modes="cycling|walking" id="planner" markup="no"}
{/exp:reinos_maps:map}

Attribute	Part
data-maps-route-form	The form, required. It needs a field named from (the start). A field named travel_mode (radio buttons, a select or a hidden field) is optional, without it the first of travel_modes is used. Only the travel modes of travel_modes are allowed
data-maps-route-locate	A "Use my location" button. Add hidden: the planner shows it when the browser supports it (on https)
data-maps-route-status	The loading and error messages
data-maps-route-result	The result. Add hidden: the planner shows it when there is a route, and hides it on an error
data-maps-route-summary	Filled with text:summary (the distance and the travel time)
data-maps-route-distance	Filled with the distance, e.g. 12.3 km
data-maps-route-duration	Filled with the travel time, e.g. 45 min
data-maps-route-steps	The list of steps, its content is replaced by the steps
data-maps-route-step	A <template> for one step, with data-maps-route-step-instruction, data-maps-route-step-distance and data-maps-route-step-duration inside. Without a template every step is an <li>
data-maps-route-link="google", data-maps-route-link="apple"	Links that get the href of the route in Google Maps or Apple Maps

The texts of the planner that are set by the Javascript (label:my_location, text:summary and the text: messages) are still set with the tag params. For full control, leave out the status and summary and use the events.

Styling

The built-in HTML has basic styles that take the font and colors of your site. Every part has a class to style it:

Class	Part
.maps-route-planner	The planner
.maps-route-planner__form	The form
.maps-route-planner__input	The start field
.maps-route-planner__locate	The "Use my location" button
.maps-route-planner__modes, .maps-route-planner__mode	The travel modes
.maps-route-planner__submit	The submit button
.maps-route-planner__status	The loading and error messages (--error for an error)
.maps-route-planner__result	The result, hidden until there is a route
.maps-route-planner__summary	The distance and travel time
.maps-route-planner__steps, .maps-route-planner__step	The steps
.maps-route-planner__links, .maps-route-planner__link	The links to Google Maps and Apple Maps

The planner has aria-busy="true" while it plans a route.

Javascript

Plan a route from your own code, e.g. a "route from here" button per store. The planner is found by its id (maps_route_planner_1 for the first planner on the page) or by the mapID of its map. It returns a promise with the route, or null when there is no route:

REINOS_MAPS.route({
    planner: 'maps_route_planner_1',
    from: 'Amersfoort',
    travel_mode: 'cycling'
}).then(function (route) {
    if (route) {
        console.log(route.distance, route.duration);
    }
});

The planner fires a maps:route:loaded event with the route, and a maps:route:error event with the error (not_found, no_route or another error) and its message. Both bubble up, so you can listen on the document:

document.addEventListener('maps:route:loaded', function (event) {
    console.log(event.detail.route.distance_m, event.detail.route.duration_s, event.detail.mapID);
});

The route has distance, duration, distance_m, duration_s, from, to, travel_mode, latlngs, bounds, steps (with instruction, distance, duration and location) and links (google and apple).