Loading...
Sign in to see the examples with your own API key.

Validate

The Validate API confirms an address written on one line. It reads the unit, level, lot, number, street, suburb, state and postcode however they are written, and answers with the one G-NAF address the line describes — or says it cannot, rather than guess.

Request

GET POST https://api.getaddress.io/validate/{address}?api-key={your-api-key}

URL-encode the address, but leave a unit's slash as it is: /validate/3/12%20Chapel%20St%20… reads as unit 3, number 12.

Responses

Status When Body Look-ups
200 Exactly one address fits the line. The address, exactly as Get returns it. 1
300 Several addresses fit; or the line names no suburb or postcode to place it; or it names a building G-NAF holds only as its units, shops and levels. candidates: their ids, for Get. Up to 10. 0
404 No address fits every word of the line. A problem description. 0
Example: found

Request

GET https://api.getaddress.io/validate/12 Acland St, St Kilda VIC 3182?api-key={your-api-key}

Response (200 — every field Get returns; some shown)

{
    "address_label": "12 ACLAND ST, ST KILDA VIC 3182",
    "address_detail_pid": "GAVIC419664638",
    "address_status": "current",
    "locality_name": "ST KILDA",
    "number_first": "12",
    "postcode": "3182",
    "state": "VIC",
    "street_name": "ACLAND",
    "street_type": "STREET",
    …
}
Example: ambiguous

'1 Pitt St' names no suburb or postcode, and there is a 1 Pitt Street in several.

Response (300)

{
    "candidates": [
        "GANSW705419145",
        "GAVIC421516744",
        "GANSW716822204",
        …
    ]
}

How a line is read

Usage

  • A found address (200) counts as 1 look-up against your plan's daily allowance.
  • Ambiguous (300) and not found (404) cost nothing, but count toward the rate limit.
  • An address is at most 200 characters.

Domain Tokens

To avoid exposing your API key in browser code, Domain Tokens can be used in place of your API key. A Domain Token is generated for one domain and works on that domain and its sub-domains.

A Domain Token can only be used for address and place look-ups — /autocomplete, /get, /validate, /distance, /location, /get-location, /nearest-location and /typeahead. It cannot read your usage, so it carries none of the access your API key does. A revoked Domain Token stops working within a minute.

Each token is throttled per visitor IP address: 60 look-ups per minute by default, and the limit can be set per token (1–10,000 look-ups over a window of 1–60 minutes). Requests over the limit get 429 with a Retry-After header. There is a second ceiling on the token's total traffic across all visitors, so a token being used somewhere other than your site is throttled even when every request arrives from a different address.

Look-ups made with a Domain Token count against your plan's allowance exactly as look-ups made with your API key do.

A Domain Token is also what carries the free Google Places fallback: with it switched on, an autocomplete that finds nothing hands the widget your own Google API key.

What a Domain Token is, and what it isn't. It keeps your API key out of your page source, and it makes a token copied out of your page close to worthless: it works only on your domain, only for look-ups, and only at the rate you set. It is not a secret — you publish it in your page — and the domain check reads request headers, which a determined caller can set to anything. The throttle is the protection; set it no higher than your address form actually needs.

Rate Limiting

Your subscription's plan will limit the number of requests per 5 minute span. Exceeding your plan's rate limit will return a HTTP 429 response.
The Retry-After HTTP header contains the number of seconds until a successful retry can be made.

Top