Addons by Reinos

Appearance

How it works ​

Maps can show routes (before v5.0.0 this needed the separate Maps Route add-on). With the route tags you fetch a route between two (or more) places and either show the directions on your page or draw the route on a map. The route itself is calculated by a route provider: Google Maps, OpenRouteService, OSRM or Bing Maps.

The route tags ​

  • The routes are part of Maps, so the tags start with reinos_maps: the Route tag is {exp:reinos_maps:route} and the add_route tag is {maps:add_route}, used inside the Maps map tag. {exp:reinos_maps_route:route} doesn't exist and gives a "Tag Not Processed" error.
  • The distance tag {exp:reinos_maps:distance} gives the distance and travel time without a map, the route planner {maps:route_planner} lets visitors plan their own route to a destination.
  • The route providers are set in Maps as well: Add-Ons → Maps → Route Providers.
  • Route errors are written to the Maps log (Add-Ons → Maps → Logs).

Route providers ​

  • Set the provider in Add-Ons → Maps → Route Providers (see CP overview). An enabled provider needs an API key.
  • Only one provider is used: the first enabled one in the order Google Maps, OpenRouteService, OSRM, Bing Maps. When that provider fails, the next one is not tried instead.
  • In a multi-site (MSM) install every site has its own route providers.
  • Google Maps: the route is requested by your server, not by the visitor's browser. The API key needs the Routes API enabled (with billing) and must not be restricted to HTTP referrers; restrict it by IP address instead. Your server needs allow_url_fopen enabled. (From v5.0.0 Maps uses the Routes API, before it used the Directions API, which Google marks as "Legacy".)
  • Google Maps terms: the Google Maps Platform terms don't allow Google route content on a non-Google map, so with Google Maps as route provider, use a Google Maps tile (tiles="google_maps_roadmap" etc.). Latitudes and longitudes from Google may be cached for up to 30 days, so keep the "Geocode cache time" at 30 days or less. Check the current Google Maps Platform Service Specific Terms for your use case.
  • OpenRouteService (from v5.0.0): routes based on OpenStreetMap for driving, cycling, walking and wheelchair, with a free API key from HeiGIT, the maker of OpenRouteService. No transit, and optimize_waypoints is not supported. The route is requested by your server, the step instructions are in the lang of the tag. Check the free plan limits of OpenRouteService for your site.
  • OSRM (from v5.0.0): routes from your own OSRM server, based on OpenStreetMap, without an API key or a third party: enter the URL of the server instead of an API key. The server decides which travel modes work (driving, cycling, walking), avoid needs a server profile that supports it, and the step instructions are in English (OSRM has no translations). The public demo server (router.project-osrm.org) is only for testing.
  • Bing Maps: Microsoft is retiring Bing Maps for Enterprise and keys from a free (Basic) account no longer work, so Google Maps is the safer choice.

The flow of a route ​

Both tags follow the same steps:

  1. Finding the addresses. Addresses in address:from, address:to and address:waypoints are first looked up by the geocoding provider of Maps (see Geocoding providers). When the start or end address can't be found, no route is returned. A waypoint that can't be found is skipped. When you already have coordinates, use the latlng: parameters instead: they skip this step.
  2. The cache. A route that was fetched before is taken from the Maps cache, so the provider is not asked again. A cached route is used for as long as the "Geocode cache time" in Maps (default one week), see Control panel. When the provider finds no route, that is cached as well, so it is not asked again on every page load. When the request fails (for example an invalid API key), nothing is cached and the route is requested again on the next page load.
  3. Fetching the route. The route is requested from the route provider. Every waypoint is a stop, so the route has a leg from each stop to the next.
  4. The result. Distances and durations come as text, for example "45 mins" (Google) or "12.3 km" (Bing).

{exp:reinos_maps:route} ​

The Route tag outputs the distance, duration and start/end location of the route, and the turn-by-turn directions in the {direction:steps} pair. With Google the step instructions contain HTML (for example bold street names), with Bing they are plain text. When no route is found, the {if no_results} conditional is shown.

{maps:add_route} ​

The add_route tag goes inside {exp:reinos_maps:map} and draws the route as a line on the map, styled with the stroke: parameters. When no route is found, nothing is drawn and no error is shown on the page. fit_map:routes="yes" on the map tag zooms the map to fit all lines on the map, also lines that are not a route.

What is sent to the provider ​

The Route tag sends travel_mode, avoid, unit, lang and optimize_waypoints to the provider. Bing Maps doesn't optimize the waypoints of a transit route, and plans a transit route from the current time.

The add_route tag sends the same parameters.

Common problems ​

  • Nothing is shown / no_results: check the Maps log (Add-Ons → Maps → Logs, with "What to log" set to at least "only errors"). Typical messages:
    • "No Route Providers added." → no route provider with an API key is saved.
    • "Route: Google Maps: ..." → the error from Google, for example a key without the Routes API enabled ("Routes API has not been used in project ... or it is disabled"), without billing, restricted to HTTP referrers, or over its quota.
    • "Route: Bing Maps: Data cannot be fetched from the remote, possible API Key error" → the Bing request failed, for example because of an invalid or retired key.
    • "No result found for ..." → an address couldn't be found; check the geocoding provider or use latlng:.
    • "Route: no route found from ... to ..." → the provider has no route between the points (for example between continents). This result is cached, delete it in the Maps cache overview to try again before it expires.
  • Wrong or old route: the route comes from the cache for up to a week. Delete it in the Maps cache overview to fetch it again.
  • Usage and costs: every route that is not cached is a request to Google or Bing (plus a lookup for each address), and routes that fail with an error are requested again on every page load. Keep an eye on the limits and billing of your provider.