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. Fill in our Rate Finder API form to get your unique key. 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"
  }

Related information