Maps API for JavaScript - HERE Developers

755 Pages·2013·8.54 MB·English

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.