LocateAU
Log in Get an API key
Home Products Pricing Docs Log in Get an API key

Five endpoints, one dataset.

Each endpoint answers a different question about the same G-NAF Core record. This page explains what each one is for. The full reference lives in the API documentation.

POST /v1/validate

Address validation

Takes an address as a person typed it and decides which G-NAF record it refers to, if any.

Typical use Checkout and onboarding forms, where you need to know an address is real before you ship to it or bill it.
match_score and match_quality are calculated per request. They describe this comparison, not the address, so they are never stored on the record. 
POST /v1/validate

{
  "address": "unit 217/181 fitzroy street, st kilda 3182"
}
{
  "match_quality": "exact",
  "match_score": 0.98,
  "address_id": "GAVIC719373775",
  "address_label": "UNIT 217 181 FITZROY ST ST KILDA VIC 3182",
  "components": {
    "flat_type": "UNIT",
    "flat_number": "217",
    "number_first": "181",
    "street_name": "FITZROY",
    "street_type": "ST",
    "locality_name": "ST KILDA",
    "state": "VIC",
    "postcode": "3182"
  },
  "matched": {
    "street_name": "exact",
    "locality_name": "exact",
    "postcode": "exact",
    "state": "inferred"
  }
}
POST /v1/geocode

Forward geocoding

Runs the same matching engine as validation, then returns the coordinates on the record it matched.

Typical use Placing a customer on a map, calculating service areas, or assigning a delivery run.
geocode_type tells you what the coordinate actually describes. A property centroid and a street locality centroid are both valid results with very different precision. 
POST /v1/geocode

{
  "address": "181 Fitzroy St, St Kilda VIC 3182"
}
{
  "address_id": "GAVIC719373775",
  "address_label": "UNIT 217 181 FITZROY ST ST KILDA VIC 3182",
  "latitude": -37.85773139,
  "longitude": 144.98132860,
  "geocode_type": "FRONTAGE CENTRE SETBACK",
  "match_quality": "exact"
}
GET /v1/autocomplete

Autocomplete

Turns partial text into a short list of candidate addresses while someone is still typing.

Typical use Address fields that finish themselves, so the address arrives clean instead of being corrected later.
Responses stay deliberately small. You get an identifier and a label, then call address details once the user picks one. 
GET /v1/autocomplete?q=181+fitzroy+st+st+ki&limit=5
{
  "suggestions": [
    {
      "address_id": "GAVIC719373775",
      "address_label": "UNIT 217 181 FITZROY ST ST KILDA VIC 3182"
    },
    {
      "address_id": "GAVIC425312091",
      "address_label": "181 FITZROY ST ST KILDA VIC 3182"
    }
  ]
}
GET /v1/addresses/{address_id}

Address details

Returns the full record for an identifier you already hold. A direct lookup with no matching involved.

Typical use Rehydrating a stored address, or fetching the complete record after an autocomplete selection.
Store address_id rather than the formatted string. The identifier is persistent, so the record stays resolvable across dataset releases. 
GET /v1/addresses/GAVIC719373775
{
  "address_id": "GAVIC719373775",
  "address_label": "UNIT 217 181 FITZROY ST ST KILDA VIC 3182",
  "flat_type": "UNIT",
  "flat_number": "217",
  "number_first": "181",
  "street_name": "FITZROY",
  "street_type": "ST",
  "locality_name": "ST KILDA",
  "state": "VIC",
  "postcode": "3182",
  "mesh_block": "21329150000",
  "primary_secondary": "S",
  "primary_address_id": "GAVIC425312091",
  "latitude": -37.85773139,
  "longitude": 144.98132860,
  "geocode_type": "FRONTAGE CENTRE SETBACK",
  "date_created": "2019-04-24"
}
GET /v1/reverse-geocode

Reverse geocoding

Takes a coordinate and a radius, and returns the addresses near it, closest first.

Typical use Working out where a driver, a device or a photograph actually is, in terms a person can read.
distance_metres describes the gap between your point and the address, so it is computed per request rather than stored. 
GET /v1/reverse-geocode
  ?latitude=-37.85773
  &longitude=144.98133
  &radius=100
  &limit=5
{
  "results": [
    {
      "address_id": "GAVIC719373775",
      "address_label": "UNIT 217 181 FITZROY ST ST KILDA VIC 3182",
      "latitude": -37.85773139,
      "longitude": 144.98132860,
      "geocode_type": "FRONTAGE CENTRE SETBACK",
      "distance_metres": 0.2
    }
  ]
}

The reference has the rest.

Full parameters, error shapes and status codes are generated from the API schema.

Get an API key Read the docs