International rate method

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"
}

 

Related information