×
Namespaces

Variants
Actions
(Difference between revisions)

HERE Maps API - Geocoordinate system

From Nokia Developer Wiki
Jump to: navigation, search
Maveric (Talk | contribs)
(Maveric -)
 
Maveric (Talk | contribs)
m (Maveric -)
Line 3: Line 3:
  
 
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.  
 +
 
The two values used by the mapping to represent a position on the map, are latitude and longitude.  
 
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 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, 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.  
 +
 
 
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 are 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.  
 
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.  
 +
 
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.  
 
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 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.  
 
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.  
  
Line 26: Line 33:
  
 
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:'''  
Line 33: Line 39:
  
 
<code java>
 
<code java>
 
 
>>> myCoord = new ovi.mapsapi.geo.Coordinate (50.1, 13.2, 3000, false);  
 
>>> myCoord = new ovi.mapsapi.geo.Coordinate (50.1, 13.2, 3000, false);  
 
</code>
 
</code>
Line 53: Line 58:
 
>>> myCoord = new ovi.mapsapi.geo.Coordinate (190.1, 200.2);
 
>>> myCoord = new ovi.mapsapi.geo.Coordinate (190.1, 200.2);
 
</code>
 
</code>
 +
 
'''"IllegalArgument: Coordinate: given arguments [190.1,200.2] are not valid"'''  
 
'''"IllegalArgument: Coordinate: given arguments [190.1,200.2] are not valid"'''  
 
To check if two coordinates are equal, the method equals can be used:  
 
To check if two coordinates are equal, the method equals can be used:  
 
    
 
    
 
<code java>
 
<code java>
 
 
>>> MyCoordTwo = new ovi.mapsapi.geo.Coordinate (50.1, 13.2)
 
>>> MyCoordTwo = new ovi.mapsapi.geo.Coordinate (50.1, 13.2)
 
</code>   
 
</code>   
  
 
...this would read out:
 
...this would read out:
 
 
 
'''50° 6' 0" N, 13° 11' 60" E { longitude=13.2, latitude=50.1 }'''  
 
'''50° 6' 0" N, 13° 11' 60" E { longitude=13.2, latitude=50.1 }'''  
 
    
 
    
 
<code java>
 
<code java>
 
 
>>> MyCoordOne = new ovi.mapsapi.geo.Coordinate (50.1, 13.2)
 
>>> MyCoordOne = new ovi.mapsapi.geo.Coordinate (50.1, 13.2)
50° 6' 0" N, 13° 11' 60" E { longitude=13.2, latitude=50.1 }  
+
</code>
 +
 
 +
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:
 
To check if two coordinates are equal we would use the "equals" method:
  
 
<code java>
 
<code java>
 
 
>>> MyCoordOne.equals(MyCoordTwo);
 
>>> MyCoordOne.equals(MyCoordTwo);
 
</code>
 
</code>
Line 80: Line 84:
 
This would display as:
 
This would display as:
 
'''true'''  
 
'''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:
 
The '''walk''' method is meant for calculating a new geo coordinate by traveling a given distance by a specific heading and defined as follows:
 
   
 
   
 
<code java>
 
<code java>
 
 
walk (heading, distance) : ovi.mapsapi.geo.Coordinate   
 
walk (heading, distance) : ovi.mapsapi.geo.Coordinate   
 
</code>
 
</code>
Line 95: Line 99:
 
The readout would give:
 
The readout would give:
 
50° 6' 0" N, 13° 16' 12" E { longitude=13.270100698289994, latitude=50.09997889702792}
 
50° 6' 0" N, 13° 16' 12" E { longitude=13.270100698289994, latitude=50.09997889702792}
 +
 
==Summary==
 
==Summary==
  

Revision as of 10:05, 20 June 2011

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, 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.

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 are 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.

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.

Ovi Maps API Coordinate

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

   new ovi.mapsapi.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 ovi.mapsapi.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 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:

>>> 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 ovi.mapsapi.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 ovi.mapsapi.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 ovi.mapsapi.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) : ovi.mapsapi.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 perhaps on how the geocoordinates are defined and how the Ovi Maps API uses them and how you can take them into use for your mapping applications.

Suggested further reading

For more; Ovi Maps API Reference, online code playground and API documentation with online examples, goto:

http://api.maps.ovi.com

Tested on

Mozilla Firefox 4.0.1

263 page views in the last 30 days.
×