# Locio

> Australian address API. Resolve any address to a stable id, coordinates, ABS mesh block and structured components. Free for the first 10,000 lookups a month; a secret API key is sent as `Authorization: Bearer lc_live_...`.

## API

- [Base URL](https://api.locio.com.au): every response is JSON; errors are RFC 7807 problem documents.
- [GET https://api.locio.com.au/v1/addresses?q=](https://locio.com.au/docs/#searchAddresses): suggest resolved addresses as someone types. 1 unit.
- [GET https://api.locio.com.au/v1/addresses/resolve?q=](https://locio.com.au/docs/#resolveAddress): validate, geocode and parse one address in one call. 1 unit.
- [GET https://api.locio.com.au/v1/addresses/similar?q=](https://locio.com.au/docs/#similarAddresses): nearest real addresses for a misspelled one. 3 units.
- [GET https://api.locio.com.au/v1/addresses/{id}](https://locio.com.au/docs/#getAddress): read an address back by its id. 1 unit.
- [OpenAPI](https://api.locio.com.au/v1/openapi.json): the machine readable spec.

## The answer

- `id`: the address's id in its country's register, and the key to store against your own record. In Australia it is the G-NAF Address Detail PID, sent under `address_detail_pid` as well; `gnaf_pid` is the deprecated former name for the same value.
- `country_code`: on the envelope, which country was searched; on a record, which register it came from, absent meaning Australia. `mesh_block` and the `gnaf` object are Australian records only.
- `note`: a sentence saying why a list is empty when empty is the right answer, so an empty list is not mistaken for a bad address.

## Country

- Every lookup belongs to one country. A secret key names it with `country`, a two letter ISO 3166-1 code, and gets `AU` when it names none.
- A public key is scoped to the country the request came from, resolved from the visitor's own connection, and `country` is ignored on one: a key that sits in a page cannot widen what it may see.
- Australia and the United States are the countries with address data today: Australia from G-NAF, the United States from the National Address Database. A country with neither answers 200 with an empty list and a `note`, and is not charged.

## Agents

- [MCP server](https://api.locio.com.au/mcp): the same four calls as tools, Streamable HTTP, bearer key or OAuth 2.1. Details at https://locio.com.au/mcp/.
- [OAuth metadata](https://api.locio.com.au/.well-known/oauth-authorization-server): dynamic client registration and PKCE, for hosted agents.

## Docs

- [API reference](https://locio.com.au/docs/): every call with samples in curl, Node, Python, Ruby, Go and PHP.
- [Guides](https://locio.com.au/guides/): worked integrations.
- [Address autocomplete in plain JavaScript](https://locio.com.au/guides/address-autocomplete-javascript/): Add Australian address autocomplete to any HTML form with one script and no framework: a debounced call to the address API as someone types, a list to pick from, and the G-NAF id saved with the form.
- [Address autocomplete in React with the Locio package](https://locio.com.au/guides/address-autocomplete-react-package/): Install the published React client and have an accessible address autocomplete working in a few minutes, with the debouncing, request cancellation and keyboard handling already done and every class name still yours.
- [Address autocomplete in React](https://locio.com.au/guides/address-autocomplete-react/): A small hook and a component that give a React form Australian address autocomplete from the Locio API, with debouncing, request cancellation and the picked address handed to the parent as a typed object.
- [Address autocomplete in Vue with the Locio package](https://locio.com.au/guides/address-autocomplete-vue-package/): Install the published Vue client and get an accessible address autocomplete as a single component, with the debouncing and request cancellation already done, v-model support and every class name still yours.
- [Address autocomplete in Vue](https://locio.com.au/guides/address-autocomplete-vue/): A single file Vue 3 component that adds Australian address autocomplete to a form with the Locio API: script setup, a watched query with a debounce, request cancellation, and the picked address emitted to the parent.
- [Stand up a React site with Australian address search](https://locio.com.au/guides/react-address-search-site/): From an empty folder to a deployed page: create a Vite React project, add address search backed by the Locio API with a public key, run it locally, build it and put it on a static host.
- [Normalise shipping addresses at checkout](https://locio.com.au/guides/normalise-shipping-addresses/): Take the address a customer typed, resolve it against G-NAF on your server, store the id, and hand your carrier the canonical form. Node, with the fallback for an address that does not resolve, unit numbers handled, and the same answer every time an order is looked at again.
- [Put a searched address on a map with MapLibre](https://locio.com.au/guides/address-on-a-map-maplibre/): Address autocomplete that drops a pin on a MapLibre map as soon as an address is picked, with OpenFreeMap tiles so there is no second API key to manage, a pin that follows each pick, and a dark mode that does not leave a bright rectangle on the page.
- [Validate and geocode Australian addresses in PHP](https://locio.com.au/guides/address-validation-php/): A small PHP client for the Locio API that checks whether an address is real, returns its G-NAF id and coordinates, and falls back to fuzzy matching for typos. Plain curl, no framework required, with a Laravel variant.
- [Australian address autocomplete for WooCommerce](https://locio.com.au/guides/address-autocomplete-woocommerce/): Install the Locio plugin on a WooCommerce shop: suggestions as the customer types at checkout, a check against G-NAF when the order is placed, and the G-NAF id saved on the order. With a local test shop you can stand up in two commands.
- [Address validation and geocoding in Go](https://locio.com.au/guides/address-validation-go/): Install the Go client and resolve a typed address to a G-NAF id and a coordinate on the server, with near misses to offer back when nothing matches and typed errors for quota and rate limits.
- [Use Locio from Claude Code, Claude Desktop and Cursor](https://locio.com.au/guides/locio-in-claude-code-desktop-cursor/): Connect the address API to the agents you already use: one command for Claude Code, a connector for claude.ai and Claude Desktop, a JSON file for Cursor and VS Code. Then what to ask, and how to read the quota when an agent runs out.
- [Give an agent address tools with the Anthropic API](https://locio.com.au/guides/agent-address-tools-anthropic-api/): Two ways to let Claude validate and geocode Australian addresses from your own code: point the Messages API at the Locio MCP server and write no tool loop at all, or define the tools yourself over the REST API with the SDK's tool runner.
- [Clean a spreadsheet of addresses with an agent](https://locio.com.au/guides/clean-a-spreadsheet-with-an-agent/): A complete Python script: read a CSV of addresses as people typed them, let Claude resolve each one through the Locio API, fall back to fuzzy matching for typos, and write a CSV with the address id, coordinates and a note for every row it could not settle.
- [Pricing](https://locio.com.au/pricing/)
- [Licensing](https://locio.com.au/legal/): G-NAF under CC BY 4.0; attribution travels with the data.