Principles꞉ Address Validation

Summary

Endpoint	Verb	Paging	Description
/api/addresses/validate	POST		validates and geocodes a given address

When saving or updating an address object, either as part of a Contact or Consignment, the address has to be considered valid to proceed.

The the principle validation rules for addresses supplied are:

• a street address is provided
• a locality (suburb) is provided
• a postcode is provided
• a valid country is provided (AU, NZ or ZA)
• a lat and lng are provided (optional: see validation paths below)

A typical a address object is:

{
  "addressId": 0,
  "streetAddress": "",
  "additionalDetails": "",
  "locality": "",
  "stateOrProvince": "",
  "postalCode": "",
  "country": "",
  "lat": 0,
  "lng": 0,
  "userCreated": false,
}

Validation Paths

Previously saved addresses

If a non-zero addressId is provided, this previous saved address is considered valid and is used without further checks. This is the fastest method of validation

Lat and lng provided

If valid lat and lng co-ordinates are provided, the geocoding process is skipped, with these values begin considered correct. The userCreated flag set to true for all addresses with user provided co-ordinates.

Address field only supplied

Each of the following address fields are validated:

• streetAddress (cannot be blank)
• locality (must match a locality from /api/addresses/postalcodes/{postalcode}/localities)
• stateOrProvince
• postalCode (must must a postal code from /api/addresses/localities/{locality}/postalcodes)
• country (must be AU, NZ or ZA)

Geocoding is then attempted on the information provided. If geocoding is successful, a lat an lng will be returned as part of the address object. Depending on the information provided many (or no) geocoding results may be returned which will require further action

As gecoding is an expensive operation, it is recommended that once you have successfully geocoded your address, that the co-ordinates are saved for future use.

Error responses

Geocoding

If multiple matches of this address occur, the HTTP response code will be 400 with a body similar to:

{
  "errors": [
    {
      "code": "GEO_ADDR_VAL",
      "message": "Address validation failed, multiple matches found (address supplied: 1 George St, Sydney NSW 2000, AU)",
      "suggestedValues": [
        "{\"PlaceId\":\"ChIJAWEuLzyuEmsR8p9SVmS6Zz4\",\"Lat\":-33.873556,\"Lng\":151.206631,\"UpdatedOn\":\"2019-01-10T14:12:07.861288+11:00\",\"UpdatedBy\":\"\",\"AddressId\":0,\"StreetAddress\":\"1 George St\",\"AdditionalDetails\":\"\",\"Locality\":\"Sydney\",\"StateOrProvince\":\"NSW\",\"PostalCode\":\"2000\",\"Country\":\"AU\",\"UserCreated\":false,\"Hash\":\"AgqCSsn3RHs7t+tapC7rtg==\"}"
      ]
    }
  ]
}

The suggested values are an array of serialised Address models which can be reused by other endpoints expecting this signature.

If no matches of this address occur, the HTTP response code will be 400 with a body similar to:

{
  "errors": [
    { 
      "code": "GEO_ADDR_VAL",
      "message": "Address validation failed, zero matches found (address supplied: 1 Clarence St, Sydney NSW 2000, AU)"
    }
  ]
}

Locality / Postalcode error responses

If we can't find the locality but can find the post code, the HTTP response code will be 400 with a body similar to:

{
  "errors": [
    { 
      "code": "PSC_PC_NF",
      "message": "Suburb with name 'Saint Ives' cannot be found",
      "suggestedValues": [
        "ST IVES",
        "ST IVES CHASE"
      ]
    }
  ]
}

If we can't find the post code but can find the locality, the HTTP response code will be 400 with a body similar to:

{
  "errors": [
    { 
      "code": "PSC_PC_NF",
      "message": "Post code with value '9999' cannot be found",
      "suggestedValues": [
        "2075",
      ]
    }
  ]
}

If neither the locality or post code can be found, the HTTP response code will be 400 with a body similar to:

{
  "errors": [
    { 
      "code": "PSC_PC_NF",
      "message": "Cannot find suburb 'Somewhere' at post code '9999'"
    }
  ]
}