[ Whereis® API Home ] [ Developers' Guide ]
The EMS JavaScript API provides web access to mapping services handled by the JSON API, which can be used for such things as obtaining coordinates for an address, confirming that an address exists, getting a route and navigation instructions from place to place, and so on. You don't need to create or display an EMS.Map to use these services.
The process for accessing the services through the JavaScript API is always the same.
1. Initialise the service object. For example:
var service = new EMS.Service.Geocode();
2. Format a request.
var query = "55 Lonsdale Street, Melbourne";
3. Submit the request, nominating a callback function. For example:
service.geocode(query, callback);
4. In the callback function, handle the response. For example:
function callback(response, status){
//check status and process the response
}
Error-Handling
Service responses are all formatted in a similar way: they return a response object and a status flag. If return status is any value other than EMS.Status.OK, a plain English error message is returned in response.message.
If the status returns EMS.Status.OK, the response object wraps the particular response from that service.
Example
The following code snippet outlines a typical error-handler for a service that returns a list of results, such as EMS.Service.Geocode.
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) {
// We have items! Process them...
} else {
// Found nothing
}
} else {
// Error! Display the message.
alert(response.message);
}
};
When dealing with services, the API expects and returns latitude and longitude coordinates in standard WGS84 format.
If you execute a request with the intention of centring a map on the returned coordinates, you must convert those coordinates to an EMS.LonLat object before passing them to EMS.Map.
For a full explanation, see the Location Readme.
