×
Namespaces

Variants
Actions
(Difference between revisions)

HERE Maps API - Geocoordinate system

From Nokia Developer Wiki
Jump to: navigation, search
hamishwillee (Talk | contribs)
m (Hamishwillee - Add Ovi Maps category)
jasfox (Talk | contribs)
m (Jasfox - update to 2.2.4)
(16 intermediate revisions by 4 users not shown)
Line 1: Line 1:
[[Category:Web]][[Category:Browser]][[Category:Ovi Maps]]
+
[[Category:Nokia Maps]][[Category:JavaScript]]
'''Coordinate systems'''
+
{{Abstract|This article provides clarity on how the geocordinates are defined and how you can use them in your applications.}}
 +
{{ArticleMetaData
 +
|sourcecode= <!-- Link to example source code e.g. [[Media:The Code Example ZIP.zip]] -->
 +
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 +
|devices= Internet Explorer, Firefox, Opera, Google Chrome
 +
|sdk= <!-- SDK(s) built and tested against (e.g. [http://linktosdkdownload/ Nokia Qt SDK 1.1]) -->
 +
|platform= <!-- Compatible platforms - e.g. Symbian^1 and later, Qt 4.6 and later -->
 +
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
 +
|dependencies=Nokia Maps 2.2.4
 +
|signing=<!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
 +
|capabilities=<!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 +
|keywords= Geocoordinates, Nokia Maps, JavaScript, latitude, longitude
 +
|id= <!-- Article Id (Knowledge base articles only) -->
 +
|language=<!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 +
|review-by=<!-- After re-review: [[User:username]] -->
 +
|review-timestamp=<!-- After re-review: YYYYMMDD -->
 +
|update-by=[[User:avnee.nathani]]
 +
|update-timestamp=20111231
 +
|creationdate=20110620
 +
|author=[[User:Maveric]]
 +
}}
 +
==Coordinate systems==
  
 
Everything on a map can be defined by it's geographical position and informed as geographic goordinates. This is done when e.g. search is performed, route calculated, a position geocoded or reverse geocoded or when a Marker is placed on the map.  
 
Everything on a map can be defined by it's geographical position and informed as geographic goordinates. This is done when e.g. search is performed, route calculated, a position geocoded or reverse geocoded or when a Marker is placed on the map.  
Line 8: Line 29:
 
The coordinates of these values are measured in degrees, and represent angular distances calculated from the center of the Earth.   
 
The coordinates of these values are measured in degrees, and represent angular distances calculated from the center of the Earth.   
  
The Earth is a sphere in it's form, and it has an axis that it spins around. The two ends of the axis are North and South Poles.  
+
The Earth is a sphere in it's form, and it has an axis that it spins around. The two ends of the axis are North and South Poles.
  
'''Definition of Latitude'''
+
==Definition of Latitude==
The Equator is a line around the Earth, an equal distance from both poles. Latitude is the Equator, and it is given the value of 0 degrees and is the start point for measuring the latitude. Latitude values indicate the angular distance between the Equator and points north or south of it on the surface of the Earth.  
+
The Equator is a line around the Earth, at equal distance from both poles. Latitude is the Equator, and it is given the value of 0 degrees and is the start point for measuring the latitude. Latitude values indicate the angular distance between the Equator and points north or south of it on the surface of the Earth.  
  
 
A line of latitude is the line that connects all the points with the same latitude value. This is the general term used to refer to the lines representing values in whole degrees. All of the latitude lines are parallel to the Equator, they are sometimes then also referred to as parallels. They are equally spaced. There are 90 degrees of latitude going north from the Equator, and the North Pole is at 90 degrees N. There are 90 degrees to the south of the Equator, and the South Pole is at 90 degrees S. When the directional designators are omitted, northern latitudes are given positive values and southern latitudes are given negative values.   
 
A line of latitude is the line that connects all the points with the same latitude value. This is the general term used to refer to the lines representing values in whole degrees. All of the latitude lines are parallel to the Equator, they are sometimes then also referred to as parallels. They are equally spaced. There are 90 degrees of latitude going north from the Equator, and the North Pole is at 90 degrees N. There are 90 degrees to the south of the Equator, and the South Pole is at 90 degrees S. When the directional designators are omitted, northern latitudes are given positive values and southern latitudes are given negative values.   
  
'''Definition of Longitude'''
+
==Definition of Longitude==
Lines of longitude, called meridians, run perpendicular to lines of latitude, and all pass through both poles. Each longitude line is part of a great circle. There is no obvious 0-degree point for longitude, as there is for latitude. Throughout history many different starting points have been used to measure longitude. By international agreement, the meridian line through Greenwich, England, is currently given the value of 0 degrees of longitude; this meridian is referred to as the Prime Meridian. Longitude values are indicate the angular distance between the Prime Meridian and points east or west of it on the surface of the Earth.
+
Lines of longitude, called meridians, run perpendicular to lines of latitude, and all pass through both poles. Each longitude line is part of a great circle. There is no obvious 0-degree point for longitude, as there is for latitude. Throughout history many different starting points have been used to measure longitude. By international agreement, the meridian line through Greenwich, England, is currently given the value of 0 degrees of longitude; this meridian is referred to as the Prime Meridian. Longitude values indicate the angular distance between the Prime Meridian and points east or west of it on the surface of the Earth.
Graphic of the Earth is divided equally into 360 degrees of longitudeThe Earth is divided equally into 360 degrees of longitude. There are 180 degrees of longitude to the east of the Prime Meridian; when the directional   designator is omitted these longitudes are given positive values. There are also 180 degrees of longitude to the  west of the Prime Meridian; when the directional designator is omitted these longitudes are given negative values. The 180-degree longitude line is opposite the Prime Meridian on the globe, and is the same going either east or west.  
+
The Earth is divided equally into 360 degrees of longitude. There are 180 degrees of longitude to the east of the Prime Meridian; when the directional   designator is omitted these longitudes are given positive values. There are also 180 degrees of longitude to the  west of the Prime Meridian; when the directional designator is omitted these longitudes are given negative values. The 180-degree longitude line is opposite the Prime Meridian on the globe, and is the same going either east or west.  
  
 
Degrees of latitude and longitude can be further subdivided into minutes and seconds: there are 60 minutes (') per degree, and 60 seconds (") per minute. For example, a coordinate might be written 65° 32' 15". Degrees  can also be expressed as decimals: 65.5375, degrees and decimal minutes: 65° 32.25', or even degrees, minutes, and decimal seconds: 65° 32' 15.275". All these notations allow us to locate places on the Earth quite precisely - to within inches.  
 
Degrees of latitude and longitude can be further subdivided into minutes and seconds: there are 60 minutes (') per degree, and 60 seconds (") per minute. For example, a coordinate might be written 65° 32' 15". Degrees  can also be expressed as decimals: 65.5375, degrees and decimal minutes: 65° 32.25', or even degrees, minutes, and decimal seconds: 65° 32' 15.275". All these notations allow us to locate places on the Earth quite precisely - to within inches.  
Line 24: Line 45:
 
A degree of longitude varies in size. At the equator, it is approximately 69 miles, the same size as a degree of  latitude. The size gradually decreases to zero as the meridians converge at the poles. At a latitude of 45 degrees, a degree of longitude is approximately 49 miles. Because a degree of longitude varies in size, minutes and seconds of longitude also vary, decreasing in size towards the poles.  
 
A degree of longitude varies in size. At the equator, it is approximately 69 miles, the same size as a degree of  latitude. The size gradually decreases to zero as the meridians converge at the poles. At a latitude of 45 degrees, a degree of longitude is approximately 49 miles. Because a degree of longitude varies in size, minutes and seconds of longitude also vary, decreasing in size towards the poles.  
  
'''Ovi Maps API Coordinate'''
+
==Nokia Maps API Coordinate==
  
In the Ovi Maps API a new instance of a coordinate object is defined as follows:
+
In the Nokia Maps API a new instance of a coordinate object is defined as follows:
  
 
<code java>
 
<code java>
   new ovi.mapsapi.geo.Coordinate (lat, lng, [alt, [skipValidation]])
+
   new nokia.maps.geo.Coordinate (lat, lng, [alt, [skipValidation]])
 
</code>
 
</code>
  
 
Note: As most of the use cases currently do not consider height information, the altitude is defined as optional. If a corresponding type is already provided by the platform the product must not implement this class.  
 
Note: As most of the use cases currently do not consider height information, the altitude is defined as optional. If a corresponding type is already provided by the platform the product must not implement this class.  
 
    
 
    
'''Create a new coordinate:'''
+
==='Create a new coordinate===
 
   
 
   
In the following, "myCoord" would be a new coordinate object with latitude value of 50.1, longitude value of 13.2 and height value of 3000 and would not be validated.
+
In the following, "myCoord" would be a new coordinate object with latitude value of 50.1, longitude value of 13.2 and height value of 3000, and would not be validated.
  
 
<code java>
 
<code java>
>>> myCoord = new ovi.mapsapi.geo.Coordinate (50.1, 13.2, 3000, false);  
+
>>> myCoord = new nokia.maps.geo.Coordinate (50.1, 13.2, 3000, false);  
 
</code>
 
</code>
  
 
This would read out:  
 
This would read out:  
 
'''50° 6' 0" N, 13° 11' 60" E { longitude=13.2, latitude=50.1, altitude=3000}'''  
 
'''50° 6' 0" N, 13° 11' 60" E { longitude=13.2, latitude=50.1, altitude=3000}'''  
Latitude and longitude provided in decimal format (50.1, 13.2) can be also stored and displayed in a more "readable", which can be achieved by using the toString method as follows:  
+
Latitude and longitude provided in decimal notation (50.1, 13.2) can be also stored and displayed in a more "readable" format, which can be achieved by using the toString method as follows:  
 
   
 
   
 
<code java>  
 
<code java>  
Line 56: Line 77:
  
 
<code java>
 
<code java>
>>> myCoord = new ovi.mapsapi.geo.Coordinate (190.1, 200.2);
+
>>> myCoord = new nokia.maps.geo.Coordinate (190.1, 200.2);
 
</code>
 
</code>
  
Line 63: Line 84:
 
    
 
    
 
<code java>
 
<code java>
>>> MyCoordTwo = new ovi.mapsapi.geo.Coordinate (50.1, 13.2)
+
>>> MyCoordTwo = new nokia.maps.geo.Coordinate (50.1, 13.2)
 
</code>   
 
</code>   
  
Line 70: Line 91:
 
    
 
    
 
<code java>
 
<code java>
>>> MyCoordOne = new ovi.mapsapi.geo.Coordinate (50.1, 13.2)
+
>>> MyCoordOne = new nokia.maps.geo.Coordinate (50.1, 13.2)
 
</code>
 
</code>
  
Line 88: Line 109:
 
   
 
   
 
<code java>
 
<code java>
walk (heading, distance) : ovi.mapsapi.geo.Coordinate   
+
walk (heading, distance) : nokia.maps.geo.Coordinate   
 
</code>
 
</code>
  
Line 102: Line 123:
 
==Summary==
 
==Summary==
  
This article was written to provide some clarity perhaps on how the geocoordinates are defined and how the Ovi Maps API uses them
+
This article was written to provide some clarity on how geocoordinates are defined and how the Nokia Maps API uses them
and how you can take them into use for your mapping applications.  
+
and how you can use them in your mapping applications.  
  
==Suggested further reading==
+
==Suggested Further Reading==
  
For more; Ovi Maps API Reference, online code playground and API documentation with online examples, goto:
+
Please check out the Nokia Maps API full documentation and API reference here:
 +
* [http://developer.here.net/javascript_api Nokia Maps API]
  
http://api.maps.ovi.com
+
You may also access the interactive API explorer
 
+
* [http://developer.here.net/javascript_api_explorer API explorer]
==Tested on==
+
 
+
Mozilla Firefox 4.0.1
+

Revision as of 14:24, 14 March 2013

This article provides clarity on how the geocordinates are defined and how you can use them in your applications.

Article Metadata
Tested with
Devices(s): Internet Explorer, Firefox, Opera, Google Chrome
Dependencies: Nokia Maps 2.2.4
Article
Keywords: Geocoordinates, Nokia Maps, JavaScript, latitude, longitude
Created: Maveric (20 Jun 2011)
Updated: avnee.nathani (31 Dec 2011)
Last edited: jasfox (14 Mar 2013)

Contents

Coordinate systems

Everything on a map can be defined by it's geographical position and informed as geographic goordinates. This is done when e.g. search is performed, route calculated, a position geocoded or reverse geocoded or when a Marker is placed on the map.

The two values used by the mapping to represent a position on the map, are latitude and longitude.

The coordinates of these values are measured in degrees, and represent angular distances calculated from the center of the Earth.

The Earth is a sphere in it's form, and it has an axis that it spins around. The two ends of the axis are North and South Poles.

Definition of Latitude

The Equator is a line around the Earth, at equal distance from both poles. Latitude is the Equator, and it is given the value of 0 degrees and is the start point for measuring the latitude. Latitude values indicate the angular distance between the Equator and points north or south of it on the surface of the Earth.

A line of latitude is the line that connects all the points with the same latitude value. This is the general term used to refer to the lines representing values in whole degrees. All of the latitude lines are parallel to the Equator, they are sometimes then also referred to as parallels. They are equally spaced. There are 90 degrees of latitude going north from the Equator, and the North Pole is at 90 degrees N. There are 90 degrees to the south of the Equator, and the South Pole is at 90 degrees S. When the directional designators are omitted, northern latitudes are given positive values and southern latitudes are given negative values.

Definition of Longitude

Lines of longitude, called meridians, run perpendicular to lines of latitude, and all pass through both poles. Each longitude line is part of a great circle. There is no obvious 0-degree point for longitude, as there is for latitude. Throughout history many different starting points have been used to measure longitude. By international agreement, the meridian line through Greenwich, England, is currently given the value of 0 degrees of longitude; this meridian is referred to as the Prime Meridian. Longitude values indicate the angular distance between the Prime Meridian and points east or west of it on the surface of the Earth. The Earth is divided equally into 360 degrees of longitude. There are 180 degrees of longitude to the east of the Prime Meridian; when the directional designator is omitted these longitudes are given positive values. There are also 180 degrees of longitude to the west of the Prime Meridian; when the directional designator is omitted these longitudes are given negative values. The 180-degree longitude line is opposite the Prime Meridian on the globe, and is the same going either east or west.

Degrees of latitude and longitude can be further subdivided into minutes and seconds: there are 60 minutes (') per degree, and 60 seconds (") per minute. For example, a coordinate might be written 65° 32' 15". Degrees can also be expressed as decimals: 65.5375, degrees and decimal minutes: 65° 32.25', or even degrees, minutes, and decimal seconds: 65° 32' 15.275". All these notations allow us to locate places on the Earth quite precisely - to within inches. A degree of latitude is approximately 69 miles, and a minute of latitude is approximately 1.15 miles. A second of latitude is approximately 0.02 miles, or just over 100 feet.

A degree of longitude varies in size. At the equator, it is approximately 69 miles, the same size as a degree of latitude. The size gradually decreases to zero as the meridians converge at the poles. At a latitude of 45 degrees, a degree of longitude is approximately 49 miles. Because a degree of longitude varies in size, minutes and seconds of longitude also vary, decreasing in size towards the poles.

Nokia Maps API Coordinate

In the Nokia Maps API a new instance of a coordinate object is defined as follows:

   new nokia.maps.geo.Coordinate (lat, lng, [alt, [skipValidation]])

Note: As most of the use cases currently do not consider height information, the altitude is defined as optional. If a corresponding type is already provided by the platform the product must not implement this class.

'Create a new coordinate

In the following, "myCoord" would be a new coordinate object with latitude value of 50.1, longitude value of 13.2 and height value of 3000, and would not be validated.

>>> myCoord = new nokia.maps.geo.Coordinate (50.1, 13.2, 3000, false);

This would read out: 50° 6' 0" N, 13° 11' 60" E { longitude=13.2, latitude=50.1, altitude=3000} Latitude and longitude provided in decimal notation (50.1, 13.2) can be also stored and displayed in a more "readable" format, which can be achieved by using the toString method as follows:

>>> myCoord.toString()

...and would read as: "50° 6' 0" N, 13° 11' 60" E" Note: All degree values must be in range of latitude -180 <= longitude <= 180. Values outside of range throw IllegalArgument error e.g.

>>> myCoord = new nokia.maps.geo.Coordinate (190.1, 200.2);

"IllegalArgument: Coordinate: given arguments [190.1,200.2] are not valid" To check if two coordinates are equal, the method equals can be used:

>>> MyCoordTwo = new nokia.maps.geo.Coordinate (50.1, 13.2)

...this would read out: 50° 6' 0" N, 13° 11' 60" E { longitude=13.2, latitude=50.1 }

>>> MyCoordOne = new nokia.maps.geo.Coordinate (50.1, 13.2)

Would give: 50° 6' 0" N, 13° 11' 60" E { longitude=13.2, latitude=50.1 }

To check if two coordinates are equal we would use the "equals" method:

>>> MyCoordOne.equals(MyCoordTwo);

This would display as: true

The walk method is meant for calculating a new geo coordinate by traveling a given distance by a specific heading and defined as follows:

walk (heading, distance) : nokia.maps.geo.Coordinate

Example when used on the previously created MyCoordOne:

>>> result = MyCoordOne.walk(90, 5000)

The readout would give: 50° 6' 0" N, 13° 16' 12" E { longitude=13.270100698289994, latitude=50.09997889702792}

Summary

This article was written to provide some clarity on how geocoordinates are defined and how the Nokia Maps API uses them and how you can use them in your mapping applications.

Suggested Further Reading

Please check out the Nokia Maps API full documentation and API reference here:

You may also access the interactive API explorer

163 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×