ParcelAddress API

Download
โ˜…โ˜…โ˜…โ˜…โ˜…
(0 reviews)

Search for International Address

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parceladdress/2.0/international/addresses
Production:
https://api.nzpost.co.nz/parceladdress/2.0/international/addresses

Resource Description

Returns a list of suggested addresses for a given country code and address fragment. This resource is ![Alt text](https://developers.google.com/places/documentation/images/powered-by-google-on-white.png).

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
country_codeCountry code for address countryNoUS
countThe maximum number of matching results to be returnedYes5
qAddress fragment to search for suggestionsYes3800 LaPasa

Country Code

Valid country codes can be found here. In the future, a method will be provided that will return a complete and up-to-date list of country codes.

Sample Request

https://api.nzpost.co.nz/parceladdress/2.0/international/addresses?q=38%20Lap&count=5&country_code=US

Business Rules

The following business rules are applied on each international/addresses request:

NameDescription
BR001The address fragment (parameter โ€˜qโ€™) must contain at least 4 characters after the leading and following spaces are removed by the API code. If less than 4 characters, an error message will be returned to the requester.
BR002If no count value is provided, a default number of responses is returned. The default is set to 5 records.
BR003If the count value provided is greater than 5 and there are more than 5 addresses matching the address fragment, only 5 address records will be returned to the merchant.

Response Parameters

The following lists the required fields in the /addresses response message.

Field NameDescriptionMandExample
successReturns if request is successfulYesfalse
addressesContains array of address objects. The number of object will not exceed the โ€˜Countโ€™ value defined.Y if success = true"addresses":[]

Address Object

The following lists the fields in the address object.

Field NameDescriptionMandExample
address_idA unique id for representing the addressYesEjAzODAwIExhIFBhc2FkYSBBdmUsIExhcyBWZWdhcywgTlYsIFVuaXRlZCBTdGF0ZXM
full_addressHuman-readable format of the addressYes if success = true3800 La Pasada Ave, Las Vegas, NV 89102, USA

Error Response Elements

Field NameDescriptionMandExample
successReturns if request is successfulYesfalse
errorsError object with error detailsYes 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 errorAddress prefix must be at least 4 characters, not including spaces at the beginning or end.

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": true,
   "addresses":    [
            {
         "full_address": "38 Lapstone Street, The Ponds, New South Wales, Australia",
         "address_id": "EjkzOCBMYXBzdG9uZSBTdHJlZXQsIFRoZSBQb25kcywgTmV3IFNvdXRoIFdhbGVzLCBBdXN0cmFsaWE"
      },
            {
         "full_address": "38 Lapis Crescent, Bardwell Valley, New South Wales, Australia",
         "address_id": "Ej4zOCBMYXBpcyBDcmVzY2VudCwgQmFyZHdlbGwgVmFsbGV5LCBOZXcgU291dGggV2FsZXMsIEF1c3RyYWxpYQ"
      },
            {
         "full_address": "38 Lapish Avenue, Ashfield, New South Wales, Australia",
         "address_id": "EjYzOCBMYXBpc2ggQXZlbnVlLCBBc2hmaWVsZCwgTmV3IFNvdXRoIFdhbGVzLCBBdXN0cmFsaWE"
      },
            {
         "full_address": "38 Lapraik Street, Ascot, Queensland, Australia",
         "address_id": "Ei8zOCBMYXByYWlrIFN0cmVldCwgQXNjb3QsIFF1ZWVuc2xhbmQsIEF1c3RyYWxpYQ"
      },
            {
         "full_address": "38 Lapwing Way, Cranebrook, New South Wales, Australia",
         "address_id": "EjYzOCBMYXB3aW5nIFdheSwgQ3JhbmVicm9vaywgTmV3IFNvdXRoIFdhbGVzLCBBdXN0cmFsaWE"
      }
   ],
   "message_id": "7f4b5f60-0d7c-11e5-ab23-025935216c03"
}

Reviews