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 http://api.nzpost.co.nz/ratefinder/international.json with the parameters listed below. An HTML form is available for easy submission of requests.

Parameter NameDescriptionRequiredExample
api_key Your license key for the application. Please contact developer@nzpost.co.nz for a license keyyes1234-5678-90ab-cdfe
country_codeDestination country code of the packageyesAU
valueApproximate commercial value in NZ dollarsyes9.50
lengthLength of package (mm)yes250
heightHeight of the package (mm)if parcel180
thicknessThickness of the packageif parcel50
diameterDiameter (if tube)if tube55
weightPackage weight in kgyes1.2
promo_codePromotional codenoXYZ001
documentsInclude document package types in results.
Use "include" to include document types
Use "only" to return only document types
Leave blank to exclude document types
noinclude
callbackJSONP callback methodif JSONPjquery_32434758934
formatThe format of the responseyesjson
Parcel Tube

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