Locator API - Documentation
This is a general purpose search for locating various New Zealand Post assets.
Request
HTTP GET or POST to http://api.nzpost.co.nz/locator/api/locations with the parameters listed below. An HTML form is available for easy submission of requests.
The If-Modified-Since request header is supported, and a 304 Not Modified
response may be returned.
| Parameter | Name | Description | Required | Example |
|---|---|---|---|---|
api_key |
API Key | Your license key for the application. Please contact developer@nzpost.co.nz for a license key | Yes | c4f820f0420a012ea143000c290fbf99 |
type |
Location Types | Return locations of this type. You can enter multiple location types. Leave blank for all. | No | Postshop |
service |
Services | Return locations that are marked with the supplied flags. You can enter multiple flags. Leave blank for all | No | bus_bank_centre |
opening_day |
Opening Days | Return locations that are open on any of the supplied days. You can enter multiple days. Leave blank for all. Days are represented by a number from 0 to 6 where 0 = Monday, 1 = Tuesday, etc. | No | 2 |
partner |
Partners | Whitelist specific locations belonging to a particular Third Party Partner. | No | postcentre |
nearby_latitude |
Nearby Latitude | Returned locations are ordered by increasing distance from the supplied coordinates (and nearby_longitude) | No | -41.288719 |
nearby_longitude |
Nearby Longitude | Returned locations are ordered by increasing distance from the supplied coordinates (and nearby_latitude) | No | 174.775019 |
lat1 |
Latitude 1 (top left) | Returned locations are within the specified area | No | -41.288719 |
long1 |
Longitude 1 (top left) | Returned locations are within the specified area | No | 174.775019 |
lat2 |
Latitude 2 (bottom right) | Returned locations are within the specified area | No | -40.288719 |
long2 |
Longitude 2 (bottom right) | Returned locations are within the specified area | No | 175.775019 |
keyword |
Keyword | Locations where the name or address of the location matches a portion of the supplied keyword. Leave blank for no limit. | No | Karori |
max |
Maximum | Limit the number of results return to this number. Leave blank for no limit. | No | 25 |
format |
Response format | Enter either html, nzpost_xml, plist, tsv, json, or jsonp. Defaults to HTML results. See the Response section for further details. |
No | html |
callback |
JSONP callback method | The name of the method that the JSONP response will call. | Yes, for format jsonp | callback123456 |
| force | Disable caching | When set to 1, the If-Modified-Since request header is ignored. |
No | 1 |
Response
The response returned depends on the requested format. Each of the responses may have elements added in the future.
HTML
When the html format is requested, a simple HTML file is
returned. This includes a table of matching locations. The content_type
header value is set to text/html.
NZ Post XML format
When the nzpost_xml format is requested, an XML file is
returned. The content_type header value is set to
application/xml.
iPhone plist format
When the plist format is requested, an iPhone compatible file
format is returned. The content_type header value is set to
application/xml.
Google TSV format
When the tsv format is requested, a Google Maps compatible file
format is returned. The content_type header value is set to
text/csv.
JSON format
When the json format is requested, a JSON array of hashed values
is returned. The content_type header value is set to
application/json.
JSONP format
When the jsonp format is requested, a Javascript file containing
a call to the supplied callback method is returned. The callback method is
passed an array of hashed values. The content_type header value is set to
application/javascript.
Error conditions
The API calls will respond with one of the following HTTP response codes:
200 | Success - message received |
400 | Bad request - incorrect or missing parameters |
401 | Unauthorised - license key expired or similar |
In the case of a 40x error, the response will again contain a JSON hash with a “message” value. For example, a missing JSONP callback parameter will give this (400) response:
{"message":"JSONP format requires a callback parameter"}
When an error occurs, the content type is set to application/json.