Nearest
The Nearest API returns the addresses nearest a latitude and longitude, nearest first, each with its distance in metres — also known as reverse geocoding. Use it for a map pin, a GPS fix or a “use my location” button.
Step 1.
Request
GET POST https://api.getaddress.io/nearest/{latitude}/{longitude}?api-key={your-api-key} The two addresses nearest Sydney Town Hall.
Request
GET https://api.getaddress.io/nearest/-33.8732/151.2061?api-key={your-api-key}&top=2 Response
{
"suggestions":
[
{
"address": "456 KENT ST, SYDNEY NSW 2000",
"url": "/get/GANSW713111479",
"id": "GANSW713111479",
"distance": 7
},
{
"address": "483A GEORGE ST, SYDNEY NSW 2000",
"url": "/get/GANSW706029328",
"id": "GANSW706029328",
"distance": 7
}
]
}
Step 2.
Pass the chosen id to the Get API for the full address, exactly as with an
Autocomplete suggestion.
Options
| Name | Default | Description | Type |
|---|---|---|---|
| top | 1 | The number of addresses to return, 1–20. A query parameter. | Number |
| radius | 0.2 | How far from the point to look, in kilometres: more than 0, at most 1. A query parameter. | Number |
Response Fields
| Field | Description |
|---|---|
| address / url / id | As an Autocomplete suggestion. |
| distance | Straight-line distance from the point to the address's position, in whole metres. |
Which addresses
- Flats, shops and levels are left out. They share their building's position, so the building's own address stands for them.
- Several addresses can share one position — two street frontages of one site, say — and come back at the same distance.
- A position is where G-NAF places the address, usually the middle of the property, so the nearest address is not always the one whose door is nearest.
Usage
- A request that finds an address counts as 1 look-up against your plan's daily allowance.
- No address within the radius returns an empty list and costs nothing.
- A latitude outside −90 to 90, a longitude outside −180 to 180, or a radius outside 0 to 1 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, /nearest, /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.