New Zealand Post

Developer

International Rate Finder API - Documentation

The Rate Finder API allows you to programmatically find NZ Post products and their associated cost via a simple API.

Request

Send an HTTP GET to https://api.nzpost.co.nz/ratefinder/international.json with the parameters listed below. An HTML form is available for easy submission of requests.

Parameter Name	Description	Required	Example
`api_key`	Your license key for the application. Please contact developer@nzpost.co.nz for a license key	yes	1234-5678-90ab-cdfe
`country_code`	Destination country code of the package	yes	AU
`value`	Approximate commercial value in NZ dollars	yes	9.50
`length`	Length of package (mm)	yes	250
`height`	Height of the package (mm)	if parcel	180
`thickness`	Thickness of the package	if parcel	50
`diameter`	Diameter (if tube)	if tube	55
`weight`	Package weight in kg	yes	1.2
`promo_code`	Promotional code	no	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	no	include
`callback`	JSONP callback method	if JSONP	jquery_32434758934
`format`	The format of the response	yes	json

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