CollectionAddress API

Download
Opens request access modal
(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

AttributeDetail
Response FormatJSON
Requires AuthenticationYes
Rate Limited15 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 NameDescriptionMandatoryExample
address_idNZ Post address identifier as URI parameterYes12345
countNumber of parcel collection delivery location address records to be returned(min:1,max:10,default:1)No1

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 NameDescriptionMandatoryExample
successReturns if request is successfulYesTrue
addressAddress object with address detailsY if success = trueJSON Object

Address Object

The following lists the address object.

Field NameDescriptionMandatoryExample
street_numberThe street number of the addressYes71
streetThe name of the streetYesOregon
street_typeType of the streetYesStreet
suburbThe name of the suburb the address resides inYesOcean Grove
cityThe name of the city the address resides inYesDunedin
is_rural_deliveryDetermines if this is a rural or an urban address (true for rural)Yesfalse
postcodeThe postcode associated with the addressYes9013
longitudeThe GPS longitude coordinate if the data existsYes170.552
latitudeThe GPS latitude coordinate if the data existsYes-45.9041
run_numberThe run number that indicates which courier run will service this addressYesDCP025
depot_nameThe name of the depot that services this addressYesDunedin Depot
countryThe name of the country the address residesYesNew Zealand
dpidDelivery point identifierYes54218
pcd_locationsContains array of collection location objects. The number of objects will not exceed the ‘count’ value defined.Yes if success=trueJSON Object
distance_in_mDistance between the address and collection locationYes4159
address_detailsAddress Details for the collection pointYesJSON Object

Pcd_Locations Object Parameters

The following lists the fields in the locations object.

Field NameDescriptionMandatoryExample
company_nameName of the company hosting the collection pointYesDunedin CourierPost Depot
latLongitude of the collection PointYes-45.888675
lngLongitude of the collection PointYes170.503033
phoneContact phone number for the collection pointYes0800 268 7437
full_addressHuman readable street address for the collection pointYesStrathallan Street, South Dunedin, Dunedin 9012
idLocation ID for the collection pointYes99054
hoursArray listing the opening and closing hours of the collection point for each day of the weekYesJSON Object

Hours Array Parameters

The following lists the field in the hours object.

Field NameDescriptionMandatoryExample
dayIndicates the day of the week where 0 = Sunday through 6 = SaturdayYes2
openTime of opening for day indicated in day parameter using 24 hour clockNo08:30
closeTime of closing for day indicated in day parameter using 24 hour clock. If location not open, then parameter set to 'true'Yes18:00

Address_details Object Parameters

The following lists the field in the address_details object.

Field NameDescriptionMandatoryExample
address_line_1Details of the street number and building nameYes5 Strathallan Street
suburbThe name of the suburb the address residesYesSouth Dunedin
cityThe city the address resides inYesDunedin
post_codeThe postcode associated with the addressYes9012

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

CodeMessage
200Success
400Bad Request
401Unauthorized
403Forbidden
404Not Found
409Invalid request
500System unavailable

Error Codes

CodeMessage
200001Partial results returned,not all system(s) have responded
200002All sources responded,data may be incomplete
400001Parameter(s) missing
400002Invalid parameter(s)
400003Non mutually exclusive parameters detected
401001Unauthorized access, please contact administrator
500001General Exception
500002System(s) offline


Reviews