Venue Maps API Developer's Guide

Quick Start

This article shows you how to use Venue Maps API.

Venue Maps API Resources

The Venue Maps API offers venue maps information in two types; Tiles and Models. Each type variation is provided using a different URL.

Venue Maps API Tiles are explained in detail in Tiles Resources. The provided variations of Venue Maps API Tiles are:

Venue Maps API Models offer all venue-related information in JSON format, fully explained in Models Resources. Models have two variations; Full Models and Points of Interest (POI) Models.

  • Full Models: provides venue information, geometry data, metadata, Points of Interest (POI) data and routing data in JSON format.
  • POI Models: provides venue information and Points of Interest (POI) data inside a venue in JSON format.

How to use Venue Maps API

Venue Maps API could be used to draw venues as a map overlay. For this functionality, Image Tiles in combination with Interaction Tiles can be used, or alternatively Interaction tiles with base 64 encoded images could be used. Venue Overlay consists of image and vector components. Image component are adjacent PNG tiles containing polygons, labels and icons. Vector component are Interaction JSON Tiles containing vector representation of corresponding PNG tile. Interaction Tile contains all polygons it intersects. By using Images Tile and Interaction tiles you can build full venue maps experience.

Figure 1. Relation between Image and Interaction Tiles

Another usage of Venue Maps API is to retrieve venue models and use it to draw venues and build using it your own customized experience. For this functionality Full models and POI Models are recommended.

How to find venues?

Venue Maps API offers two ways to discover venues available.

  • Discovery Service: Venue Maps API provides a customized service that returns the list of venues available in a given geographical area.
  • Venue Index: A full list of the venues available that makes it possible to do venues search locally and enhance your client performance.

Making your first request

Venue Maps API offers map tiles which when combined form a complete map of the world using the Normalized Mercator Projection. Also, Venue Maps API offers models, which provide a customized experience with enhanced performance.

In order to draw Venue Maps API overlay using tiles, simplest request must provide:

  • Unique identifier (Quadkey) of the map area requested
  • The resource type that is to be requested; for example Image Tile (PNG)
  • The Path variables which describe other details of the request (Zoom Level and Floor Level requested inside the venue)
  • authentication parameters

The examples below show requesting a venue map tile at Zoom Level 20, showing Floor Level 0, for the Quadkey number 03022223103013033. Each example is for a different resource type.

Example of request for PNG Tile

http://static-3.venue.maps.cit.api.here.com/0/tiles-png/L0/03022223103013033.png?
  Policy={YOUR_GENERATED_POLICY}
  &Signature={YOUR_GENERATED_SIGNATURE}
  &Key-Pair-Id={YOUR_GENERATED_KEY_PAIR_ID}
  &app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}
Figure 2. PNG Tile Response

Example of request for Interaction Tile


  http://static-3.venue.maps.cit.api.here.com/0/tiles-ia/L0/03022223103013033.json?
  Policy={YOUR_GENERATED_POLICY}
  &Signature={YOUR_GENERATED_SIGNATURE}
  &Key-Pair-Id={YOUR_GENERATED_KEY_PAIR_ID}
  &app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}

Response

[
  {"area":[248,254,249,254,250,254,251,254,252,254,253,254,254,253,255,253,
       256,254,260,252,261,253,262,252,265,252,265,251,266,251,267,251,
       268,251,268,252,269,252,270,253,270,252,272,251,271,250,272,249,
       272,248,273,246,271,245,270,245,267,245,266,245,265,246,263,247,
       261,247,259,248,257,249,254,250,252,251,249,252,247,253,246,253,
       247,254],
  
  "object":
  {
    "id":"Lv24319Ds_1795349",
    "category":{"id":"24"},
    "preview":"PlayArea",
    "outerAreaId":"Lv24319Ds_1795319_d",
    "type":"space/polygon",
    "contentId":"1111313"}},
  
  {"area":[237,257,236,258,235,259,236,260,236,261,237,262,238,262,239,262,
       240,262,240,261,241,262,242,261,243,261,244,261,245,259,246,259,
       247,258,247,257,247,256,246,256,246,255,246,254,245,254,244,254,
       243,255,242,256,241,256,240,256,239,257,238,258,238,257],
  
  "object":
  {
    "id":"Lv24319Ds_1795354",
    "category":{"id":"99999"},
    "preview":"Children's BoatingPond",
    "outerAreaId":"Lv24319Ds_1795319_d",
    "type":"space/polygon",
    "contentId":"1110676"
  }
}....

Example of request for Interaction Tile with base 64 encoded image


  http://static-3.venue.maps.cit.api.here.com/0/tiles-ia-b64/L0/03022223103013033.js?
  Policy={YOUR_GENERATED_POLICY}
  &Signature={YOUR_GENERATED_SIGNATURE}
  &Key-Pair-Id={YOUR_GENERATED_KEY_PAIR_ID}
  &app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}

Response

JSON.venues("0_17_33627_48715", {
  "image": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAhuklEQVR4nO2dS/AdxXXGvf...",
  "mambers": [
    {
      "area": [
        182, 69, 182, 85, ...
      ],
      "object": {
        "id": "Lv25710Ds_1914895",
        "preview": "Platform 21",
        "placeId": "",
        "type": "space/polygon"
      }
    },
    {
      "area": [
        74, 145, ...
      ],
      "object": {
        "id": "Lv25710Ds_1914919",
        "preview": "Shoe Shine Service",
        "placeId": "",
        "type": "space/polygon"
      }
    },
    ...
    {
      "area": [
        109, 191, 128, 190, 128, 205, 130, 205, 130, 190, 134, ...
      ],
      "object": {
        "id": "Lv25710Ds_1908939_d",
        "center": [
          41.878688,
          -87.6397015
        ],
        "preview": "Concourse Level",
        "minZoomLevel": 17,
        "placeId": "",
        "buildingPreview": "Union Station Chicago",
        "buildingMaxLevel": 1,
        "buildingMinLevel": 0,
        "type": "floor/polygon",
        "buildingId": "DM_12321"
      }
    }
  ]
});

The other approach to using Venue Maps API is using Venue Models to provide a customized experience with enhanced performance.

In order to draw Venue Maps API Venue Model, simplest request must provide:

Example of request of a Full Model

http://static-3.venue.maps.cit.api.here.com/1/models-full/DM_7171.json?
  Policy={YOUR_GENERATED_POLICY}
  &Signature={YOUR_GENERATED_SIGNATURE}
  &Key-Pair-Id={YOUR_GENERATED_KEY_PAIR_ID}
  &app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}

Response:

{"content":
  {"category":
    {
    "id":"shopping","nt":"6512"
    },
    
    "phoneNumber":"+49 (30) 2693400",
    "placeId":"",
    "names":{"GER":"Alexa Shopping Center"},
    "addresses":
      {"GER":{"postalCode":"10179",
      "countryCode":"DEU",
      "houseNumber":"20",
      "streetName":"Gruner strasse",
      "district":"DE","city":"Berlin"},
      "ENG":{"postalCode":"10179",
      "countryCode":"DEU",
      "houseNumber":"20",
      "streetName":"Gruner strasse",
      "district":"DE","city":"Berlin"}},
    "contentId":"814985"},
  
  "connectors":[{
    "destination2":"Lv15003Ds_2486040",
    "connectorClass":"ELEVATOR",
    "destination1":"Lv15004Ds_2486057"}, ... 
           == Content Truncated == 

Example of request for a POI Model

http://static-3.venue.maps.cit.api.here.com/1/models-poi/DM_7171.json?
  Policy={YOUR_GENERATED_POLICY}
  &Signature={YOUR_GENERATED_SIGNATURE}
  &Key-Pair-Id={YOUR_GENERATED_KEY_PAIR_ID}
  &app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}

Response:

{"content":
  {"category":
    {
    "id":"shopping","nt":"6512"
    },
    
    "phoneNumber":"+49 (30) 2693400",
    "placeId":"",
    "names":{"GER":"Alexa Shopping Center"},
    "addresses":
      {"GER":{"postalCode":"10179",
      "countryCode":"DEU",
      "houseNumber":"20",
      "streetName":"Gruner strasse",
      "district":"DE","city":"Berlin"},
      "ENG":{"postalCode":"10179",
      "countryCode":"DEU",
      "houseNumber":"20",
      "streetName":"Gruner strasse",
      "district":"DE","city":"Berlin"}},
    "contentId":"814985"},
  
  "connectors":[{
    "destination2":"Lv15003Ds_2486040",
    "connectorClass":"ELEVATOR",
    "destination1":"Lv15004Ds_2486057"}, ... 
           == Content Truncated ==