ParcelAddress API

Download
(0 reviews)

Get Address Detail - dpid

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parceladdress/2.0/domestic/addresses/dpid/{dpid}

Production:

https://api.nzpost.co.nz/parceladdress/2.0/domestic/addresses/dpid/{dpid}

Resource Description

Returns the detailed information for a single dpid.

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.

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

Request Parameters

Field NameDescriptionMandExample
dpidNZ Post address identifierYes216250

Sample Request

https://api.nzpost.co.nz/parceladdress/2.0/domestic/addresses/dpid/12345

Response Parameters

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

Field NameDescriptionMandExample
SuccessReturns if request is successfulYesTrue
AddressAddress object with address detailsY if success = true"address": {}

Address Object

The following lists the required fields in the address object.

Field NameDescriptionMandExample
building_nameThe name of the buildingNoSky Tower
company_nameThe name of the company associated with the address (rarely available)NoAcme Inventions
depot_nameThe name of the depot that services this addressNoAkl City Fleet
floorThe floor number (if it exists)No3
latitudeThe GPS latitude coordinate if the data existsYes-45.9041
longitudeThe GPS longitude coordinate if the data existsYes170.552
postcodeThe postcode associated with the addressYes2013
is_rural_deliveryDetermines if this is a rural or a urban address (true for rural)YesTrue
rural_delivery_numberThe rural delivery number associated with the addressYes If Rural Delivery = True2
run_numberThe run number that indicates which courier run will service this addressNoDCP003
gated_community_flagIndication that address is within a gated communityNoTrue
streetThe name of the streetYesHighbrook
street_alphaThe street address alphabetic code indicating multiple delivery locations at the street number eg 25a Main Street. The "a" is the alpha.Noa
street_numberThe street address numberYes22
street_typeType of streetYesAvenue
suburbThe name of the suburb the address residesYesPakuranga
cityThe city the address resides inYesAuckland
unit_typeThe unit type of the addressNoFlat
unit_valueThe unit value of the addressNo27
countryThe name of the country the address residesYesNew Zealand
dpidDelivery point identifierNo54218

Error Response Elements

Field NameDescriptionMandExample
successReturns if request is successfulYesfalse
errorsError object with error detailsY if success =falseSee Error Object Parameters below
message_idThe unique message identifierYesec608f40-2a8b-11e5-a9c0-025c481d35ef

Error Object Parameters

Field NameDescriptionExample
codeError code where first 3 digits are http status code, last three digits identify error type400002
messageDescription of error codeInvalid Parameter(s)
detailsDescription of specific errorNo results returned. Check your Address ID and try again.

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

CodeMessage
200Success
400Bad request
401Unauthorized
403Forbidden
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
401001Unauthorised access, please contact administrator
500001General Exception
500002System(s) offline

Sample Response

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",

   },

   "message_id": "618a5799-85e3-4559-8a62-280f231a26b3"

}



Sample failure response:

{

   "success": true,

   "errors": [   {

      "code": "400002",

      "message": "Invalid parameter(s)",

      "details": "No results returned. Check your Address ID and try again. "

   }],

   "message_id": "e5d56f1c-d6f7-4742-a7f8-c411fdb6cae5"

}


Reviews