The international rate method allows you to programmatically find NZ Post products and their associated cost via a simple API.
How the international request works
Make a GET HTTP request to api.nzpost.co.nz/ratefinder/international.json with the parameters listed below. An HTML form is available for easy submission of requests.
Parameters for the API request
Required parameters
| Parameter Name | Description | Example |
|---|---|---|
api_key |
Your license key for the application. | 1234-5678-90ab-cdfe |
country_code |
Destination country code of the package | AU |
value |
Approximate commercial value in NZ dollars | 9.50 |
length |
Length of package (mm) | 250 |
height(for parcels) |
Height of the package (mm) | 180 |
thickness(for parcels) |
Thickness of the package | 50 |
diameter(for tubes) |
Diameter (if tube) | 55 |
weight |
Package weight in kg | 1.2 |
promo_code |
Promotional code | XYZ001 |
callback(for format jsonp) |
JSONP callback method | jquery_32434758934 |
format |
The format of the response | json |
Optional parameters
| Parameter Name | Description | Example |
|---|---|---|
promo_code |
Promotional code | XYZ001 |
documents |
Include document package types in results. Use "include" to include document types Use "only" to return only document types Leave blank to exclude document types |
include |
API response
Success is indicated by a 200 HTTP status code, and a 'status' = 'success' key-value pair. Failure is indicated by a 400 HTTP status code, and a 'status' = 'failure' key-value pair.
Products available (and their prices) are contained in an array within the 'products' node.
Sample responses can be generated on the international demo form for any of the supported formats.
Example JSON response
{
"products": [{
"group": "Economy International Parcel",
"price": 17.15,
"name": "Zone A EconomyPost Pcl 1.5kg",
"code": "IECNA1500"
},
{
"group": "Air International Parcel",
"price": 19.2,
"name": "Zone A AirPost Cust Pcl 1.5kg",
"code": "IACNA1500"
},
{
"group": "Intl Economy Courier Document",
"price": 30.52,
"name": "Int Econ Cour Doc Zn A 1.5kg",
"code": "IEZDA1500"
},
{
"group": "Intl Economy Courier Parcel",
"price": 30.52,
"name": "Int Econ Cour Pcl Zn A 1.5kg",
"code": "IEZPA1500"
}],
"status": "success"
}