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. | 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.