[ Whereis® API Home ] [ Developers' Guide ]
Physical locations on the earth are defined in terms of latitude and longitude coordinates. These coordinates are correct and consistent when applied to a three-dimensional globe, but not when applied to a two-dimensional map image such as that returned by the EMS API.
The agreed standard for correcting latitude and longitude coordinates to two dimensions, as relied upon for most GPS applications, is the World Geodetic System 84 (WGS84). However, the Whereis API uses a different coordinate system internally for JavaScript maps. Consequently you are required to convert coordinates to and from the WGS84 format as required. The process is set out below.
EMS.LonLat
When you pass a set of coordinates to the JavaScript API for mapping purposes, always construct an EMS.LonLat object unless otherwise stated. You can use any of the following constructors.
new EMS.LonLat(longitude, latitude)
new EMS.LonLat([longitude, latitude]);
new EMS.LonLat({lon: longitude, lat: latitude})
or even:
var wrapped = new OpenLayers.LonLat(longitude, latitude); new EMS.LonLat(wrapped);
where
- longitude: number 113 to 154, required.
- latitude: : number -44 to -9, required.
asWGS84()
If your application needs to get coordinates (in order to display a result or to perform a reverse geocode for a clicked location) convert the coordinates back to the WGS84 standard using:
EMS.LonLat.asWGS84()
Granularity
A centre point takes on a different meaning depending on whether it is intended to represent the centre of property, a suburb, a street, a state, a region, or an intersection. The EMS API can return a geocode object to represent any one of these address types. The "granularity" property distinguishes between them on the basis of scale.
A system where global points are applied to a map is called a "projection". A projection describes the way real points on a globe are "projected" onto a map. There are many different types of projection, but the Whereis API uses a projection called "Spherical Mercator", which is the most common projection for web browser maps.