Domestic Rating API - Documentation
This API allows you to find NZ Post products and their associated costs.
Request
API Details
URL |
HTTP Request Types |
Request Formats |
http://api.nzpost.co.nz/ratefinder/domestic/rating/v2 |
GET |
JSON, XML, HTML |
Request Parameters
Parameter |
Description |
Required |
Value Type |
Example |
api_key |
Your license key for the application. Please contact developer@nzpost.co.nz for a license key |
Yes |
String |
c4f820f0420a013ea143230c290fbf99 |
length_in_millimetres |
Length of the package |
Yes |
Integer |
200 |
width_in_millimetres |
Width of the package |
Yes, unless diameter is given |
Integer |
100 |
height_in_millimetres |
Height of the package. Also known as thickness |
Yes, unless diameter is given |
Integer |
50 |
diameter_in_millimetres |
Diameter of the package. Leave blank if rectangular |
Only if width and height are not given |
Integer |
30 |
weight_in_grams |
Weight of the package in grams |
Yes |
Integer |
3000 |
value |
Monetary value of the package |
Yes |
Decimal |
20.40 |
source_x |
The x coordinate for the source location. Using WGS84 spatial reference system |
No |
Decimal |
170.98 |
source_y |
The y coordinate for the source location. Using WGS84 spatial reference system |
No |
Decimal |
-44.32 |
dest_x |
The x coordinate for the destination location. Using WGS84 spatial reference system |
No |
Decimal |
178.34 |
dest_y |
The y coordinate for the destination location. Using WGS84 spatial reference system |
No |
Decimal |
-43.29 |
source_postcode |
Postcode at the source location |
No |
String |
6011 |
dest_postcode |
Postcode at the destination location |
No |
String |
6012 |
rural |
Boolean option to return or exclude rural addons. Leaving this blank will return rural addons with mandatory=false. |
No |
Boolean |
1 |
distance_code |
Either across_town, within_island or nationwide. Only supply this field, when src/dest fields are missing. |
No |
Repeated Strings |
within_island |
postage_type |
Either postage_only or postage_included. Leave blank for all product types.
| No |
String |
postage_only |
format |
The format of the response |
Yes |
String |
json |
Example Requests
Response
Types of Response
Response Type |
Status Code |
Success |
200 |
Request has validation errors |
400 |
Missing or incorrect api key |
401 |
Unexpected Error |
500 |
Response Elements
Element |
Description |
Type |
Required |
Example |
success |
Indicates if the request succeeded or not |
Boolean |
Yes |
See examples below |
products |
An array of product hashes containing computer-readable codes and human-readable messages for each product |
Array |
Yes |
See examples below |
package |
A hash of package related attributes |
Hash |
Yes |
See examples below |
delivery |
A hash of delivery specific attributes |
Hash |
Yes |
See examples below |
error |
A hash containing a computer-readable code and message |
Hash |
No |
See examples below |
Successful Response Example
The snippet below shows an example of a successful result. You should use the example form
to gain an understanding of the various request parameters, and the responses that are returned.
Failure Response Example
The example below shows an unsuccessful result.
An attribute named message
will contain
further information on the cause of the failure.