Track method

This API method provides package search capability for deliveries sent with New Zealand Post.

How the track method works

Make a GET or POST HTTP request to http://api.nzpost.co.nz/tracking/track 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
license_key
License Key Your license key for the application. c4f820f0420a012e a143000c290fbf99
user_ip_address User IP Address The IP address of the end user 50.12.2.99
tracking_code Tracking Code The tracking code supplied by NZ Post. This field may be provided multiple times to request the status of up to 10 packages. XY123456789NZ
callback
(for format jsonp)
JSONP callback method The name of the method that the JSONP response will call. callback123456

Optional parameters

Parameter Name Description Example
include_signature _data Include Signature Data If this flag is present, then signature data will be included in the response. This data is a Base64 encoded PNG blob. Signature data is not included by default. 1
format Response format Enter either html, xml, json, or jsonp. Defaults to html results. See the Response section for further details. html

API responses

The response returned depends on the requested format. Each of the responses may have elements added in the future.

HTML

When the html format is requested, a simple HTML file is returned. This includes a table of matching packages.
The content_type header value is set to text/html.

XML format

When the xml format is requested, an XML file is returned.
The content_type header value is set to application/xml.

Example response:

<trackingresults xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <results>
    <result>
      <trackingnumber>00094010521015594248</trackingnumber>
      <shortdescription>Delivery</shortdescription>
      <detaileddescription>Delivery on 26/10/11 at 12.00 AM and signed for by Signature Illegible</detaileddescription>
      <source>courier_post</source>
      <eventhistory>
        <eventhistory>
          <eventdate>21/10/11</eventdate>
          <eventtime>06.48 PM</eventtime>
          <eventdatetime>2011-10-21T18:48:21+13:00</eventdatetime>
          <flag>C</flag>
          <description>Auckland Operations Centr</description>
          <location>tauranga</location>
          <carrier>CP</carrier>
        </eventhistory>
        <eventhistory>
          <eventdate>22/10/11</eventdate>
          <eventtime>02.51 AM</eventtime>
          <eventdatetime>2011-10-22T02:51:23+13:00</eventdatetime>
          <flag>C</flag>
          <description>Handover</description>
          <location>Tauranga Depot</location>
          <carrier>CP</carrier>
        </eventhistory>
        <eventhistory>
          <eventdate>26/10/11</eventdate>
          <eventtime>12.00 AM</eventtime>
          <eventdatetime>2011-10-26T00:00:00+13:00</eventdatetime>
          <flag>F</flag>
          <description>Delivery</description>
          <location>Rotorua RD Region</location>
          <signature_name>Signature Illegible</signature_name>
          <carrier>CP</carrier>
        </eventhistory>
      </eventhistory>
    </result>
  </results>
</trackingresults>

JSON format

When the json format is requested, a JSON array of hashed values is returned.
The content_type header value is set to application/json.

Example response:

{
  "RR483989453SK": {
    "short_description":"Delivered",
    "detail_description":"Your item has been successfully delivered and was signed for by 5271.\n\t\t",
    "events":[
      {
        "flag":"C",
        "time":"02.00 PM",
        "date":"04/10/11",
        "description":"Arrived in New Zealand",
        "datetime":"2011-10-04T14:00:00+13:00"
      },
      {
        "flag":"F",
        "time":"06.30 AM",
        "date":"11/10/11",
        "description":"Delivery Complete",
        "datetime":"2011-10-11T06:30:00+13:00"
      }
    ],
    "source":"nz_post"
  }
}

JSONP format

When the jsonp format is requested, a Javascript file containing a call to the supplied callback method is returned. The callback method is passed an array of hashed values.
The content_type header value is set to application/javascript.

Error conditions

The API request will respond with one of the following HTTP response codes:

200 Success - message received
400 Bad request - incorrect or missing parameters
401 Unauthorised - license key expired or similar

In the case of a 40x error, the response will again contain a JSON hash with a “message” value. For example, a missing JSONP callback parameter will give this (400) response:

{"message":"JSONP format requires a callback parameter"}

When an error occurs, the content type is set to application/json.

Error codes

An API request may contain the following error codes:

N Not yet received. The tracking service does not have a record of that item
U The tracking service is currently unavailable

Flags

An API request may contain the following flags:

A Picked up
B Left country of origin OR Left New Zealand
C Accepted at Mail Centre OR Arrived in New Zealand OR Arrived overseas
D Held for clearance
F Delivery Complete
O Out for Delivery

Datetime

"datetime":"2011-10-11T06:30:00+13:00"

This provides date and time information for an event in ISO 8601 format. The "date" and "time" fields contain similar information, in a more human readable format.

Mock Service

A mock service is available that provides fixed responses for given inputs. To use this service, you must supply a mock parameter with value "1".

The available inputs are:

Use Case User IP Address Tracking Code
Not Found 10.10.10.1 AS000000001NZ
Accepted 10.10.10.2 AS000000001NZ
Out for Delivery 10.10.10.3 AS000000001NZ
Delivered 10.10.10.4 AS000000001NZ
Not Found Anything AS000000002NZ
Service Down Anything AS000000003NZ
Invalid Tracking Code Anything invalidstring
Valid Tracking Code Anything Anything

Related information