Location Metadata API

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

The Location Metadata API is used to collect metadata associated with a location selected from the New Zealand Location Autocomplete API. The response includes geographic coordinates, canonical address formatting, and location metadata from LINZ.

Parameters

Endpoint

New Zealand

https://api.addressfinder.io/api/nz/location/metadata

Parameter	Description	Test Value
`key`	Your unique Addressfinder license key. Type: `string` `required`
`format`	The format of the response. Default value: `json` Type: `string` `required`
`pxid`	Unique address identifier from the Location Autocomplete API. Type: `string` `required`
`domain`	Used to identify your calling service for usage tracking in the Addressfinder Portal. Must be registered in the Portal. Type: `string`

Responses

200 Location metadata for the selected pxid

Name	Description	Example
`pxid`	The unique location identifier. Type: `string`	1-.B.11.4.2H
`a`	Canonical location string. Type: `string`	Seaview Road, Glenfield, Auckland
`x`	Longitude in WGS84. Type: `number`	174.643199
`y`	Latitude in WGS84. Type: `number`	-36.426956
`success`	Whether the request completed successfully. Type: `boolean`	true
`street`	Street name and type (from LINZ). Type: `string`	Martin Street
`suburb`	Suburb or locality name (from LINZ). Type: `string`	Gore
`city`	City, town, or locality (from LINZ). Type: `string`	Gore
`region`	Regional Authority (from LINZ). Type: `string`	Southland Region

400 Invalid input or missing parameters.

Name	Description	Example
`error`	Type: `string`	Missing required parameter 'pxid'

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.