Given latitude (Y) and longitude (X) GPS coordinates and an optional distance filter, the Geocode Address API will return a collection of the closes addresses.
Visit the Geocode and Reverse Geocode page to see a live demo of this API in action.
| URL | https://www.addy.co.nz/api/geocode |
|---|---|
| HTTP Request Type | GET |
The example below will make a JSON request to find the addresses closest to Victoria Park in Auckland (-36.846829, 174.754325):
curl -X GET --header 'Accept: application/json' 'https://www.addy.co.nz/api/geocode?key=demo-api-key&x=174.754325&y=-36.846829'| Parameter | Description | Type | Example |
|---|---|---|---|
| limit | Number of addresses to return per batch (default = 100, maximum = 1000) | integer | 200 |
| offset | Offset to continue the paging (default = 0) | integer | 5 |
| x | Longitute in WGS84 format | double | 174.754325 |
| y | Latitute in WGS84 format | double | -36.846829 |
| distancekm | Maximum distance in kilometers from the point. Default = 0.2 (200 metres). Maximum = 50 (km). | double | -36.846829 |
| Property | Description | Type | Example |
|---|---|---|---|
| addresses | Array of address results | address array | [{address},{address}] |
| _links | Link for paging to the next set of results | URI | /api/geocode?x=174.754325&y=-36.846829&offset=10&limit=10 |
Address Response Property Description
| Property | Description | Type | Example |
|---|---|---|---|
| id | Unique identifier for the address | integer | 5334946 |
| displayname | Full display name of the address | string | 203-271 Victoria Street West, Auckland Central, Auckland 1010 |
| distancekm | Approximate distance between the address and the coordinates | double | 0.15607143886453542 |
| _link | Link to Details API for retrieving metadata | string | /api/address/5334946 |
Response Example for retrieving the closes addresses to Victoria Park in Auckland (-36.846829, 174.754325):
https://www.addy.co.nz/api/geocode/key=demo-api-key&x=174.754325&y=-36.846829&distancekm=0.160{
"addresses": [
{
"id": 5334946,
"displayname": "203-271 Victoria Street West, Auckland Central, Auckland 1010",
"distancekm": 0.15607143886453542,
"_link": "/api/address/5334946"
},
{
"id": 5326755,
"displayname": "271 Victoria Street West, Auckland Central, Auckland 1010",
"distancekm": 0.15607143886453542,
"_link": "/api/address/5326755"
},
{
"id": 2834475,
"displayname": "203 Victoria Street West, Auckland Central, Auckland 1010",
"distancekm": 0.15640097635336167,
"_link": "/api/address/2834475"
}
],
"_links": {
"next": "/api/geocode?x=174.754325&y=-36.846829&distancekm=0.160&offset=10&limit=10"
}
}