Geocode Address API

Turn GPS coordinates into the nearest addresses with reverse geocoding

Overview

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.

FREE Geocode Address API: It is 100% free to call this API to reverse geocode NZ addresses. Sign up for free.

API Endpoint


URL https://api.addy.co.nz/geocode
HTTP Request Type GET

cURL Request

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://api.addy.co.nz/geocode?key=demo-api-key&x=174.754325&y=-36.846829'

Request Parameters


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

Response Properties


Property Description Type Example
addresses Array of address results address array [{address},{address}]
_links Link for paging to the next set of results URI /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 /address/5334946

Response Example for retrieving the closes addresses to Victoria Park in Auckland (-36.846829, 174.754325):

https://api.addy.co.nz/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": "/address/5334946"
    },
    {
      "id": 5326755,
      "displayname": "271 Victoria Street West, Auckland Central, Auckland 1010",
      "distancekm": 0.15607143886453542,
      "_link": "/address/5326755"
    },
    {
      "id": 2834475,
      "displayname": "203 Victoria Street West, Auckland Central, Auckland 1010",
      "distancekm": 0.15640097635336167,
      "_link": "/address/2834475"
    }
  ],
  "_links": {
    "next": "/geocode?x=174.754325&y=-36.846829&distancekm=0.160&offset=10&limit=10"
  }
}