Addons by Reinos

Appearance

How it works ​

Maps Route adds routes to the Maps 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 or Bing Maps.

Maps Route and Maps ​

  • The route features are provided together with the Maps add-on. That's why 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 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), not to the Maps Route log.

Route providers ​

  • Set the provider in Add-Ons → Maps → Route Providers (see Installation). A provider without an API key is not saved.
  • Only one provider is used. When both Google Maps and Bing Maps have an API key, Google Maps is used. When that provider fails, Bing Maps is not tried instead.
  • In a multi-site (MSM) install all sites share the same route providers.
  • Google Maps: the route is requested by your server, not by the visitor's browser. The API key needs the Directions API enabled (with billing) and must not be restricted to HTTP referrers; restrict it by IP address instead. Google marks the Directions API as "Legacy", so check in your Google Cloud project that you can still enable it. Your server needs allow_url_fopen enabled.
  • 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. Routes that failed are not cached and are requested again on every page load.
  3. Fetching the route. The route is requested from the route provider. Waypoints are places the route passes through, not separate stops, so the result is always one route from start to end.
  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.

Parameters that currently have no effect ​

Not every parameter of the Route tag works with every provider at the moment:

  • travel_mode: routes are always driving routes, with both providers.
  • avoid: has no effect with Google Maps. With Bing Maps it gives an error, so don't use it with Bing.
  • unit: works with Bing Maps. Google Maps picks the unit itself, based on the country of the start point.
  • lang and optimize_waypoints: have no effect; Google returns the directions in English.

The add_route tag only uses the from/to/waypoints and travel_mode 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 Directions API enabled, 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:.
  • When Google simply can't find a route (for example between continents), nothing is logged and the tag shows no_results.
  • Error with address:waypoints: on PHP 8 this parameter gives an error. Use latlng:waypoints instead.
  • Error with avoid when Bing Maps is the provider: remove the parameter.
  • 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 failed routes are requested again on every page load. Keep an eye on the limits and billing of your provider.