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