Domestic rate method

The domestic rate method allows you to programmatically find NZ Post products and their associated cost via a simple API.

How the domestic rate method works

Make a GET HTTP request to api.nzpost.co.nz/ratefinder/rate.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
`thickness` unless diameter given	Thickness (mm). Leave blank if tube	120
`length`	Length of parcel in mm (tube or rectangular)	1000
`weight`	Weight (kg)	1.2
`diameter` only if thickness and height not give	Diameter of tube (mm). Leave blank if rectangular	100
`height` unless diameter given	Height in mm for rectangular shaped parcels. Leave blank if tube	120

Optional parameters

Parameter Name	Description	Example
`carrier`	Which carriers to allow. Default is "nzpost", or you can choose "courierpost" or "all"	courierpost
`source_x`	Source X Coordinate (latitude)	-41.281257
`source_y`	Source Y Coordinate (longitude)	174.77746
`dest_x`	Destination X Coordinate (latitude)	-41.28085
`dest_y`	Destination Y Coordinate (longitude)	174.778951
`postcode_src`	Source Postcode	6012
`postcode_dest`	Destination Postcode	1050
`dest_wildcard`	Destination wildcard when set will return all available delivery options (nationwide, within island or across town)	1
`rural_options`	Either, 'exclude' or 'force'. Leaving this blank will return products with and without rural pricing.	exclude
`format`	The format of the response (it can also be set by the content-type header)	json

API response

The response object is a json hash.

Success is determined by the 'status' key-value pair (either success or failure). Products available are contained in an array within the 'products' node. The following request can be used to see what products are available:

http://api.nzpost.co.nz/ratefinder/rate.json?api_key=123&height=100&length=100&postcode_dest=6011&postcode_src=6012&thickness=100&weight=1

  {
     "post_large_delivery_type":"across_town",
     "post_defaulting_to_nationwide":false,
     "products":[
        {
           "cost":"6.00",
           "product_url":null,
           "thickness":100,
           "code":"PCB5C5",
           "service":"parcel_post_tracked",
           "priority":"parcel_post_tracked",
           "weight":1.0,
           "product_max_dimensions":"165*235*170 5000gms",
           "label_url":"https://www.nzpost.co.nz/cart/checkout",
           "height":100,
           "service_group_description":"ParcelPost Tracked",
           "packaging":"postage_only",
           "description":"C5 Postage Only",
           "length":100,
           "speed_description":"parcel_post_tracked"
        },
        {
           "cost":"5.50",
           "product_url":null,
           "thickness":100,
           "code":"PCBXT",
           "service":"parcel_post_tracked_zonal",
           "priority":"parcel_post_tracked_zonal",
           "weight":1.0,
           "product_max_dimensions":"15000*15000*15000 25000gms",
           "label_url":"https://www.nzpost.co.nz/cart/checkout",
           "height":100,
           "service_group_description":"ParcelPost Tracked Zonal",
           "packaging":"postage_only",
           "description":"Across town",
           "length":100,
           "speed_description":"Next Working Day"
        }
     ],
     "params":{
        "format":"json",
        "thickness":"100",
        "postcode_dest":"6011",
        "weight":"1",
        "api_key":"123",
        "action":"rate",
        "height":"100",
        "length":"100",
        "controller":"api",
        "postcode_src":"6012"
     },
     "status":"success"
  }