ParcelTrack API
Track Parcel(s)
###Resource URL
UAT:
https://api.uat.nzpost.co.nz/parceltrack/v4/parcels?tracking_reference=Production:
https://api.nzpost.co.nz/parceltrack/v4/parcels?tracking_reference=
###Resource Description
Request to return tracking information for up to ten specific tracking references.
###Resource Information
| Attribute | Detail |
|---|---|
| Response Format | JSON |
| Requires Authentication | Yes |
| Rate Limited | 15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out. |
###Request Message Fields
| Field | Description | Mand | Example |
|---|---|---|---|
| tracking_reference | Unique tracking reference for a parcel (job number for Pace) | Yes | JP100000271NZ or 123521 |
###Sample Request
https://api.nzpost.co.nz/parceltrack/v4/parcels?tracking_reference=EY593742046NZ&tracking_reference=FF138431175NZ&tracking_reference=FL010795711NZ&tracking_reference=FZ101183740NZ&tracking_reference=GC000875843NZ&tracking_reference=HA099246112NZ&tracking_reference=EY593742046NZ&tracking_reference=FF138431175NZ&tracking_reference=FL010795711NZ&tracking_reference=FZ101183740NZ
###Response Parameters
| Field Name | Description | Mand | Example |
|---|---|---|---|
| success | Returns true if request is successful else false. | Yes | True |
| message_id | A unique ID for the API Call | Yes | da5ac7f0-7c18-11e5-b508-0297700fe675 |
| results | An JSON object containing the scan event details of all queried parcels. See Results Object Parameters. | No | JSON Object |
###Results Object Parameters
| Field Name | Description | Mand | Example |
|---|---|---|---|
| tracking_reference | The queried tracking reference | Yes | JP100000271NZ |
| tracking_events | An JSON object containing all scan events of queried parcels. See Results - Tracking Events Object Parameter section. This may be presented when the success flag is true. This may be absent if the parcel has no associated scan events at the time of the request or the success flag is false. | N | JSON Object |
| errors | An JSON object containing error details. See Results - Errors Object Parameter section. This may be presented if the parcel has no associated scan events at the time of the request or the success flag is false. | N | JSON Object |
###Results - Tracking Events Object Parameters
| Field Name | Description | Mand | Example |
|---|---|---|---|
| date_time | Date and time the courier recorded the scan or event. This is the time you should display to your customers | Y | 2016-01-29 11:00:00Z |
| description | Detailed description of the event | Y | Ready to send |
| edifact_code | EDIFACT code for the parcel delivery step | Yes | 997 |
| depot_name | Name of the depot that relates to scan | N | AKL City Fleet |
| run_name | Name of the run that relates to the scan | N | Auckland CBD |
| courier_first_name | First name of the courier performing the event | N | John |
| courier_full_name | Full name of the courier performing the event. This field is only returned for the internal users. | N | John Smith |
| location | JSON object containing the location details of an event. See Tracking Events - Location Object Parameters section. | N | JSON Object |
| signed_by | JSON object containing name of the signer and the string representation of binary signature data. See Tracking Events - Signed By Object Parameters section. | Yes if the item was signature required | JSON Object |
| seqref | CME sequence ref of the event | Y if event derived from CME | 2631897613 |
| source | Source system where the event occurred. Valid systems are: CME, Navigator, IPS, ParcelStore, PSG | N | CME |
| status | Brief description of the event | Y | Ready to send |
###Tracking Events - Location Object Parameters
| Field Name| Description | Mand| Example |
|---------|-----------------------------------------------------------|--------|--------------------------|
|latitude|Latitude of the location of the scan|Y if longitude exists|-36.8485|
|longitude|Longitude of the location of the scan|Y if latitude exists|174.7633|
###Tracking Events - Signed By Object Parameters
| Field Name | Description | Mand | Example |
|---|---|---|---|
| name | Full name of the person providing the signature. | Yes if signature required | Lee Child |
| signature | String representation of the binary data for the signature. | No | ec608f40-2a8b-11e5... |
###Results - Errors Object Parameters
|Field Name|Description|Example|
|------------|--------------------------------------------------------------------------------------------------------------------------------------------|---------------------|
|code|Error code|400002|
|message|Error message|Invalid parameter(s)|
|details|Error details|No event for this ticket|
###HTTP Status Codes
Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request
| Code | Message |
|---|---|
| 200 | Success |
| 400 | Bad request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 409 | Invalid request |
| 500 | System unavailable |
###Error Codes
| Code | Message |
|---|---|
| 200001 | Partial results returned, not all system(s) have responded |
| 200002 | All sources responded, data may be incomplete |
| 400001 | Parameter(s) missing |
| 400002 | Invalid parameter(s) |
| 400003 | Non mutually exclusive parameters detected |
| 401001 | Unauthorised access, please contact administrator |
| 500001 | General Exception |
| 500002 | System(s) offline |
###Sample Response
Sample of all queried tracking references in a request are valid:
{
"success" : true,
"message_id" : "123456789",
"results" : [{
"tracking_reference" : "8441112178053201AKL020AS",
"tracking_events" : [{
"date_time" : "2016-01-29 11:00:00Z",
"description" : "Ready to send",
"edifact_code" : "997",
"seqref" : "2834931351",
"source" : "CME",
"status" : "Ready to send"
}, {
"date_time" : "2016-02-01 20:43:15Z",
"description" : "Picked up",
"edifact_code" : "13",
"depot_name" : "AKL City Fleet",
"run_name" : "Auckland CBD",
"courier_first_name" : "Jatinder",
"seqref" : "2835679952",
"source" : "CME",
"status" : "Picked up"
}, {
"date_time" : "2016-02-01 23:04:27Z",
"description" : "Processing at depot",
"edifact_code" : "8",
"depot_name" : "AKL Central East Fleet",
"run_name" : "East Tamaki",
"courier_first_name" : "Sorter",
"seqref" : "2835835282",
"source" : "CME",
"status" : "Processing at depot"
}, {
"date_time" : "2016-02-02 02:31:03Z",
"description" : "Waiting for courier",
"edifact_code" : "58",
"depot_name" : "AKL North Shore Fleet",
"run_name" : "Albany",
"courier_first_name" : "North Shore",
"seqref" : "2836045179",
"source" : "CME",
"status" : "Waiting for courier"
}, {
"date_time" : "2016-02-02 23:44:37Z",
"description" : "Redirected",
"edifact_code" : "95",
"seqref" : "2837278756",
"source" : "CME",
"status" : "Redirected"
}, {
"date_time" : "2016-02-03 17:37:39Z",
"description" : "With courier for delivery",
"edifact_code" : "32",
"depot_name" : "AKL North Shore Fleet",
"run_name" : "Glenfield",
"courier_first_name" : "Alexander",
"seqref" : "2838110846",
"source" : "CME",
"status" : "With courier for delivery"
}, {
"date_time" : "2016-02-03 19:46:00Z",
"description" : "Ready to collect",
"edifact_code" : "144",
"depot_name" : "AKL North Shore Fleet",
"run_name" : "Glenfield",
"courier_first_name" : "Alexander",
"seqref" : "2838282165",
"source" : "CME",
"status" : "Ready to collect"
}, {
"date_time" : "2016-02-03 20:16:27Z",
"description" : "Ready to collect",
"edifact_code" : "141",
"depot_name" : "PCD Ext - Countdown Scanners",
"run_name" : "Glenfield",
"courier_first_name" : "Glenfield Mall",
"seqref" : "2838320096",
"source" : "CME",
"status" : "Ready to collect"
}, {
"date_time" : "2016-02-03 23:33:51Z",
"description" : "Delivered",
"edifact_code" : "22",
"depot_name" : "PCD Ext - Countdown Scanners",
"run_name" : "Glenfield",
"courier_first_name" : "Glenfield Mall",
"location" : {
"latitude" : -36.8485,
"longitude" : 174.7633
},
"signed_by" : {
"name" : "raezel villamena",
"signature" : "/yQwJCcnDyQUIRohHCAeICAiIiQhJyAqHywfLyMvJzAkMh8zGzUWNRQ1ETQPMQwvCyoLKAwkECETIBggGiEdIx8lICgiKiQtJjMoNy06MDozOjU5Nzc5NDoyOS03KzYpNCgyKC8oLSorKyctJDAgMx02GTgYOBo3ITckNyY2KDgqOig8Jj4hPx4/HD8aPRo7HDkfOSQ5JjkoOyk9KD8lQSJCH0MdQx9DIUQjRCVGJUgjSSFKH0wdTRtPHFAfUSJRJVIrUjBSNFE3UDpOOU42TTRML00qTyZQJFIiVCBWIFgjWCVZJ1kpWStbK1woXCZdI10hXiNeJV4nYSViI2MhYx5kHGQfZSJlJWUnaClrKW0mbyFvHnAbcBhwFm8TbRNsFWsYaxtrHmsgbCRsJ24ocClyKHQmdiR4H3kbexl8G3wdfSB/IoIjhCKFIIYehB2CHYAefiB9I30lfSd/J4IlgyKEH4QhhSSHJIgiix6MHIwejCCLI4sliyKLII4gjiOQI5Egkh2UHJYemCCaIZwgnh6fHJ8anxyeH54hoCKjIaUgpx2pG6oZqRyoHqcgpiKoIKoeqhysGq8YsRqyHLQeth64HLoavBe9Fb0TuxK5FLcWthi1G7Udtxy5GrsYwRTDEsURxw/LDc0M"
},
"seqref" : "2838545768",
"source" : "CME",
"status" : "Delivered"
}
]
}, {
"tracking_reference" : "8441112178053201AKL666AS",
"tracking_events" : [{
"date_time" : "2016-02-24 23:57:00Z",
"description" : "International arrival",
"edifact_code" : "6002",
"source" : "ParcelStore",
"status" : "International arrival"
}, {
"date_time" : "2016-02-25 00:01:18Z",
"description" : "In Transit",
"edifact_code" : "6022",
"source" : "ParcelStore",
"status" : "In Transit"
}
]
}
]
}Sample of some queried tracking references in a request are invalid:
{
"success": true,
"message_id": "123456789",
"results": [
{
"tracking_reference": "8441112178053201AKL666AS",
"errors": [
{
"code": "400002",
"message": "Invalid parameter(s)",
"details": "No events for this ticket"
}
]
},
{
"tracking_reference": "8441112178053201AKL020AS",
"tracking_events": [
{
"date_time": "2016-03-01 19:00:00Z",
"description": "Departure from New Zealand",
"edifact_code": "5201",
"depot_name": "Location not available",
"source": "IPS",
"status": "Departure from New Zealand"
}
]
}
]
}