[ Whereis® API Home ] [ Developers' Guide ] [ JS Services ]
Mapping applications work with a location in terms of its latitude and longitude coordinates. End-users typically describe the same location in terms of its street address.
The Geocoding service provides a means of converting street address to a set of coordinates and vice versa. Two methods are available on this service:
- geocode(query, callback) to return coordinates for an address, which may be submitted as a string or as a structured address object
- reverse(query, callback) to return an address for a set of coordinates, which may be submitted as an EMS.LonLat object, a hashtable with "lon" or "lat" properties, or in as a full request object (described in the JSON API).
To geocode a location, perform the following steps.
- Initialise the Geocoding service.
- Format the request.
- Submit the request, nominating a callback function.
If the request succeeds, the API returns a list of Geocode objects.
4. Process the response within the callback function.
A successful request returns a list of results. In some cases the list may be empty or may contain only one result at index[0]. Whether geocoding or reverse-geocoding, a Geocode object is returned, which includes both the coordinates and the address for the location.
Sample request
The following code snippet performs a geocode and retrieves the first usable result.
//Initialise service
var service = new EMS.Service.Geocode();
//Format request
var query = "55 Lonsdale Street, Melbourne";
//Submit request
service.geocode(query, callback);
//Handle the response
function callback (response, status){
// Check the status of the result is non-error
if (status == EMS.Status.OK) {
// Success! check the results
var items = response.results;
if (items.length > 0) {
var msg = items[0].address.toString() + " (";
msg += items[0].centerPoint.lon + ", ";
msg += items[0].centerPoint.lat + ")";
alert(msg);
} else {
// Found nothing
}
} else {
// Error! Display the message.
alert(response.message);
}
};