×
Namespaces

Variants
Actions
(Difference between revisions)

Archived:HERE Maps API - Passing Query Parameters

From Nokia Developer Wiki
Jump to: navigation, search
jasfox (Talk | contribs)
m (Jasfox - Avoid time travel.)
jasfox (Talk | contribs)
m (Jasfox - Correct Meta data.)
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Category:Nokia Maps]][[Category:Code Snippet]][[Category:JavaScript]]
+
[[Category:Nokia Maps]][[Category:Code Snippet]][[Category:JavaScript]][[Category:Code Examples]]
{{Abstract|This article explains how to read in query parameters to display a map at a known location, and define links to both the main http://maps.nokia.com website  and the mobile HTML5 website http://m.maps.nokia.com . It is an example of the use of both Geocoding and Reverse Geocoding.}}  
+
{{Archived|timestamp=20120420151019|user=[[User:Jasfox|Jasfox]]|Equivalent deeplinks are now available directly within the Nokia Maps website itself, for example see : [http://maps.nokia.com/whereis/New%20York http://maps.nokia.com/whereis/New York]. For further details read the blog entry [http://www.developer.nokia.com/Community/Blogs/blog/web-dev/2012/04/19/new-nokia-maps-api-url here]}}
  
{{ArticleMetaData
+
{{Abstract|This article explains how to read in query parameters to display a map at a known location, and define links to both the main http://maps.nokia.com website and the mobile HTML5 website http://m.maps.nokia.com . It is an example of the use of both Geocoding and Reverse Geocoding.}}
|sourcecode= [[Media:querystringexample.zip]]  
+
 
 +
 
 +
 
 +
{{ArticleMetaData  
 +
|sourcecode= [[Media:querystringexample.zip]]
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 
|devices= Google Chrome 16.0.912
 
|devices= Google Chrome 16.0.912
Line 9: Line 13:
 
|platform= Web Browser
 
|platform= Web Browser
 
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
 
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->
+
|dependencies= Nokia Maps API 2.2.0
|signing=<!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
+
|signing= <!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
 
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 
|keywords= Nokia Maps, JavaScript
 
|keywords= Nokia Maps, JavaScript
|id= <!-- Article Id (Knowledge base articles only) -->
 
 
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 
|translated-by= <!-- [[User:XXXX]] -->
 
|translated-by= <!-- [[User:XXXX]] -->
|translated-from-title= <!-- Title only -->  
+
|translated-from-title= <!-- Title only -->
 
|translated-from-id= <!-- Id of translated revision -->
 
|translated-from-id= <!-- Id of translated revision -->
|review-by=<!-- After re-review: [[User:username]] -->
+
|review-by= <!-- After re-review: [[User:username]] -->
 
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 
|update-by= <!-- After significant update: [[User:username]]-->
 
|update-by= <!-- After significant update: [[User:username]]-->
 
|update-timestamp= <!-- After significant update: YYYYMMDD -->
 
|update-timestamp= <!-- After significant update: YYYYMMDD -->
|creationdate=20120207
+
|creationdate= 20120207
|author=[[User:jasfox]]
+
|author= [[User:jasfox]]
 
}}
 
}}
 +
 +
{{SeeAlso|
 +
*  [http://api.maps.nokia.com/ Nokia Maps API]
 +
* [http://api.maps.nokia.com/en/playground/examples/maps/services/addresses.html Search example]
 +
* [http://www.developer.nokia.com/Community/Blogs/blog/web-dev/2012/04/19/new-nokia-maps-api-url-creation Deep linking in Nokia Maps]
 +
}}
  
 
== Introduction ==
 
== Introduction ==
It is sometimes useful to be able to supply a link to an '''interactive''' map of a known location using the [http://api.maps.nokia.com/ Nokia Maps API]  in the same manner as the [http://www.developer.nokia.com/Develop/Maps/Map_Image_API Map Image API] does for static maps.
+
It is sometimes useful to be able to supply a link to an '''interactive''' map of a known location using the [http://api.maps.nokia.com/ Nokia Maps API]  in the same manner as the [http://api.maps.nokia.com/en/restmaps/overview.html RESTful Map API] does for static maps.
This could be done to allow your user to make a search or a routing request on the ready-made http://maps.nokia.com website for example. Alternatively if your user is using an Android or iPhone, you wish to forward them to the mobile HTML5 website http://m.maps.nokia.com , so they can still
+
This could be done to allow your user to make a search or a routing request on the ready-made http://maps.nokia.com website for example. Alternatively if your user is using an Android or iPhone, you wish to forward them to the mobile HTML5 website http://m.maps.nokia.com, so they can still
 
access Nokia Maps. Currently neither of these websites websites offers an API directly, but since they both use the same services as the Nokia Maps API, it is relatively simple task to create a query-string-based web page which creates URLs of an appropriate format for these websites to consume.
 
access Nokia Maps. Currently neither of these websites websites offers an API directly, but since they both use the same services as the Nokia Maps API, it is relatively simple task to create a query-string-based web page which creates URLs of an appropriate format for these websites to consume.
  
Line 34: Line 43:
  
 
=== Defining a Minimal set of Query String Parameters ===
 
=== Defining a Minimal set of Query String Parameters ===
The URL of an http  "Get"' request consists of the path to a file location followed by a query string. The query string contains the parameters which are passed to the page. The [http://www.developer.nokia.com/Develop/Maps/Map_Image_API Map Image API] documentation contains a multitude of parameters for modifying a map. This example will replicate some of the major request parameters defining the location of a map.
+
The URL of an http  "Get"' request consists of the path to a file location followed by a query string. The query string contains the parameters which are passed to the page. The [http://api.maps.nokia.com/en/restmaps/overview.html RESTful Map API] documentation contains a multitude of parameters for modifying a map. This example will replicate some of the major request parameters defining the location of a map.
  
* A pair of parameters for defining the longitude  '''long''' and latitude  '''lat''' at the center of the map. This can be used for reverse geocoding.
+
* A pair of parameters for defining the longitude  '''long''' and latitude  '''lat''' at the center of the map. This can be used for reverse geocoding.
 
* A free text address '''address''' to define the location at the center of the map. This can be used for geocoding.
 
* A free text address '''address''' to define the location at the center of the map. This can be used for geocoding.
* A zoom level '''zoom''' for the map.
+
* A {{Icode|zoomLevel}} '''zoom''' for the map.
* Some associated free text '''name'''  to display on the map. Obviously additional parameters can be added in the same manner.
+
* Some associated free text '''name'''  to display on the map. Obviously additional parameters can be added in the same manner.
  
 
== How to read query string parameters ==
 
== How to read query string parameters ==
Line 53: Line 62:
 
var key = parms[i].substring(0,pos);
 
var key = parms[i].substring(0,pos);
 
var val = parms[i].substring(pos+1);
 
var val = parms[i].substring(pos+1);
param[key] = val;
+
param[key] = decodeURI(val);
 
}
 
}
 
}
 
}
Line 86: Line 95:
 
== How to generate links to maps.nokia.com and m.maps.nokia.com ==
 
== How to generate links to maps.nokia.com and m.maps.nokia.com ==
  
Depending upon the parameters passed we may have a latitude, longitude or alternatively we may have an address. We need '''both''' in order to create a link to  [http://m.maps.nokia.com m.maps.nokia.com]  . Therefore we need to create a search manager and either
+
Depending upon the parameters passed we may have a latitude, longitude or alternatively we may have an address. We need '''both''' in order to create a link to  [http://m.maps.nokia.com m.maps.nokia.com]  . Therefore we need to create use the {{Icode|nokia.places.search.manager}} and either make a {{Icode|geocode()}} request or a {{Icode|reverseGeoCode()}} request as necessary.
do a ''geocode()'' request or ''reverseGeocode()'' as necessary.
+
  
 
<code javascript>
 
<code javascript>
 
var locName = param['name'];
 
var locName = param['name'];
var addressQuery = unescape(param['address']);
+
var addressQuery = param['address'];
 
 
 
if (addressQuery !=  ""){
 
if (addressQuery !=  ""){
     searchManager.geocode(addressQuery);     
+
     nokia.places.search.manager.geoCode({
 +
                searchTerm : addressQuery,
 +
                onComplete: processResults
 +
            });     
 
} else {
 
} else {
     searchManager.reverseGeocode(center);
+
     nokia.places.search.manager.reverseGeoCode({
 +
                latitude : center.latitude,
 +
                longitude : center.longitude,
 +
                onComplete: processResults
 +
            });  
 
}
 
}
 
</code>
 
</code>
  
The search manager needs build up the address if necessary (this has been removed for brevity - check the [[Media:querystringexample.zip|coded example]]) , and then pass the location and address for further processing.
+
The callback function {{Icode|processResults()}} needs build up the address if necessary (this has been removed for brevity - check the [[Media:querystringexample.zip|coded example]]) , and then pass the location and address for further processing.
 
<code javascript>
 
<code javascript>
var searchManager = new nokia.maps.search.Manager();
+
var processResults = function (data, requestStatus) {
  searchManager.addObserver("state", function (observedManager, key, value) {
+
         // If the search has finished we can process the results      
         // If the search has finished we can process the results
+
         if (requestStatus == "OK") {
         if (value == "finished") {
+
              if (observedManager.locations.length > 0) {
+
 
///... build up address if necessary
 
///... build up address if necessary
 
if (addressQuery != ""){
 
if (addressQuery != ""){
 
                                 // This is a geocode request, center on the location
 
                                 // This is a geocode request, center on the location
addMarker(locName, observedManager.locations[0].address.label, observedManager.locations[0].displayPosition);
+
addMarker(locName, addressQuery, data.location.position);
map.setCenter(observedManager.locations[0].displayPosition);
+
map.setCenter(data.location.position);
 
} else {
 
} else {
 
                               // This is a reverse geocode request, center is already correct.
 
                               // This is a reverse geocode request, center is already correct.
Line 118: Line 131:
 
 
 
}
 
}
} else if (value == "failed") {
+
} else if (requestStatus == "ERROR") {
addMarker(locName, "", center);
+
addMarker(locName, "", center);
}
+
}
 
   });
 
   });
 
</code>
 
</code>
  
The ''addMarker()'' function creates and adds the necessary links to an info bubble.  The links are defined in the ''getNokiaMapsHTML5Link()'' and  ''getNokiaMapsLink()'' functions.
+
The {{Icode|addMarker()}} function creates and adds the necessary links to an info bubble.  The links are defined in the {{Icode|getNokiaMapsHTML5Link()}} and  {{Icode|getNokiaMapsLink()}} methods.
 
<code javascript>
 
<code javascript>
 
   var infoBubbles = new nokia.maps.map.component.InfoBubbles();
 
   var infoBubbles = new nokia.maps.map.component.InfoBubbles();
Line 156: Line 169:
 
</code>
 
</code>
  
== How to forward directly to m.maps.nokia.com ==
+
== How to forward directly to m.maps.nokia.com ==
  
 
{{Note|Not all phones or web browsers are able to use the [http://m.maps.nokia.com m.maps.nokia.com] website. }}
 
{{Note|Not all phones or web browsers are able to use the [http://m.maps.nokia.com m.maps.nokia.com] website. }}
Once a URL of a link has been calculated,  it is a trivial matter to change the code from displaying that link to forwarding a user on to that URL. Just use ''window.location'' as shown:
+
Once a URL of a link has been calculated,  it is a trivial matter to change the code from displaying that link to forwarding a user on to that URL. Just use {{Icode|window.location}} as shown:
 
<code javascript>window.location=url_of_the_new_location</code>
 
<code javascript>window.location=url_of_the_new_location</code>
  
 
== The coded example ==
 
== The coded example ==
 
The  [[Media:querystringexample.zip|coded example]] consists of two files:
 
The  [[Media:querystringexample.zip|coded example]] consists of two files:
''location_query_string.html'' - displays the map of an arbitrary location based upon the query string parameters.
+
{{Icode|location_query_string.html}} - displays the map of an arbitrary location based upon the query string parameters.
''forward_query_string.html'' - forwards directly to the mobile HTML5 website. This could be used as a link in a phone app for examle.
+
{{Icode|forward_query_string.html}} - forwards directly to the mobile HTML5 website. This could be used as a link in a phone app for example.

Revision as of 11:10, 5 December 2012

Archived.pngArchived: This article is archived because it is not considered relevant for third-party developers creating commercial solutions today. If you think this article is still relevant, let us know by adding the template {{ReviewForRemovalFromArchive|user=~~~~|write your reason here}}.

Equivalent deeplinks are now available directly within the Nokia Maps website itself, for example see : http://maps.nokia.com/whereis/New York. For further details read the blog entry here

This article explains how to read in query parameters to display a map at a known location, and define links to both the main http://maps.nokia.com website and the mobile HTML5 website http://m.maps.nokia.com . It is an example of the use of both Geocoding and Reverse Geocoding.


Article Metadata
Code ExampleTested with
Devices(s): Google Chrome 16.0.912
Compatibility
Platform(s): Web Browser
Dependencies: Nokia Maps API 2.2.0
Article
Keywords: Nokia Maps, JavaScript
Created: jasfox (07 Feb 2012)
Last edited: jasfox (05 Dec 2012)

Contents

Introduction

It is sometimes useful to be able to supply a link to an interactive map of a known location using the Nokia Maps API in the same manner as the RESTful Map API does for static maps. This could be done to allow your user to make a search or a routing request on the ready-made http://maps.nokia.com website for example. Alternatively if your user is using an Android or iPhone, you wish to forward them to the mobile HTML5 website http://m.maps.nokia.com, so they can still access Nokia Maps. Currently neither of these websites websites offers an API directly, but since they both use the same services as the Nokia Maps API, it is relatively simple task to create a query-string-based web page which creates URLs of an appropriate format for these websites to consume.

Querystring.png

Defining a Minimal set of Query String Parameters

The URL of an http "Get"' request consists of the path to a file location followed by a query string. The query string contains the parameters which are passed to the page. The RESTful Map API documentation contains a multitude of parameters for modifying a map. This example will replicate some of the major request parameters defining the location of a map.

  • A pair of parameters for defining the longitude long and latitude lat at the center of the map. This can be used for reverse geocoding.
  • A free text address address to define the location at the center of the map. This can be used for geocoding.
  • A zoomLevel zoom for the map.
  • Some associated free text name to display on the map. Obviously additional parameters can be added in the same manner.

How to read query string parameters

The parsing of the query string is absolutely the first thing that must be done even before setting up the map. This can be done with a standard library function as shown below:

function splitQueryString() {
var query = window.location.search.substring(1);
var parms = query.split('&');
for (var i=0; i<parms.length; i++) {
var pos = parms[i].indexOf('=');
if (pos > 0) {
var key = parms[i].substring(0,pos);
var val = parms[i].substring(pos+1);
param[key] = decodeURI(val);
}
}
}

Sensible defaults can be added to the parameters - in this case we are defaulting to display a map of Sydney, Australia. The default values can then be overwritten by reading in the actual values from the query string.

var param = new Array();
param['long'] = "151.211111";
param['lat'] = "-33.859972";
param['name'] = "";
param['zoom'] = "14"; // Default Zoom
param['address'] = "";
splitQueryString();

Displaying a map with query string parameters

Having obtained a latitude. longitude and zoom level, the initial map can be set up in the usual manner:

 
var center = new nokia.maps.geo.Coordinate(parseFloat(param['lat']), parseFloat(param['long']));
var map = new nokia.maps.map.Display(mapContainer, {
// initial center and zoom level of the map
center: center,
zoomLevel: param['zoom'],
components: [ etc ....


How to generate links to maps.nokia.com and m.maps.nokia.com

Depending upon the parameters passed we may have a latitude, longitude or alternatively we may have an address. We need both in order to create a link to m.maps.nokia.com . Therefore we need to create use the nokia.places.search.manager and either make a geocode() request or a reverseGeoCode() request as necessary.

var locName = 	param['name'];
var addressQuery = param['address'];
 
if (addressQuery != ""){
nokia.places.search.manager.geoCode({
searchTerm : addressQuery,
onComplete: processResults
});
} else {
nokia.places.search.manager.reverseGeoCode({
latitude : center.latitude,
longitude : center.longitude,
onComplete: processResults
});
}

The callback function processResults() needs build up the address if necessary (this has been removed for brevity - check the coded example) , and then pass the location and address for further processing.

var processResults = function (data, requestStatus) {
// If the search has finished we can process the results
if (requestStatus == "OK") {
///... build up address if necessary
if (addressQuery != ""){
// This is a geocode request, center on the location
addMarker(locName, addressQuery, data.location.position);
map.setCenter(data.location.position);
} else {
// This is a reverse geocode request, center is already correct.
addMarker(locName, addressText, center);
}
 
}
} else if (requestStatus == "ERROR") {
addMarker(locName, "", center);
}
});

The addMarker() function creates and adds the necessary links to an info bubble. The links are defined in the getNokiaMapsHTML5Link() and getNokiaMapsLink() methods.

  var infoBubbles = new nokia.maps.map.component.InfoBubbles();
map.addComponent( infoBubbles);
 
function addMarker(locName, address, coordinate){
var marker = new nokia.maps.map.StandardMarker(coordinate, {
$html: "<h2>" + unescape(locName) + "</h2><br/>"
+ getNokiaMapsHTML5Link(address, coordinate) + "<br/>"
+ getNokiaMapsLink(coordinate)
});
 
marker.addListener("click" , function(evt) {
infoBubbles.addBubble(evt.target.$html, evt.target.coordinate);
currentMarker = evt.target;
}, false);
 
// Add the markers to the map's object collection so they will be rendered onto the map.
map.objects.add(marker);
}
 
function getNokiaMapsHTML5Link(address, coordinate ){
return "<a href='http://m.maps.nokia.com/#action=search&params={%22id%22:%22826gcpvj-8a33c3c9e61545eda32879b880d3c96f%22,%22query%22:%22" +
escape(address) + "%22,%22slatitude%22:" + coordinate.latitude + ",%22slongitude%22:" + coordinate.longitude + "}&bmk=1'>HMTL 5 Mobile Website</a>";
}
 
function getNokiaMapsLink (coordinate){
return "<a href='http://maps.nokia.com/services/#|" + coordinate.latitude + "|" + coordinate.longitude +
"|" + map.get('zoomLevel') + "|0|0|normal.day'>Nokia Maps website</a>";
}

How to forward directly to m.maps.nokia.com

Note.pngNote: Not all phones or web browsers are able to use the m.maps.nokia.com website.

Once a URL of a link has been calculated, it is a trivial matter to change the code from displaying that link to forwarding a user on to that URL. Just use window.location as shown:

window.location=url_of_the_new_location

The coded example

The coded example consists of two files:

  • location_query_string.html - displays the map of an arbitrary location based upon the query string parameters.
  • forward_query_string.html - forwards directly to the mobile HTML5 website. This could be used as a link in a phone app for example.
123 page views in the last 30 days.
×