Details method

This API method displays the details of a location when a location ID is entered, including contact information, available services and physical address.

How the details method works

Make a GET or POST HTTP request to api.nzpost.co.nz/locator/api/details 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
id Location ID The ID of the location that details are being requested for 58130
callback
(required for format jsonp)
JSONP callback method The name of the method that the JSONP response will call. callback123456

Optional parameters

Parameter Name Description Example
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-Sincerequest 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.

Response format

HTML
When the html& format is requested, a simple HTML file is returned. This includes detailed information of the requested location.
The content_type header value is set to text/html.

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