Venue Maps API Developer's Guide

Discovery Service

The Discovery Service allows you to obtain list of venues available in given geographical area.

Note: 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://discovery.venue.maps.api.here.com

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

Production environment

Customer Integration Testing environment

Service venues
Feature discovery
Version v1 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=48.103030448017215%2C-93.65234375000001 %2C-3.3445330159738336%2C143.65234375 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

Examples

Example Request:

https://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

Example Response:

{"hostname":"ip...",
 "totalHits":11,
 "forecastedHits":0,
 "bboxDiameter":22,
 "status":{"code":"200","message":"Ok"},
 "type":"venues",
 "results":{
  "items":[{
    "id":"DM_8791",
    "title":"Potsdamer Platz Arcaden",
    "address":{
      "countryCode":"DEU",
      "city":"Berlin",
      "postalCode":"10785",
      "street":"Alte Potsdamer Strasse","house":"7"},
    "position":[13.374028800000001,52.50753],
    "distance":"1.3597230050045217",
    "type":"urn:nlp-types:venue",
    "vicinity":"Alte Potsdamer Strasse 7,10785,Berlin,DEU",
    "size":1,
    "level":"13",
    "minFloor":-1,
    "maxFloor":1},
  
  {  "id":"DM_7171",
    "title":"Alexa",
    "address"{
      "countryCode":"DEU",
      "city":"Berlin",
      "postalCode":"10179",
      "street":"Grunerstrabe",
      "house":""},
    "position":[13.41571115,52.51872755],
    "distance":"2.3267883368141047",
    "type":"urn:nlp-types:venue",
    "vicinity":"Grunerstrabe,10179,Berlin,DEU",
    "size":1,"level":"13",
    "minFloor":-1,
    "maxFloor":3},
    .... Content Truncated .. 

Example Request (with static callback):

https://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...",
 "totalHits":11,
 "forecastedHits":0,
 "bboxDiameter":22,
 "status":{"code":"200","message":"Ok"},
 "type":"venues",
 "results":{
  "items":[{
    "id":"DM_8791",
    "title":"Potsdamer Platz Arcaden",
    "address":{
      "countryCode":"DEU",
      "city":"Berlin",
      "postalCode":"10785",
      "street":"Alte Potsdamer Strasse","house":"7"},
    "position":[13.374028800000001,52.50753],
    "distance":"1.3597230050045217",
    "type":"urn:nlp-types:venue",
    "vicinity":"Alte Potsdamer Strasse 7,10785,Berlin,DEU",
    "size":1,
    "level":"13",
    "minFloor":-1,
    "maxFloor":1},
  
  {  "id":"DM_7171",
    "title":"Alexa",
    "address"{
      "countryCode":"DEU",
      "city":"Berlin",
      "postalCode":"10179",
      "street":"Grunerstrabe",
      "house":""},
    "position":[13.41571115,52.51872755],
    "distance":"2.3267883368141047",
    "type":"urn:nlp-types:venue",
    "vicinity":"Grunerstrabe,10179,Berlin,DEU",
    "size":1,"level":"13",
    "minFloor":-1,
    "maxFloor":3},
    .... 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.

Attribute Type Description
status ResponseStatusCode HTTP response status code
type String VENUES | CLUSTERS
results Array An array of ResultItemCluster or ResultItemVenue