Venue Maps API Developer's Guide

Discovery Service

The Discovery Service allows you to obtain a list of venues available in a given geographical area. Note that the CIT environment is limited to venues in Chicago (US), Boston (US), Berlin (DE) and San Francisco (US)..

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, see https://here.com/en/products-services/products/here-venue-maps.

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
The previous example contains a few unexplained data points such as "level" - which appears to be different to the "level" described in the model structure. Logged here: https://confluence.in.here.com/display/TEW/Venue+Maps+API+Doc+-+Questions+and+Answers-\->

Example Request (with static callback):

https://indoor-discovery.venue.maps.cit.api.here.com/venues/discovery/v1
  ?app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}
  &at=52.569352,%2013.240772,52.468448,%2013.521953
  &cbfn=JSON.venues

Example Response:

JSON.venues({
  "hostname": "ip...",
  "type": "venues",
  "status": {
    "code": "OK",
    "reason": "DISCOVERY_SUCCESSFULL"
  },
  "results": {
    "items": [{
      "id": "DM_18568",
      "title": "LP12 Mall of Berlin",
      "address": {
        "countryCode": "DEU",
        "city": "Berlin",
        "postalCode": "10117",
        "street": "Leipziger Platz",
        "house": "12"
      },
      "position": [52.510570099882194,
      13.381399000013154],
      "distance": 926.2459256454601,
      "type": "urn:nlp-types:venue",
      "vicinity": "Leipziger Platz 12,10117,Berlin,DEU",
      "bbox": [[52.51132166967421,
      13.378926268672588],
      [52.50981862285035,
      13.383871805467322]],
      "minFloor": -4,
      "maxFloor": 2,
      "namespace": "public"
    },
    {
      "id": "DM_16615",
      "title": "Pergamonmuseum",
      "address": {
        "countryCode": "DEU",
        "city": "Berlin",
        "postalCode": "10178",
        "street": "Bode straße",
        "house": "1"
      },
      "position": [52.52092885006327,
      13.396425399977867],
      "distance": 1043.833708066091,
      "type": "urn:nlp-types:venue",
      "vicinity": "Bode straße 1,10178,Berlin,DEU",
      "bbox": [[52.521680707244336,
      13.39517699325204],
      [52.52017700802355,
      13.39767395183927]],
      "minFloor": -1,
      "maxFloor": 0,
      "namespace": "public"
    .... Content Truncated .... 

Response Attributes

As the number of venues returned in the Discovery Service response depends on the bounding box given, it's possible that the result may contain only a venue, few venues or a large number of venues. If the number of venues returned for the given bounding box is large i.e. 100, a cluster would be created. The cluster is identified by a position point (Lat,Lon) at the center, and the number of venues it contains. Thus, the results item may be of type Venue or Cluster.

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 HTTP response status code
namespace The namespace of the discovered venue