New Zealand Post

Developer

Domestic Rating API - Documentation

This API allows you to find NZ Post products and their associated costs.

Try it here

Request

API Details

URL	HTTP Request Types	Request Formats
http://api.nzpost.co.nz/ratefinder/domestic/rating/v2	GET	JSON, XML, HTML

Request Parameters

Parameter	Description	Required	Value Type	Example
api_key	Your license key for the application. Please contact developer@nzpost.co.nz for a license key	Yes	String	c4f820f0420a013ea143230c290fbf99
length_in_millimetres	Length of the package	Yes	Integer	200
width_in_millimetres	Width of the package	Yes, unless diameter is given	Integer	100
height_in_millimetres	Height of the package. Also known as thickness	Yes, unless diameter is given	Integer	50
diameter_in_millimetres	Diameter of the package. Leave blank if rectangular	Only if width and height are not given	Integer	30
weight_in_grams	Weight of the package in grams	Yes	Integer	3000
value	Monetary value of the package	Yes	Decimal	20.40
source_x	The x coordinate for the source location. Using WGS84 spatial reference system	No	Decimal	170.98
source_y	The y coordinate for the source location. Using WGS84 spatial reference system	No	Decimal	-44.32
dest_x	The x coordinate for the destination location. Using WGS84 spatial reference system	No	Decimal	178.34
dest_y	The y coordinate for the destination location. Using WGS84 spatial reference system	No	Decimal	-43.29
source_postcode	Postcode at the source location	No	String	6011
dest_postcode	Postcode at the destination location	No	String	6012
rural	Boolean option to return or exclude rural addons. Leaving this blank will return rural addons with mandatory=false.	No	Boolean	1
distance_code	Either across_town, within_island or nationwide. Only supply this field, when src/dest fields are missing.	No	Repeated Strings	within_island
postage_type	Either postage_only or postage_included. Leave blank for all product types.	No	String	postage_only
format	The format of the response	Yes	String	json

Example Requests

Response

Types of Response

Response Type	Status Code
Success	200
Request has validation errors	400
Missing or incorrect api key	401
Unexpected Error	500

Response Elements

Element	Description	Type	Required	Example
success	Indicates if the request succeeded or not	Boolean	Yes	See examples below
products	An array of product hashes containing computer-readable codes and human-readable messages for each product	Array	Yes	See examples below
package	A hash of package related attributes	Hash	Yes	See examples below
delivery	A hash of delivery specific attributes	Hash	Yes	See examples below
error	A hash containing a computer-readable code and message	Hash	No	See examples below

Successful Response Example

The snippet below shows an example of a successful result. You should use the example form to gain an understanding of the various request parameters, and the responses that are returned.

{
  "delivery": {
      "cutoff_time": null,
      "cutoff_time_has_passed": null,
      "dest_postcode": "9818",
      "dest_postcode_name": "Stewart Island",
      "dest_x": 173.91959399999999,
      "dest_y": -41.278131000000002,
      "destination_label_1": "The Grove",
      "destination_label_2": null,
      "distance_codes": [
          "within_island"
      ],
      "not_guaranteed": true,
      "rural": null,
      "saturday_delivery": false,
      "source_postcode": "9818",
      "source_postcode_name": "Stewart Island",
      "source_x": 174.77306823318801,
      "source_y": -41.291701884620103
  },
  "package": {
      "applied_weight_in_grams": 2000,
      "height_in_millimetres": 10,
      "length_in_millimetres": 255,
      "value": "249.0",
      "volumetric_weight_in_grams": 99.450000000000003,
      "weight_in_grams": 2000,
      "width_in_millimetres": 195
  },
  "products": [
      {
          "bag_only_price_excluding_gst": 1.74,
          "bag_only_price_including_gst": 2.0,
          "barcode": "9415599116048",
          "family_code": "RED",
          "information": "Includes ParcelPost postage within New Zealand",
          "max_height_in_millimetres": null,
          "max_length_in_millimetres": 310,
          "max_weight_in_grams": 3000,
          "max_width_in_millimetres": 250,
          "min_weight_in_grams": 0,
          "name": "Size 3 bag - postage included",
          "package_type": "bag",
          "price_excluding_gst": 4.3499999999999996,
          "price_including_gst": 5.0,
          "services": [
              {
                  "addons": [],
                  "distance_description": "Nationwide",
                  "duration_description": "Up to 3 working days",
                  "duration_rank": 1.5,
                  "information": "Our most affordable service for sending parcels within New Zealand. You can send parcels worth up to $250 and under 3kg by ParcelPost post.",
                  "max_compensation": "250.0",
                  "name": "ParcelPost",
                  "price_excluding_gst": 0.0,
                  "price_including_gst": 0.0,
                  "tracked": false
              },
              {
                  "addons": [
                      {
                          "information": "",
                          "mandatory": false,
                          "name": "Rural Delivery",
                          "price_excluding_gst": 2.4300000000000002,
                          "price_including_gst": 2.7999999999999998,
                          "unique_code": "RURALD"
                      }
                  ],
                  "distance_description": "Nationwide",
                  "duration_description": "Up to 3 working days",
                  "duration_rank": 1.5,
                  "information": "With tracked, we record when we receive and deliver your parcel. You can send parcels worth up to $250 using this service.",
                  "max_compensation": "250.0",
                  "name": "Tracked",
                  "price_excluding_gst": 1.3,
                  "price_including_gst": 1.5,
                  "tracked": true
              }
          ],
          "shorter_name": "C4 red",
          "weight_range_description": "0-3kg"
      }
  ],
  "success": true
}

Failure Response Example

The example below shows an unsuccessful result. An attribute named message will contain further information on the cause of the failure.

{
  "success":false,
  "error":
  {
    "code":400,
    "message":
    {
      "length_in_millimetres": ["can't be blank"]
    }
  }
}