Venue Maps API Developer's Guide

Discovery Service

The Discovery Service V2 enables discovery of venues. Bounding box can be used as a request parameter to only return venues falling inside specified bounding box. The maximum diameter (diagonal length) of provided bounding box is 100 000 meters. If no bounding box is given, all venues matching additional filtering parameters are returned.

By default, discovery service returns both public and private content. Filtering parameter ns can be used to provide a list of namespaces to which discovered items should be matched against. Special namespace keywords public and private can be used to refer all public and all private items respectively. Keyword public expands to full list of private namespaces matching authorizations provided in request.

For more informaton on private venues, please visit the Venue Maps page here

Note: The CIT environment is limited to venues in Chicago (US), Boston (US), Berlin (DE) and San Francisco (US).
Table 1. Basic elements of request to Discovery Service
Element Value/Example Description
Base

https://indoor-discovery.venue.maps.api.here.com

https://indoor-discovery.venue.maps.cit.api.here.com

Production environment

Customer Integration Testing environment

Feature discovery
Version v2 Version number of Venue Maps API
Application Id app_id={YOUR_APP_ID} Substitute with your unique Application Id
Application Code app_code={YOUR_APP_CODE} Substitute with your unique Application Code
Bounding box at=52.569352,13.240772,52.468448,13.521953 Bounding box is the geographical box which encompasses a certain area/venue. Bounding box is given as two WGS 84 coordinates topLeftLat, topLeftLon, bottomRightLat, bottomRightLon and URL encoded
JSONP static callback function (optional) cbfn=JSON.venues Substitute with desired static callback URL encoded
Content namespace selection (optional) ns=public Limit results to public content (Special namespace keyword public and private can be used to refer all public and all private items respectively. By default, discovery service returns both public and private content)
Content namespace selection (optional) ns=private Limit results to private content (Special namespace keyword public and private can be used to refer all public and all private items respectively. By default, discovery service returns both public and private content)
Value representing index offset on paginated result set (optional) after A value representing index offset on paginated result set. Correct value of this parameter can be retrieved from discovery service response in case results contain multiple pages
The size of each page pagesize Determines how many result items are returned as a response to a single request (default value is 50)

Examples

Example Request:

https://indoor-discovery.venue.maps.cit.api.here.com/discovery/v2
  ?app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}
  &at=52.569352,13.240772,52.468448,13.521953

Example Response:

{
  "hostname": "ip-xx",
  "type": "venues",
  "status": {
    "code": "OK",
    "reason": "DISCOVERY_SUCCESSFULL"
  },
  "paging": {
    "after": "1"
  },
  "results": {
    "items": [...venue items...]
  }
}
Table 2. Response fields
Field Description

type

Type of response. Currently only "venues" type is supported

status.code

Enumeration. Allowed values OK and NOK

status.reason

Textual reason for success or failure

paging.after

Value representing last returned venue item in paginated result set. Can be provided as a value of after request parameter to retrieve next page of results in paginated result set

results.items

A collection of venue items

Each venue item in the collection is represented as follows:

{
  "id": "DM_18568",
  "title": "LP12 Mall of Berlin",
  "address": {
    "countryCode": "DEU",
    "city": "Berlin",
    "postalCode": "10117",
    "street": "Leipziger Platz",
    "house": "12"
  },
  "position": [
    13.381429987051547,
    52.510570662621134
  ],
  "distance": "0.013010295533498152",
  "type": "urn:nlp-types:venue",
  "vicinity": "Leipziger Platz 12,10117,Berlin,DEU",
  "size": 1,
  "level": "13",
  "bbox": [
    [
      13.378871714287248,
      52.51132800366525
    ],
    [
      13.383988259815847,
      52.50981332157702
    ]
  ],
  "minFloor": -5,
  "maxFloor": 2,
  "namespace": "public"
}
Table 3. Response fields
Field Description

position

The coordinates of the venue centroid

distance

Distance from request bounding box centroid to venue centroid

namespace

The namespace of the discovered venue