Custom Location Extension API Developer's Guide

Corridor Search for Custom Locations

User Story

The user wants to request custom locations between Friedrichstraße train station and Französische Straße metro station, both in Berlin. This is done via a corridor search.

Figure 1. Berlin Route Used in Custom POI Search
This request is split in two parts:
  • First, we request a route from Friedrichstraße train station to Französische Straße metro station using the HERE Routing API. Using the response data from that request, we create an array of latitudes and longitudes.
  • Then, we make a request to the Custom Location Extension API to search for all custom locations in the "HERE Stores DE" layer, using the array and a radius value to define a shape search area.

Request Summary: Routing API

HTTP method: GET
Resource: calculateroute.json
Parameters: app_id [app_id={YOUR_APP_ID}]

app_code [app_code={YOUR_APP_CODE}]

waypoint [waypoint0=geo!52.51978,13.388211][waypoint1=geo!52.514758,13.389155], a list of waypoints that define a route. First element marks the start point, last marks the end point.

mode [mode=shotest;car], specifies the routing mode for how the route is calculated.

Request: Routing API

The code below shows an actual request matching the user story.

https://route.cit.api.here.com
  /routing/7.2/calculateroute.json
  ?app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}
  &waypoint0=geo!52.51978,13.388211
  &waypoint1=geo!52.514758,13.389155
  &mode=shortest;car

Response: Routing API

"Response": {
  "MetaInfo": {
    ...
  },
  "Route":[
    {
      "RouteId":"REM0iQIAAADG-ZtQiEJKQBnlmZf
        DxipAAAAA4IlCSkAAAABAw8YqQAAAAAAAAPB
        _AAAAAAAA8H850yIicbVOXI4HKQFdmfBL
        _RyrAAEAAACQBykBAQAAAAAdqwABAAAAAADA
        _wEAAAAAAMD_UW2D8A_K",
      "Waypoint":[
        {
          "LinkId":"+572707641",
          "MappedPosition":
          {
            "Latitude":52.5198326,
            "Longitude":13.3882084
          },
          "OriginalPosition":
          {
            "Latitude":52.519785,
            "Longitude":13.388211
          },
          "Type":"stopOver"
        },
        {
          "LinkId":"-64955564",
          "MappedPosition":
          {
            "Latitude":52.5147705,
            "Longitude":13.3891602
          },
          "OriginalPosition":
          {
            "Latitude":52.514758,
            "Longitude":13.389155
          },
          "Type":"stopOver"
        }
      ],
      "Mode":
      {
        "Type":"shortest",
        "TransportModes":[
          "car"
        ],
        ...
      },
      "Leg":[
        ...
      ],
      "Summary":
      {
        "Distance":571,
        "TrafficTime":69,
        "BaseTime":69,
        "Flags":[
        ]
      }
    }
  ]
}

Request Summary: Corridor Search

HTTP method: GET
Resource: corridor.json
Parameters: app_id [app_id={YOUR_APP_ID}]

app_code [app_code={YOUR_APP_CODE}]

corridor [corridor=52.51978,3.388211;52.5198326,13.3882084; 52.5198402,13.3883495;52.5147705,13.3891602;52.514758,13.389155]

radius [radius=100], specifies the buffer search radius in meters.

layer_ids [layer_ids=30], specifies the list of layer IDs to be searched; only 1 layer for this example.