Overview

What Is the Maps API for JavaScript?

The Nokia Maps API for JavaScript (the Maps API) is a set of programming interfaces that enable developers to build Web applications with feature rich, interactive Nokia 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 Playground 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 Nokia Maps API for JavaScript
Feature	Description
Nokia 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.

Packages and Detection

The Nokia Maps API 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). 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 Maps API
URL Parameter	Allowed Values [1]	Default
`with`	`maps`, `positioning`, `places` [2], `placesdata` [2], `directions`, `datarendering`, `all` [4]	`maps` [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]	equivalent to "with=maps,placesdata", which loads the Maps library package and the Places data-only library package, not the Places UI library
[4]	`all` loads all the available libraries

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" 
"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" /> 
        <script type="text/javascript" 
            src="http://api.maps.nokia.com/2.2.4/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 Nokia 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
Opera 10+	desktop and mobile*

* support does not extend to all multi-touch gestures

The table above does not imply that the Maps API can be used only on the platforms it lists. If you are developing for a platform not shown in the table, we suggest that you test your application thoroughly in the target environment and report any issues via our Discussion Board.

HTML5 Support

Although HTML5 is a new emerging HTML standard, and as such it is still undergoing continual improvement, the Nokia Maps API 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:

Canvas: When the <canvas> element is detected, the Maps API enables fast rendering of custom shapes, forms, and images. When hardware acceleration is used, as is the case in many modern desktop and mobile browsers, the performance gain is even greater. The API auto detects <canvas> support by default and performs all rendering activities using <canvas> where possible.
SVG: The HTML5 specification allows for embedding of Scalable Vector Graphics (SVG) in HTML pages. The use of SVG increases the rendering speed of custom shapes and forms. The Maps API supports the use of SVG icons as custom markers.
Geolocation: Browsers that offer HTML5 geolocation support are able to share their position on the globe and this means that the Maps API can request the location 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 accurate current position on desktop environments connected to the Internet 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 Nokia Maps API 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.

Fast start-up: The Nokia Maps API is outstanding in terms of memory consumption due to the small size of the underlying JavaScript framework. The map starts fast and the content loads smoothly.
Fast loading: The Nokia Maps API provides packaged and lazy loading of features such as route and search – and even of the map data itself. The content is downloaded from the server only when needed.
Fast browsing: The Nokia Maps API supports in-built browser caching. Once the content has been downloaded from the server, it is reused as much as possible to minimize bandwidth usage.

Licensing

Nokia's Maps API for JavaScript is free to use under the Nokia Maps API terms and conditions and subject to limitations set out on the Nokia Location Platform page http://www.developer.nokia.com/Develop/Maps/Quota/. This site also outlines alternative licensing options for developers. Please note that the use of any of the Nokia Location Platform APIs must be accompanied by authentication credentials. For information on how to obtain the credentials, please see Acquiring Credentials.