ParcelAddress API

(0 reviews)

Australian Address Lookup

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parceladdress/2.0/australia/addresses/{address_id}

Production:

https://api.nzpost.co.nz/parceladdress/2.0/australia/addresses/{address_id}

Resource Description

This resource is intended to be used in conjunction with the Get International Address Detail resource. The Australian Address Lookup returns the detailed information for a single address identifier for an address in Australia. This resource is Alt text . The details returned from Google Places is mapped to NZ Post standard address fields. The Australian Address Lookup resource is useful to the merchant who sends a regular volume of parcel to Australian destinations and also consumes the ParcelLabel functionality.

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
address_id	International address identifier used by Google Places.	Yes	EjAzODAwIExhIFBhc2FkYSBBdmUsIExhcyBWZWdhcywgTlYsIFVuaXRlZCBTdGF0ZXM

Sample Request

https://api.nzpost.co.nz/parceladdress/2.0/australia/addresses/ChIJN1t_tDeuEmsRUsoyG83frY4%26key%3DAIzaSyAC711805j5JJgCpY7RV662jayqffVS-jY

Response Parameters

The following lists the required fields in the Australian Address Lookup response message:

Field Name	Description	Mand	Example
success	Returns if request is successful	Yes	false
address	Address object with address details	Y if success = true	"address": {}
message_id	The unique message identifier	Yes	ec608f40-2a8b-11e5-a9c0-025c481d35ef

Address Object

The following lists the required fields in the address object.

Field Name	Description	Mand	Example
street_number	The street address number	No	139
street	The name of the street	No	Mitchell St
suburb	The name of the suburb the address resides	No	Larrakeyah
state	Name of the Australian state	No	Northern Territory
state_code	Code for the Australian state	No	NT
postcode	The postcode associated with the address	No	0820
longitude	The GPS longitude coordinate if the data exists	No	130.832234
latitude	The GPS latitude coordinate if the data exists	No	-12.456088
country	The name of the country the address resides	No	Australia
country_code	The code for the country	No	AU
formatted_address	The "human readable" address	No	139 Mitchell St, Larrakeyah NT 0820, Australia

Error Response Elements

Field Name	Description	Mand	Example
success	Returns if request is successful	Yes	false
errors	Error object with error details	Yes 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	Address 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

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

Sample success response:

{
   "success": true,
   "address":    {
      "street_number": "139",
      "street": "Mitchell St",
      "suburb": "Larrakeyah",
      "state": "Northern Territory",
      "state_code": "NT",
      "postcode": "0820",
      "longitude": 130.832234,
      "latitude": -12.456088,
      "country": "Australia",
      "country_code": "AU",
      "formatted_address": "139 Mitchell St, Larrakeyah NT 0820, Australia"
   },
   "message_id": "27009370-2a69-11e5-a9c0-025c481d35ef"
}

Sample failure responses:

{
   "success": false,
   "errors": [   {
      "code": "40002",
      "message": "Invalid Parameter",
      "details": "International Address ID is invalid"
   }],
   "message_id": "ec608f40-2a8b-11e5-a9c0-025c481d35ef"
}

{
   "success": false,
   "errors": [   {
      "code": "40002",
      "message": "Invalid Parameter",
      "details": "International Address ID is not an Australian Address"
   }],
   "message_id": "ed0819e0-2a8b-11e5-a9c0-025c481d35ef"
}