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.

Failure Response Example

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