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.