Collection and Drop Off API

(0 reviews)

Collection Addresses

Resource URL

UAT:

https://api.uat.nzpost.co.nz/collectionaddress/v1/addresses/{address_id}

Production:

https://api.nzpost.co.nz/collectionaddress/v1/addresses/{address_id}

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.

Resource Description

This resource uses an address_id to retrieve address details for the address_id and a list of nearby collection points. The address_Id can be obtained using the “Search for Address” resource in the ParcelAddress API. Notes: Please make “ParcelAddress” a link to the ParcelAddress 2.0 page in the developer portal.

Please note that all request parameters should be in lower case.

Request Parameters

The following list the request parameters for the "addresses" resource.

Field Name	Description	Mandatory	Example
address_id	NZ Post address identifier as URI parameter	Yes	12345
count	Number of parcel collection delivery location address records to be returned(min:1,max:10,default:1)	No	1

Sample Request

https://api.nzpost.co.nz/collectionaddress/v1/addresses/12345?count=1

Response Parameters

The following lists the required fields in the Get Address Detail response message:

Field Name	Description	Mandatory	Example
success	Returns if request is successful	Yes	True
address	Address object with address details	Y if success = true	JSON Object

Address Object

The following lists the address object.

Field Name	Description	Mandatory	Example
street_number	The street number of the address	Yes	71
street	The name of the street	Yes	Oregon
street_type	Type of the street	Yes	Street
suburb	The name of the suburb the address resides in	Yes	Ocean Grove
city	The name of the city the address resides in	Yes	Dunedin
is_rural_delivery	Determines if this is a rural or an urban address (true for rural)	Yes	false
postcode	The postcode associated with the address	Yes	9013
longitude	The GPS longitude coordinate if the data exists	Yes	170.552
latitude	The GPS latitude coordinate if the data exists	Yes	-45.9041
run_number	The run number that indicates which courier run will service this address	Yes	DCP025
depot_name	The name of the depot that services this address	Yes	Dunedin Depot
country	The name of the country the address resides	Yes	New Zealand
dpid	Delivery point identifier	Yes	54218
pcd_locations	Contains array of collection location objects. The number of objects will not exceed the ‘count’ value defined.	Yes if success=true	JSON Object
distance_in_m	Distance between the address and collection location	Yes	4159
address_details	Address Details for the collection point	Yes	JSON Object

Pcd_Locations Object Parameters

The following lists the fields in the locations object.

Field Name	Description	Mandatory	Example
company_name	Name of the company hosting the collection point	Yes	Dunedin CourierPost Depot
lat	Longitude of the collection Point	Yes	-45.888675
lng	Longitude of the collection Point	Yes	170.503033
phone	Contact phone number for the collection point	Yes	0800 268 7437
full_address	Human readable street address for the collection point	Yes	Strathallan Street, South Dunedin, Dunedin 9012
id	Location ID for the collection point	Yes	99054
hours	Array listing the opening and closing hours of the collection point for each day of the week	Yes	JSON Object

Hours Array Parameters

The following lists the field in the hours object.

Field Name	Description	Mandatory	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:30
close	Time of closing for day indicated in day parameter using 24 hour clock. If location not open, then parameter set to 'true'	Yes	18:00

Address_details Object Parameters

The following lists the field in the address_details object.

Field Name	Description	Mandatory	Example
address_line_1	Details of the street number and building name	Yes	5 Strathallan Street
suburb	The name of the suburb the address resides	Yes	South Dunedin
city	The city the address resides in	Yes	Dunedin
post_code	The postcode associated with the address	Yes	9012

Response Message - CollectionAddress API Response Message

Sample success response:

  {
    "success": true,
    "address": {
      "street_number": 71,
      "street": "Oregon",
      "street_type": "Street",
      "suburb": "Ocean Grove",
      "city": "Dunedin",
      "is_rural_delivery": false,
      "postcode": "9013",
      "longitude": 170.552,
      "latitude": -45.9041,
      "run_number": "DCP025  ",
      "depot_name": "Dunedin Depot",
      "country": "New Zealand",
      "dpid": "54218",
      "pcd_locations": [
        {
          "company_name": "Dunedin CourierPost Depot",
          "lat": -45.888675,
          "lng": 170.503033,
          "phone": "0800 268 7437",
          "full_address": "5 Strathallan Street, South Dunedin, Dunedin 9012",
          "id": 99054,
          "hours": [
            {
              "day": 0,
              "open": "08:30",
              "close": "18:00"
            },
            {
              "day": 1,
              "open": "08:30",
              "close": "18:00"
            },
            {
              "day": 2,
              "open": "08:30",
              "close": "18:00"
            },
            {
              "day": 3,
              "open": "08:30",
              "close": "18:00"
            },
            {
              "day": 4,
              "open": "08:30",
              "close": "18:00"
            },
            {
              "day": 5,
              "open": "09:00",
              "close": "12:00"
            },
            {
              "day": 6,
              "closed": true
            }
          ],
          "distance_in_m": 4159,
          "address_details": {
            "address_line_1": "5 Strathallan Street",
            "suburb": "South Dunedin",
            "city": "Dunedin",
            "post_code": "9012"
          }
          }
      ]
    },
    "message_id": "618a5799-85e3-4559-8a62-280f231a26b3"
  }

Response message- CollectionAddress API Error Response Message

Sample failure response:

 {
   "success": false,
   "errors": [ {
   "code": "40001",
   "message": "Bad Request",
   "details": "You may have entered invalid or missing input parameters,
   please consult the API documentation if in doubt." } ],
   "message_id": "4dd9d6d0-ab89-11e6-b31d-0692fd96189f"
 }

HTTP Status Codes

Note that some error messages are customized 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
404	Not Found
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	Unauthorized access, please contact administrator
500001	General Exception
500002	System(s) offline