How to calculate route to the correct side of the street

This tutorial explains in detail how to use the sideOfStreetHint to influence which side of the street a waypoint should be matched to.

If you specify a waypoint that is located on a specific side of the street you should also specify the sideOfStreetHint to allow the Routing API to select the correct direction to arrive from at the waypoint. The most common source of this information is a search provider.

Conceptually, sideOfStreetHint is a location situated between 2 m to 100 m off the center line of the road, identifying one side of the street (for example, the right side, if it's to the right of the road's geometry).

The matchSideOfStreet place option tells the router when to consider the sideOfStreetHint:

• matchSideOfStreet=onlyIfDivided: This is the default value. In this case, the router only considers the sideOfStreetHint on streets where there is a physical or legal divider present between the opposite directions. In those cases, crossing lanes is impossible or inconvenient.
• matchSideOfStreet=always: In this case the router considers the sideOfStreetHint for all streets. Use this value if you know that the user is willing to take a longer route in order to ensure arriving at the correct side of the street.

We look at two examples in this tutorial:

• Specifying a waypoint on a road with legal and/or physical dividers
• Specifying a waypoint on a road without dividers

Divided street

This is an example of a request that benefits from using sideOfStreetHint:

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.532017,13.381293&'\
'destination=52.531076,13.384907;sideOfStreetHint=52.53094541029134,13.385008983523676&'\
'return=polyline,summary&'\
'transportMode=car&'\
'apiKey=YOUR_API_KEY'

The destination is on a street with a legal divider. Without the sideOfStreetHint (blue route) the user would not be able to access the destination properly. With a sideOfStreetHint (purple route) they are guided to the correct side of street.

Undivided street

In this example, the destination waypoint isn't located on a divided street. The default routing behavior in this case would be to ignore the sideOfStreetHint. Specify matchSideOfStreet=always to override the default behavior:

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'transportMode=car&'\
'origin=52.5411320,13.4108499&'\
'destination=52.5391210,13.4081705;sideOfStreetHint=52.5389135,13.4079459;matchSideOfStreet=always&'\
'return=polyline,summary&'\
'apiKey=YOUR_API_KEY'

• The purple route shows the default behavior.
• The blue route shows the effect of matchSideOfStreet=always. It obeys the sideOfStreetHint.