Address Reverse Geocode API

This API requires authentication. See Authentication Overview for details on using API key + secret or OAuth2 bearer tokens.

This API takes GPS coordinates (latitude and longitude) and returns the nearest matching addresses, ordered by distance. It works in tandem with the Address Metadata API to load detailed information for a selected address.

Parameters

Endpoint

New Zealand

https://api.addressfinder.io/api/nz/address/reverse_geocode

Parameter	Description	Test Value
key	Your unique Addressfinder license key. Type: string required
format	Response format. Default value: json Type: string required	-- Select --jsonxml
x	Longitude in WGS84 format. Type: string required
y	Latitude in WGS84 format. Type: string required
domain	Used to identify your service in the Addressfinder Portal. Must be registered in the Portal. Type: string
max	Maximum number of results to return (1–100). Default value: 10 Type: integer

Responses

200 Closest addresses to the provided coordinates

Name	Description	Example
success	True if the query completed successfully. Type: boolean	true
completions	Type: array	-
a	Canonical address. Type: string	184 Willis Street, Te Aro, Wellington 6011
pxid	Unique address identifier. Type: string	2-.F.1W.p.0G1Jx

400 Invalid input or missing required parameters

Name	Description	Example
error	Type: string	Missing required parameter 'x'

See API Error Reference for details.

401 Unauthorized

Name	Description	Example
error_code	A unique numerical value identifying the error that occurred Type: string	1030
message	An informative message describing the error that occurred. For error code 1030 this includes the token expiry time in UTC, for example "Token expired at 2026-08-24T05:15:57Z". Type: string	Token expired at 2026-08-24T05:15:57Z
success	Indicates that the request was not successful Type: boolean	false

See API Error Reference for details.