ParcelAddress API
Collection Locations
Resource URL
UAT:
http://api.uat.nzpost.co.nz/parceladdress/2.0/domestic/pcdlocationshttps://api.nzpost.co.nz/parceladdress/2.0/domestic/pcdlocationsResource Description
Returns a list of parcel collection points nearest to the coordinates provided.
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. |
Please note that all request parameters should be in lower case.
Request Parameters
| Field Name | Description | Mand | Example |
|---|---|---|---|
| latitude | The latitude of the delivery address. This value is returned from the Get Address Details resource. The results returned are ordered by increasing distance from the supplied coordinates. | Yes | -41.288719 |
| longitude | The latitude of the delivery address. This value is returned from the Get Address Details resource. The results returned are ordered by increasing distance from the supplied coordinates. | Yes | 174.775019 |
| count | Limits the number of results return to this number. | Yes | 5 |
Sample Request
https://api.nzpost.co.nz/parceladdress/2.0/domestic/pcdlocations?latitude=-39.939946&longitude=175.076388&count=5Business Rules
The following business rules are applied on each /addresses request:
| Name | Description |
|---|---|
| BR001 | There is no maximum value for count but you should consider the impacts of displaying a large number of results in your user interface |
| BR002 | The latitude and longitude provided in the request are validated to ensure only numbers are submitted but are not validated as being coordinates within New Zealand |
| BR003 | If the delivery address used on a label is an NZ Post collection point, then you MUST create a PCD type subscription for the parcel recipient via the ParcelNotification API. This requires the tracking reference from the label, parcel recipient's first and last names, email address and the location ID of the collection point. |
Response Parameters
The following lists the required fields in the /addresses response message.
| Field Name | Description | Mand | Example |
|---|---|---|---|
| success | Returns if request is successful | Yes | true |
| locations | Contains array of collection location objects. The number of objects will not exceed the ‘count’ value defined. | Y if success = true | See Locations Object Parameters |
| message_id | A unique id for the API call | Yes | d413cb59-9aab-48a3-bdd9-7d62ecf9027c |
Locations Object Parameters
The following lists the fields in the locations object.
| Field Name | Description | Mand | Example |
|---|---|---|---|
| company_name | Name of the company hosting the collection point | Yes | Wanganui CourierPost Depot |
| lat | Latitude of the collection Point | Yes | -39.933741 |
| lng | Longitude of the collection Point | Yes | 175.046749 |
| phone | Contact phone number for the collection point | Yes | 0800 268 7437 |
| distance_in_m | Distance in metres (as the crow flies) from the coordinates provided to the collection point | Yes | 1500 |
| full_address | Human readable street address for the collection point | Yes | 62 Wilson Street, Wanganui 4500 |
| id | Location ID for the collection point | Yes | 99061 |
| hours | Array listing the openin and closing hours of the collection point for each day of the week | Yes | See Hours Array Parameters |
Hours Array Parameters
The following lists the fields in the hours object.
| Field Name | Description | Mand | Example |
|---|---|---|---|
| day | Indicates the day of the week where 0 = Sunday through 6 = Saturday | Yes | 2 |
| open | Time of opening for day indicated in day parameter using 24 hour clock | No | 08:00 |
| closed | Time of closing for day indicated in day parameter using 24 hour clock. If location not open, then parameter set to 'true'. | Yes | 17:30 |
Error Response Elements
| Field Name | Description | Mand | Example |
|---|---|---|---|
| success | Returns if request is successful | Yes | false |
| errors | Error object with error details | Y if success =false | See Error Object Parameters below |
| message_id | The unique message identifier | Yes | ec608f40-2a8b-11e5-a9c0-025c481d35ef |
Error Object Parameters
| Field Name | Description | Example |
|---|---|---|
| code | Error code where first 3 digits are http status code, last three digits identify error type | 400002 |
| message | Description of error code | Invalid Parameter(s) |
| details | Description of specific error | Latitude cannot be null. |
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
Success Sample:
{
"success": true,
"locations": [
{
"company_name": "Wanganui CourierPost Depot",
"lat": -39.933741,
"lng": 175.046749,
"phone": "0800 268 7437",
"full_address": "62 Wilson Street, Wanganui 4500",
"id": 99061,
"hours": [
{
"day": 0,
"open": "08:00",
"close": "17:30"
},
{
"day": 1,
"open": "08:00",
"close": "17:30"
},
{
"day": 2,
"open": "08:00",
"close": "17:30"
},
{
"day": 3,
"open": "08:00",
"close": "17:30"
},
{
"day": 4,
"open": "08:00",
"close": "17:30"
},
{
"day": 5,
"open": "09:00",
"close": "12:30"
},
{
"day": 6,
"closed": true
}
],
"distance_in_m": 2619,
"address_details": {
"address_line_1": "62 Wilson Street",
"suburb": "Wanganui",
"city": "Wanganui",
"post_code": "4500"
}
},
{
"company_name": "Palmerston North CourierPost Depot",
"lat": -40.32668,
"lng": 175.619298,
"phone": "0800 268 7437",
"full_address": "99 McGregor Street, Milson, Palmerston North 4414",
"id": 99060,
"hours": [
{
"day": 0,
"open": "08:00",
"close": "18:00"
},
{
"day": 1,
"open": "08:00",
"close": "18:00"
},
{
"day": 2,
"open": "08:00",
"close": "18:00"
},
{
"day": 3,
"open": "08:00",
"close": "18:00"
},
{
"day": 4,
"open": "08:00",
"close": "18:00"
},
{
"day": 5,
"open": "08:00",
"close": "12:00"
},
{
"day": 6,
"closed": true
}
],
"distance_in_m": 63083,
"address_details": {
"address_line_1": "99 McGregor Street",
"suburb": "Milson",
"city": "Palmerston North",
"post_code": "4414"
}
},
{
"company_name": "Merrilands Lotto and Post",
"lat": -39.066579,
"lng": 174.102856,
"phone": "06 758 0753",
"full_address": "200 Mangorei Road, Merrilands, New Plymouth 4312",
"id": 72366,
"hours": [
{
"day": 0,
"open": "09:00",
"close": "17:00"
},
{
"day": 1,
"open": "09:00",
"close": "17:00"
},
{
"day": 2,
"open": "09:00",
"close": "17:00"
},
{
"day": 3,
"open": "09:00",
"close": "17:00"
},
{
"day": 4,
"open": "09:00",
"close": "17:00"
},
{
"day": 5,
"closed": true
},
{
"day": 6,
"closed": true
}
],
"distance_in_m": 128090,
"address_details": {
"address_line_1": "200 Mangorei Road",
"suburb": "Merrilands",
"city": "New Plymouth",
"post_code": "4312"
}
},
{
"company_name": "Bell Block Lotto and Book Centre",
"lat": -39.035667,
"lng": 174.142533,
"phone": "06 755 1038",
"full_address": "7 Bell Block Court, Bell Block, New Plymouth 4312",
"id": 72128,
"hours": [
{
"day": 0,
"open": "08:30",
"close": "17:30"
},
{
"day": 1,
"open": "08:30",
"close": "17:30"
},
{
"day": 2,
"open": "08:30",
"close": "18:30"
},
{
"day": 3,
"open": "08:30",
"close": "17:30"
},
{
"day": 4,
"open": "08:30",
"close": "17:30"
},
{
"day": 5,
"open": "08:30",
"close": "19:00"
},
{
"day": 6,
"closed": true
}
],
"distance_in_m": 128578,
"address_details": {
"address_line_1": "7 Bell Block Court",
"suburb": "Bell Block",
"city": "New Plymouth",
"post_code": "4312"
}
},
{
"company_name": "New Plymouth CourierPost Depot",
"lat": -39.048723,
"lng": 174.109921,
"phone": "0800 268 7437",
"full_address": "2 Smart Road, Waiwhakaiho, New Plymouth 4312",
"id": 99066,
"hours": [
{
"day": 0,
"open": "08:00",
"close": "17:30"
},
{
"day": 1,
"open": "08:00",
"close": "17:30"
},
{
"day": 2,
"open": "08:00",
"close": "17:30"
},
{
"day": 3,
"open": "08:00",
"close": "17:30"
},
{
"day": 4,
"open": "08:00",
"close": "17:30"
},
{
"day": 5,
"open": "08:00",
"close": "11:00"
},
{
"day": 6,
"closed": true
}
],
"distance_in_m": 129219,
"address_details": {
"address_line_1": "2 Smart Road",
"suburb": "Waiwhakaiho",
"city": "New Plymouth",
"post_code": "4312"
}
}
],
"message_id": "d413cb59-9aab-48a3-bdd9-7d62ecf9027c"
}
Failure Sample:
{
"success": false,
"errors": [ {
"code": "400002",
"message": "Invalid parameter(s)",
"details": "Latitude cannot be null."
}],
"message_id": "28eed9bd-8ea5-4167-85d8-a20d4a5e7a42"
}