Venue Maps API Developer's Guide

Venue Maps API routing request

The Venue Maps API provides routing:

  • Inside a venue
  • From an outside point to a point inside a venue
  • From inside a venue to a point outside the venue
  • Between two venues

Routing combines indoor and outdoor routing into an integrated service and adds support for venue-specific attribution like elevators and escalators. The routing responses are in json format, and the the client is rendering. One or more route waypoints are within a routable venue or venues. Currently two waypoints are supported, representing start and destination coordinates respectively.

When the specified waypoints are inside separate venues or inside a single venue but in separate buildings, the venue routing service calls the outdoor routing service (matrix routing) to find the optimal outdoor route between the corresponding entrances. The most optimal route from the matrix routing response is then used as a outdoor route connecting venue/building entrances.

Note: Waypoints residing within private venues are considered as indoor waypoints only if request has credentials (app_id and/or Here OAuth2 token) authorizing access to those private venues. If no sufficient credentials are present the waypoint is considered as an outdoor waypoint. For more informaton on private venues, please visit the Venue Maps page here

Both indoor and outdoor routing calls can be parametrized separately. Many outdoor routing parameters are supported and passed as is to the outdoor routing call. For more information about outdoor routing parameters, see the Routing API Developer's Guide.

Based on provided routing parameters the venues routing service determines the actual routing strategy to execute. The following strategies are currently supported.

Routing mode

Desription

OUTDOOR

When both waypoints reside outside of venues the request is directly dispatched to outdoor routing service.

VENUE

Both waypoints inside same building within single venue.

VENUE_BUILDING_TO_BUILDING

Start and destination waypoints inside separate buildings within single venue.

OUTDOOR_TO_VENUE

Start waypoint outside venue, destination waypoint inside venue.

VENUE_TO_OUTDOOR

Start waypoint inside venue, destination waypoint outside venue.

VENUE_TO_VENUE

Start and destination waypoints inside separate venues.

The general syntax of venue routing request is:

Sample Request

https://indoor-routing.venue.maps.cit.api.here.com/venues/routing/v1
  ?app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}
  &waypoint0={START_OF_ROUTE}&waypoint1={END_OF_ROUTE}&venueRouteOptions={VENUE_ROUTE_OPTIONS}&mode=fastest;pedestrian
Note: In addition, most outdoor specific routing parameters can be appended to request URL. All defined outdoor specific parameters are directly passed to outdoor routing service. In the example above, the attribute values of mode= are sent to the outdoor routing service.

For more information on supported outdoor routing attributes, see the related section in the Routing API Developer's Guide.

There are some exceptions to this rule since not all outdoor specific paramenters are currently supported. The table below lists the exceptions.

Parameter

Comment

alternatives

No support for alternative routes.

metricsystem

No imperial support.

resolution

No support for resolution.

viewbounds

Access to all shape points is needed.

jsonattributes

Indoor routing relies on specific attributes which must be present in outdoor routing response.

representation

Indoor routing relies on specific attributes which must be present in outdoor routing response.

routeattributes

Indoor routing relies on specific attributes which must be present in outdoor routing response.

legattributes

Indoor routing relies on specific attributes which must be present in outdoor routing response.

maneuverattributes

Indoor routing relies on specific attributes which must be present in outdoor routing response.

linkattributes

Indoor routing relies on specific attributes which must be present in outdoor routing response.

lineattributes

Indoor routing relies on specific attributes which must be present in outdoor routing response.

generalizationtolerances

Indoor routing has no support for generalizations.

maxnumberofchanges

No public transit support.

avoidtransporttypes

No public transit support.

walktimemultiplier

No public transit support.

walkradius

No public transit support.

combinechange

No public transit support.

Waypoints

There can be only one start (waypoint0) and one destination (waypoint1) parameters in the request. The general syntax of the waypoint parameter is:

geo!{latitude}, {longitude},{level}

Example 1: waypoint0=geo!52.518807689845346,13.415577850623919,0

venueRouteOptions

Option

Desription

fastest

Calculate fastest route

shortest

Calculate shortest route

(dis)allowAll

Allow or disallow all connectors

(dis)allowElevators

Allow or disallow elevators

(dis)allowEscalators

Allow or disallow escalators

(dis)allowStairs

Allow or disallow stairs

(dis)allowShuttles

Allow or disallow shuttle connections

(dis)allowSkywalks

Allow or disallow skywalks

(dis)allowMovingSidewalks

Allow or disallow moving sidewalks

Example

Desription

venueRouteOptions=fastest;disallowAll;allowElevators

Calculate the fastest route with only elevators allowed as connectors.

venueRouteOptions=shortest;disallowEscalators

Calculated the shortest route with all types of connectors except escalators allowed

Default values

Route options are optional. If no options are given, the defaults are used: fastest;allowAll

Response

The Venues routing service response follows the structure of the common outdoor routing service response. Some extensions described below were added to represent indoor specific information.

The response currently consists of single route containing necessary legs to represent all indoor and connecting outdoor legs to travel between start and destination waypoints. Each leg has type property defining whether leg is indoor or outdoor leg. The legs are always represented in logical order from start to destination in respect to provided start and destination waypoints. For indoor legs, only pedestrian routing is currently supported, and any parameters suggesting other routing modes will be ignored.

In addition to common outdoor response shape property, the response introduces a level property determining corresponding level (floor) for every coordinate pair represented in the shape property.


  For example:
…
    "shape": [
      52.519885791453724,
      13.414394522476186,
      52.51939683023066,
      13.415148150431241,
      52.51856395001506,
      13.416065256894697,
      52.518521265746585,
      13.416319253668194,
      52.51856775464091,
      13.416489715739772,
      52.518598064769954,
      13.416581861849192,
      52.51841526493865,
      13.416708111029038,
      52.51840558397678,
      13.416716257755013,
      52.518318792513625,
      13.416794671105707,
      52.518351603126355,
      13.41705527381896
    ],
    "level": [
      0,
      0,
      0,
      0,
      0,
      0,
      0,
      0,
      1,
      1
    ],
...

  

The shape and level pair described above is available as both route and leg level attributes. So both routes as legs of a combined route can have shape-level pairs attached to them.

The maneuver element represents a position along a route on which the user is expected to perform a specific action such as entering or exiting a building or entering or exiting a connector between levels.


  For example:

[
  {
    "position": {
      "latitude": 52.51840558397678,
      "longitude": 13.416716257755013,
      "level": 0
    },
    "id": "V_7171Lv15001Ds2486074",
    "connectorType": "ESCALATOR",
    "actionType": "ENTER"
  },
  {
    "position": {
      "latitude": 52.518318792513625,
      "longitude": 13.416794671105707,
      "level": 1
    }
    "id": "V_7171Lv15002Ds2486091",
    "connectorType": "ESCALATOR",
    "actionType": "EXIT"
  }
]

  

For an example of a complete routing request and response, see Requesting a Venue Route.