Maps API for JavaScript Developer's Guide Public Version 2.5.3 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 Feature List......................................................................................................................................................7 Packages and Detection...............................................................................................................................8 Browser Support.............................................................................................................................................9 HTML5 Support.............................................................................................................................................10 Performance..................................................................................................................................................10 Chapter 2: Quick Start 12 ........................................................................................................................ Basic Scenario...............................................................................................................................................13 Loading the API Code Library....................................................................................................................13 Implementing the Application...................................................................................................................14 Setting Credentials..........................................................................................................................15 Displaying a Map..............................................................................................................................15 Chapter 3: User Guide 17 ......................................................................................................................... Acquiring Credentials...................................................................................................................................18 Beyond the Basic Map Application...........................................................................................................18 Map Types......................................................................................................................................................20 Components and User Interaction...........................................................................................................23 Markers...........................................................................................................................................................25 Geo Objects...................................................................................................................................................28 Map Overlays.................................................................................................................................................29 A Map of Berlin from 1789............................................................................................................30 Routing............................................................................................................................................................33 Maps API for JavaScript Developer's Guide 3 ►  Contents   Traffic..............................................................................................................................................................35 KML Support..................................................................................................................................................36 Heat Maps......................................................................................................................................................37 Marker Clustering.........................................................................................................................................39 Places...............................................................................................................................................................41 Architecture in Outline...................................................................................................................42 Places Widget....................................................................................................................................44 Searching for Places........................................................................................................................47 Displaying Place Details..................................................................................................................51 Making Sure the Widget Is Ready................................................................................................55 Templates..........................................................................................................................................56 Positioning......................................................................................................................................................89 Event System.................................................................................................................................................91 Observers and Mutable Objects...............................................................................................................95 Multi-language Support..............................................................................................................................96 Chapter 4: API reference 98 .................................................................................................................. jsMotif..............................................................................................................................................................99 Template............................................................................................................................................99 selector............................................................................................................................................103 nokia..............................................................................................................................................................105 Features...........................................................................................................................................105 Settings............................................................................................................................................110 maps.................................................................................................................................................114 places................................................................................................................................................662 Maps API for JavaScript Developer's Guide 4 ►  Legal Notices   Legal Notices © 2013 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: Public Version 2.5.3     Document    Name: Maps API for JavaScript Developer's Guide    Id: a9bd3dd-1385500279    Status: FINAL    Date: 2013-Nov-26, 21:14 (GMT) Maps API for JavaScript Developer's Guide 6 ►  Overview   Chapter 1 Overview Topics: This article defines the HERE Maps API for JavaScript, explains its • What Is the Maps API for purpose, summarizes its features and outlines how it supports JavaScript? third-party application development. • Feature List • Packages and Detection • Browser Support • HTML5 Support • Performance Maps API for JavaScript Developer's Guide 7 ►  Overview   What Is the Maps API for JavaScript? The HERE Maps API for JavaScript (the Maps API) 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. The associated API Explorer offers ready-made working examples, whose code the developer can modify and view the effect immediately.   Feature List The main features offered by the Maps API are summarized in the table below: Table 1: Main features of the HERE Maps API for JavaScript Feature Description HERE Maps map data The API provides full access to world-leading map data in three different modes: satellite, terrain and hybrid. Points of interest The map data to which the API offers access, include millions of different places, landmarks, places and addresses located on maps. Their visibility on the map can be controlled via the API. Searches The API allows you to build search functionality into you application. Users can searches for places, using keywords, addresses, or geographic coordinates. Geocoding The API provides full access to geocoding and reverse geocoding services. Routing The API allows you to define and render routes between a start and a destination point. It supports many navigation options such as toll road preference and transport type. W3C positioning The API includes built-in functionality that takes advantage of the W3C Geolocation API supported by many browsers. Custom items The API allows you to modify existing markers or create custom ones, using SVG or bitmap images. You can also add geo shapes based on coordinates to the map: polygons, polylines, circles or rectangles, and make these custom map object interactive by assigning UI events to them. Maps API for JavaScript Developer's Guide 8 ►  Overview   Packages and Detection The HERE Maps API for JavaScript is modular and contains separate packages for maps, places, positioning, directions (routing) and data rendering. If an application does not require certain packages, you can reduce the footprint and load time by excluding them. The entry point to the API is the JavaScript file "jsl.js" (see also Quick Start on page 12). It contains a package loader and an environment detection mechanism. To load the API, set the "src" attribute of a <script> element to the base URL followed by the name of this file. You can alter the packages loaded by the <script> element by appending the parameter with, followed by the equals sign (=), followed by a comma-spearated list of packages. If you do not specify any packages (that is if you use the URL only without the with parameter), the Maps library package is loaded by default. The table below shows the packages you can select, using the query parameter with and the default loading behavior. Table 2: Selectable packages in the HEREMaps API for JavaScript URL Parameter Allowed Values [1] Default with maps, positioning, places [2], placesdata [2], directions, maps [4] datarendering, all [3] The following notes relate to this table: [1] values can be combined in a comma-separated sequence, but specify either places or placesdata (not both); all must not be used if any other package is specified [2] places means that the complete Places library is loaded (both UI and data); to load the data- only Places library, use placesdata [3] all loads all the available libraries [4] equivalent to "with=maps,placesdata", which loads the Maps library package and the Places data-only library package, not the Places UI library   The example below shows an HTML page that loads the following library packages: Maps, Places (complete), Rouging and Positioning. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" Maps API for JavaScript Developer's Guide 9 ►  Overview   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=7; IE=EmulateIE9; IE=10" /> <script type="text/javascript" src="http://js.api.here.com/se/2.5.3/jsl.js? with=maps,places,directions,positioning"> </script> </head> <body> ... </body> </html> Please note that the last part of the URL before the name of the JavaScript file is the release version number for the Maps API, which means that the URL changes, depending on which version you wish to use.   Browser Support The Maps API is a multi-purpose and cross-platform API, targeting all JavaScript-enabled Web browsers, whether desktop or mobile, as well as all HTML5 environments (see the next section for information about HTML5 support). Because the number of possible browser and platform combinations is too large, we limit our support to the following list of browsers: Table 3: Browser support in HERE Maps API for JavaScript Browser Support Internet Explorer 7+ desktop, Windows Phone with Mango update or later on mobile* Firefox 3.6+ desktop Google Chrome 12+ desktop, Android 2.2+ on mobile/tablet* Apple Safari 5+ desktop, iOS 4+ on mobile/tablet * support does not extend to all multi-touch gestures Maps API for JavaScript Developer's Guide 10 ►  Overview   HTML5 Support Although HTML5 is a new emerging HTML standard, and as such it is still undergoing continual improvement, the HERE Maps API for JavaScript is committed to supporting it. For information regarding the latest features of HTML5 please visit the official HTML5 Specification page of the W3C. Details on HTML5 compliance in different Web browsers, are available on THE HTML5 TEST. The built-in support for HTML5 in the Maps API enhances the user experience in browsers that implement the following aspects of the HTML5 specification: SVG The HTML5 specification allows for embedding of Scalable Vector Graphics (SVG) in HTML pages. The use of SVG increases the rendering speed of cus- tom shapes and forms. The Maps API supports the use of SVG icons as cus- tom markers. Geolocation Browsers that offer HTML5 geolocation support are able to share their po- sition on the globe and this means that the Maps API can request the loca- tion details from the browser. On most mobile devices, geolocation detects a user’s position to within a few meters. It is also possible to obtain an ac- curate current position on desktop environments connected to the Inter- net via Wi-Fi, but note that there may be some delay in response, as the Wi- Fi positioning look-up is based on a server request. Positioning look-up and response time vary from browser to browser. The security policy on most browsers does not automatically allow immediate access and a confirmation dialog is shown instead. Please bear this in mind when using the geolocation feature.   Performance The HERE Maps API for JavaScript has been designed to meet the demands of modern Web application development. The common development patterns it implements help improve efficiency and shorten the development cycle.