This API method is a general purpose search for locating various New Zealand Post assets.
How the locations method works
Make a GET or POST HTTP request to api.nzpost.co.nz/locator/api/locations with the parameters listed below. An HTML form is available for easy submission of requests.
Note:
The If-Modified-Sincerequest header is supported, and a 304 Not Modifiedresponse may be returned.
Parameters for the API request
Required parameters
| Parameter | Name | Description | Example |
|---|---|---|---|
api_key |
API Key | Your license key for the application. | c4f820f0420a012e a143000c290fbf99 |
callback |
JSONP callback method | The name of the method that the JSONP response will call. | callback123456 |
Optional parameters
| Parameter | Name | Description | Example |
|---|---|---|---|
type |
Location Types | Return locations of this type. You can enter multiple location types. Leave blank for all. | Postshop |
service |
Services | Return locations that are marked with the supplied flags. You can enter multiple flags. Leave blank for all | 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. | 2 |
nearby_latitude |
Nearby Latitude | Returned locations are ordered by increasing distance from the supplied coordinates (and nearby_longitude) | -41.288719 |
nearby_longitude |
Nearby Longitude | Returned locations are ordered by increasing distance from the supplied coordinates (and nearby_latitude) | 174.775019 |
lat1 |
Latitude 1 (top left) | Returned locations are within the specified area | -41.288719 |
lng1 |
Longitude 1 (top left) | Returned locations are within the specified area | 174.775019 |
lat2 |
Latitude 2 (bottom right) | Returned locations are within the specified area | -40.288719 |
lng2 |
Longitude 2 (bottom right) | Returned locations are within the specified area | 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. | Karori |
max |
Maximum | Limit the number of results return to this number. Leave blank for no limit. | 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. |
html |
force |
Disable caching | When set to 1, the If-Modified-Since request header is ignored. |
1 |
API responses
The response returned depends on the requested format. Each of the responses may have elements added in the future.
HTML
When the htmlformat 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_xmlformat is requested, an XML file is returned. The content_type header value is set to application/xml.
iPhone plist format
When the plistformat is requested, an iPhone compatible file format is returned. The content_type header value is set to application/xml.
Google TSV format
When the tsvformat is requested, a Google Maps compatible file format is returned. The content_type header value is set to text/csv.
JSON format
When the jsonformat is requested, a JSON array of hashed values is returned. The content_type header value is set to application/json.
JSONP format
When the jsonpformat 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 request 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.