Distance
The Distance API returns the straight-line distance in metres between two addresses, two locations, or two points. It answers metres and nothing else — never either point's coordinates.
Between two addresses or locations
Request
GET https://api.getaddress.io/distance/{from-id}/{to-id}?api-key={your-api-key} Each id is either an address's address_detail_pid — the id of an Autocomplete suggestion, or one you stored — or a place's location id, the id of a Location suggestion. A location is measured from its centre. The two ids may be of different kinds.
Example1 Pitt St, Sydney to 12 Acland St, St Kilda.
GET https://api.getaddress.io/distance/GANSW721316793/GAVIC419664638?api-key={your-api-key} Response
{
"metres": 716312
}
Sydney NSW 2000 to Melbourne VIC 3000, centre to centre.
GET https://api.getaddress.io/distance/sydney-nsw-2000/melbourne-vic-3000?api-key={your-api-key} Response
{
"metres": 713306
}
Between two points
Request
GET https://api.getaddress.io/distance/{latitude}/{longitude}/to/{latitude}/{longitude}?api-key={your-api-key} GET https://api.getaddress.io/distance/-33.8612/151.2107/to/-33.8605/151.2073?api-key={your-api-key} Response
{
"metres": 322
}
Response Fields
| Field | Description |
|---|---|
| metres | The straight-line (great-circle) distance in whole metres, between the addresses' G-NAF geocodes, the locations' centres or the two points. As the crow flies — not a driving distance. |
Usage
- Distance queries are rate limited but do not increase your usage.
- An unknown id, or an address with no geocode, returns 404 naming which of the two (from or to).
- An id G-NAF has since withdrawn still measures, as it still resolves with Get.
- A latitude outside −90 to 90, or a longitude outside −180 to 180, returns 400.
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.