Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries. Thanks for all your past and future contributions.

HERE Maps API - Geocoordinate system

From Wiki
Jump to: navigation, search

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: HERE Maps 2.2.4
Keywords: Geocoordinates, HERE Maps, JavaScript, latitude, longitude
Created: Maveric (20 Jun 2011)
Updated: avnee.nathani (31 Dec 2011)
Last edited: jasfox (24 Apr 2013)


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.

HERE Maps API Coordinate

In the HERE 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}


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

Suggested Further Reading

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

You may also access the interactive API explorer

This page was last modified on 24 April 2013, at 16:02.
154 page views in the last 30 days.