Maps API for JavaScript

660 Pages·2014·10.22 MB·English

Maps API for JavaScript
Developer's Guide
Version 3.0.4
Maps API for JavaScript Developer's Guide 2
►  Contents  
Contents
Legal Notices..........................................................................................................................................................4
Document Information....................................................................................................................................5
Chapter 1: Overview 6
.................................................................................................................................
What is the Maps API for JavaScript?........................................................................................................7
Why use the Maps API for JavaScript?......................................................................................................7
Browser Support.............................................................................................................................................8
HERE Maps API for JavaScript Modules.....................................................................................................8
Chapter 2: Quick Start 10
........................................................................................................................
Use Case.........................................................................................................................................................11
Loading the API Code Libraries.................................................................................................................11
Initialize Communication with Back-end Services................................................................................12
Initialize the Map..........................................................................................................................................12
Complete HTML Example Page.................................................................................................................13
Chapter 3: Guide 15
.......................................................................................................................................
Acquiring Credentials...................................................................................................................................16
API versions...................................................................................................................................................16
Map Types......................................................................................................................................................17
Map Events.....................................................................................................................................................22
Map Objects...................................................................................................................................................25
Marker Objects.................................................................................................................................27
Geo Shapes........................................................................................................................................32
StreetLevel.....................................................................................................................................................38
Map Controls and UI....................................................................................................................................42
Geocoding......................................................................................................................................................49
Routing............................................................................................................................................................56
Maps API for JavaScript Developer's Guide 3
►  Contents  
Traffic..............................................................................................................................................................63
Clustering.......................................................................................................................................................66
KML Support..................................................................................................................................................71
Service Support............................................................................................................................................72
Chapter 4: API reference 73
..................................................................................................................
H........................................................................................................................................................................74
Map......................................................................................................................................................74
clustering............................................................................................................................................92
data...................................................................................................................................................111
geo.....................................................................................................................................................122
lang....................................................................................................................................................158
map...................................................................................................................................................161
mapevents.......................................................................................................................................443
math..................................................................................................................................................459
service..............................................................................................................................................470
ui........................................................................................................................................................532
util......................................................................................................................................................640
Maps API for JavaScript Developer's Guide 4
►  Legal Notices  
Legal Notices
© 2014 HERE. All rights reserved.
This material, including documentation and any related computer programs, is protected by
copyright controlled by HERE. All rights are reserved. Copying, including reproducing, storing,
adapting or translating, any or all of this material requires the prior written consent of HERE. This
material also contains confidential information, which may not be disclosed to others without the
prior written consent of HERE.
Trademark Acknowledgements
HERE and Nokia are trademarks or registered trademarks of Nokia Corporation in the United States
and other countries.
Other trade names are trademarks or registered trademarks of their owners.
Disclaimer
This content is provided "as-is" and without warranties of any kind, either express or implied,
including, but not limited to, the implied warranties of merchantability, fitness for a particular
purpose, satisfactory quality and non-infringement. Nokia does not warrant that the content is error
free and Nokia does not warrant or make any representations regarding the quality, correctness,
accuracy, or reliability of the content. You should therefore verify any information contained in the
content before acting on it.
To the furthest extent permitted by law, under no circumstances, including without limitation Nokia's
negligence, shall Nokia be liable for any damages, including, without limitation, direct, special,
indirect, punitive, consequential, exemplary and/ or incidental damages that result from the use or
application of this content, even if Nokia or an authorized representative has been advised of the
possibility of such damages.
Maps API for JavaScript Developer's Guide 5
►  Document Information  
Document Information

Product
   Name: Maps API for JavaScript
   Version: Version 3.0.4

Document
   Name: Maps API for JavaScript Developer's Guide
   Id: 382cec5-1409139022
   Status: DRAFT
   Date: 2014-Aug-27, 11:31 (GMT)
Maps API for JavaScript Developer's Guide 6
►  Overview  
Chapter
1
Overview
Topics: This documentation introduces the HERE Maps API for JavaScript,
• What is the Maps API for offers a quick start guide, followed by a developer's guide with
JavaScript? articles showing the implementation of typical use cases, and ends
• Why use the Maps API for with a detailed API reference.
JavaScript?
• Browser Support The overview (this chapter):
• HERE Maps API for JavaScript
• defines the API
Modules
• outlines the key benefits of the API for developers
• explains the modular organization of the API
Maps API for JavaScript Developer's Guide 7
►  Overview  
What is the Maps API for JavaScript?
The HERE Maps API for JavaScript (also referred to as the Maps API in the following text) is a set
of programming interfaces that enable developers to build Web applications with feature rich,
interactive HERE Maps at their center. The API consists of libraries of classes and methods with
which to implement the functionality of an interactive application.
Why use the Maps API for JavaScript?
The Maps API for JavaScript offers the following high level features and benefits to developers of
Web applications with maps as a core element:
Table 1: Main features of the HERE Maps API for JavaScript
Feature Description
Efficient map rendering The API is built for HTML5-capable environments to maximize map and map object rendering
efficiency on mobile devices and desktops. It also includes support for high-DPI devices to show the
best maps wherever possible.
HERE Maps map data The API provides full access to world-leading map data and map images, with a choice of view
modes and customization options, including three main map types: map, terrain and hybrid.
Geocoding The API provides full access to geocoding and reverse geocoding services.
Routing The API supports route calculation and display, with a variety of customization options such as
public transport routing and others.
Enterprise routing The API supports advanced enterprise routing use cases such as isoline routing or truck routing.
Custom map objects The API supports the creation of both interactive and non-interactive map objects:
• markers with SVG, HTML or bitmap images
• geo shapes, including polygons, polylines, circles and rectangles
Mouse and touch The API (via an events extension) supports mouse and touch interaction with the map, including
interaction pan, zoom and pinch-to-zoom on a broad range of devices.
Pre-built UI controls The API offers pre-built, customizable UI controls that allow users to change the base map, zoom in
and out smoothly, and display the current map scale. In addition, info bubbles with arbitrary HTML
content and SVG images can be placed on the map.
Integrated HERE Thorough integration with HERE StreetLevel imagery, the API offers access to interactive 360°
StreetLevel panoramas in covered areas.
Maps API for JavaScript Developer's Guide 8
►  Overview  
Browser Support
The Maps API is built specifically for modern browsers that support HTML5 on desktop as well as
mobile environments. Although it is optimized for certain browsers and environments, we do our
utmost to ensure the API can be used on a wide variety of platforms and browsers.
Below is a list showing support (with and without optimizations) in the Maps API for different
browsers and environments:
Table 2: Browser support in HERE Maps API for JavaScript
Support Level Browser Environment
Supported with optimizations: Internet Explorer 10+ desktop, Windows Phone 8+
Firefox (latest) desktop
Google Chrome (latest) desktop, Android 4.4+ on mobile/tablet
Apple Safari 6+ desktop, iOS 6+ on mobile/tablet
Supported without optimizations: Internet Explorer 9 desktop
Android default browser / WebView [1]
Android 2.2+ on mobile/tablet
iOS WebView iOS 6+
Not supported: Opera
Internet Explorer <= 8
[1] Support does not extend to all multi-touch gestures as Android 2.x does not expose multi-
touch events
HERE Maps API for JavaScript Modules
The Maps API for JavaScript is organized into a number of modules. Developers can therefore use the
API efficiently by selecting only the modules which their applications require.
The table below outlines the selectable modules of the Maps API for JavaScript.
Maps API for JavaScript Developer's Guide 9
►  Overview  
Table 3: Modules of the HEREMaps API for JavaScript
Module name Module Description
dependencies
core (mapsjs-core.js) none This module contains the core functionality for rendering maps, map
layers and map objects as well as utilities used in other modules. This
module forms the core of the API and is a dependency of all other
modules.
service (mapsjs- core This module supports map tile retrieval, routing, geocoding, etc.
service.js)
mapevents (mapsjs- core This module provides functionality to enable user-interaction with the
mapevents.js) map, including map panning and pinch-to-zoom. The module normalizes
various browser event systems (mouse events, touch events, pointer
events) to offer unified events that can be used across desktop and
mobile environments.
ui (mapsjs-ui.js + core This module provides a set of pre-built cross-browser UI components
mapsjs-ui.css) (such as base map settings, zoom control, map scale) that can be added
to the map. It also provides functionality to display location-specific info
bubbles with arbitrary HTML content on the map.
clustering (mapsjs- core This module provides functionality for marker clustering.
clustering.js)
pano (mapsjs-pano.js) core, service This module provides access to HERE StreetLevel imagery on WebGL-
enabled devices. It supports switching the map to the StreetLevel
rendering mode and navigation through StreetLevel panoramas.
Maps API for JavaScript Developer's Guide 10
►  Quick Start  
Chapter
2
Quick Start
Topics: This article shows the implementation of a basic use case to
• Use Case demonstrate how to start using the Maps API for JavaScript.
• Loading the API Code Libraries
• Initialize Communication with Back-
end Services
• Initialize the Map
• Complete HTML Example Page