Locations method

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. Fill in our Locator API form to get your unique key. 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.

Related information