This article explains the logic behind how we validate your addresses through our API and what could be causing your API error when generating a consignment.
Address Validation Logic Process
Our Address Validation logic works based on the process of elimination through the following steps:
- The API checks the receiver coordinates
- If it fails, it then checks Street & Suburb
-
If it still fails, it will check the declared Suburb & City
At this point; it will be invalidated with warnings included in the response. - If all three checks fail, then it will return an error
1. The API checks the receiver coordinates first
The API will consider the latitude and longitude as the first check to provide the rates.
Even if the Street Address is incorrect, the API will still rate it according to the coordinates. However, the Street Address is needed as it will be the basis for the driver as to where it will be delivered. It must be a human-readable address.
| Declaration | Comments | Result |
|---|---|---|
|
|
API will accept this, and the item will be delivered. This is the ideal outcome. |
|
|
API will accept this but there could be potential issues with delivery |
|
|
API may accept this as long as the coordinates are in New Zealand, but the rate and branch code would be incorrect. The item will be delivered to the address declared, but there could be issues and delays. |
|
|
API will reject this request and return an error. |
2. If it fails, then it checks on Street & Suburb
If no coordinates are provided, then the API will try and search for the address declared.
Examples:
| Declaration | Comment | Result |
|---|---|---|
|
|
API will try and locate the address based on the street and suburb and will rate it accordingly, which will include the surcharges. |
|
|
API will fail to locate the address and move on to the next check. |
3. If it still fails then it will check the suburb, city & postcode (with accuracy warnings)
At this point, it will be invalidated with warnings included in the response.
The location will only be estimated, so API cannot include the Residential charge or Rural charges. These fees may be recovered after delivery occurs.
Saturday Delivery will not be available.
Delivery is subject to the quality of the human-readable address
Example:
Declaration |
Comment |
Result |
|---|---|---|
|
Street: 32 Boootha Road Suburb: Penrose Town: Auckland Lat: Long: Postcode: |
No Coordinates Incorrect Street Name (misspelled) No Postcode |
API will accept this based on the suburb & town declaration. However, the surcharges will not be included. A warning will be returned. No PFE rates - Rural and Saturday Delivery not available. |
|
Street: 32 Boootha Road Suburb: Penrose Town: Lat: Long: Postcode: 1061 |
No Coordinates Incorrect Street Name (misspelled) Only have City or Suburb but not both |
API will accept this based on the suburb & postcode declaration. However, the surcharges will not be included. A warning will be returned. No PFE rates - Rural and Saturday Delivery not available. |
|
Street: 32 Boootha Road Suburb: Town: Lat: Long: Postcode: 1061 |
No Coordinates Incorrect Street Name (misspelled) No City & Suburb |
API will accept this based on the postcode however this may not be deliverable due to missing/unclear declarations. A warning will be returned. No PFE rates - Rural and Saturday Delivery not available. |
API will return the following warning:
4. If all three checks fail, then it will return an error
Examples:
| Declaration | Comment | Result |
|---|---|---|
|
|
API will return an error |
|
|
API will return an error |
The API will return the following error:
