This documentation provides your reference to the EMS JSON API.
It explains each service, and describes all commonly exchanged objects and datatypes. It is accompanied by a glossary and an appendix of tabular information also relevant to the JavaScript API.
Before attempting to access any of the JSON services, please note the following essentials regarding access, authentication and error-handling.
URL access
All service URLs are presented in relation to an <ENDPOINT>. For the appropriate URL, and to check on server status, see Access URLs.
Authentication and headers
All services are secured by two headers:
X-Auth-Token X-Auth-Password
For services accessed by HTTP POST, you should also set the following header:
Content-Type: application/json
When requesting a map, you will use an HTTP header to specify the return format, which may be a binary stream, JSON with a base64-encoded image, or JSON with a URL referencing a gif or a png.
For more information, see Map Services.
Error-handling
- Services return 401 (Unauthorised) if the authentication headers are not present or do not contain a valid token and password combination.
- Services return 400 (Bad Request) if they receive a request body that is not valid for the service or if a valid search fails to return any results.
- Services return 500 (Internal Server Error) if an unexpected error occurs while processing the response.
400 and 500 errors return with the following JSON body:
{
"message":<string>
"code":<int>,
}
If you are using the mapping service with the accept header set to image/gif or image/png, 400 and 500 errors return a standard HTML error response.
Tools
Sensis cannot endorse any particular product, but developers have found the following tools useful:
- RESTclient add-on for FireFox
- SoapUI for SOAP and REST-based web services
- The Online JSON Viewer
- cURL - eg. curl -H "X-Auth-Token: TOKEN" -H "X-Auth-Password: PASSWORD" -H "Content-Type: application/json" -H "Accept: application/json" http://api-ems-stage.ext.sensis.com.au/v2/service/search/suggest -d {\"query\":\"melb\"}
- wget - eg wget -S -O - --no-proxy http://api-ems-stage.ext.sensis.com.au/v2/service/search/suggest --header="X-Auth-Token: TOKEN" --header="X-Auth-Password: PASSWORD" --header="Content-Type: application/json" --post-data={\"query\":\"melb\"}
Sample request
{
"height":400,
"width":600,
"layers":["PHOTO"],
"centre":{"lat":-37.9,"lon":145},
"zoom":4
}
