---
title: "Suggest addresses, suburbs and places as someone types"
method: GET
path: "/v1/typeahead"
tags: ["Search"]
---

# Suggest addresses, suburbs and places as someone types

`GET /v1/typeahead`

## Request

- Base URL: `https://api.locio.com.au`
- URL: `https://api.locio.com.au/v1/typeahead`
- Auth: HTTP bearer

Two characters minimum: below that the endpoint returns an empty list rather than matching most of the table.

Debounce by at least 150ms in the client. Each request is a unit, and firing on every keystroke spends them for no better answer.

A result whose `kind` is `address` is a resolved G-NAF record, not a string: it carries `gnaf_pid`, coordinates, and `components` holding the address split into G-NAF's own fields. Store the pid against your own record and the two systems agree they mean the same door, whatever either of you does to the formatting afterwards.

Address matching is a prefix of the street line, so type it the way it is written: the number first, then the street. A unit in front is understood and resolves to the unit's own record, not the building's: `3/90 Bay Road` returns the pid of unit 3, and `90 Bay Road` returns the pid of the parcel. `unit 3`, `u3`, `apt 3` and `3 90` are read the same way. A suburb name or a postcode alone matches suburbs, not addresses.

## Query parameters

- `q` string, required
- `limit` integer

## Response `200`

Matches, best first.

- SearchEnvelope
  - `data` SearchHit[]
    - `kind` 'locality' | 'place' | 'address': What was matched. An address may sit in a suburb with no page of its own, which is why locality_name and state are text beside a possibly empty slug.
    - `slug` string
    - `name` string
    - `country` string
    - `region` string
    - `locality` string
    - `locality_name` string
    - `state` string
    - `postcode` string
    - `place_count` integer
    - `lat` number
    - `lng` number
    - `score` number
    - `gnaf_pid` string: The G-NAF Address Detail PID, on address results only. This is the id to store against your own record: it is stable across G-NAF releases for an address that has not changed, so two systems holding it agree they mean the same door.
    - `components` AddressComponents: One address in G-NAF's field names, so it can be checked against the published schema rather than guessed at. Every field is optional: most Australian addresses have no flat and no level, and G-NAF holds properties with no street number. Values are cased for printing, not in G-NAF's upper case.
      - `building_name` string: G-NAF's own name for the building, where it has one. It leads the address: "Piermont Resort, Unit 9, 12990 Tasman Highway".
      - `flat_type` string
      - `flat_number` string
      - `level_type` string
      - `level_number` string
      - `number_first` string
      - `number_first_suffix` string
      - `number_last` string: The far end of a range; 435-437 is number_first 435 and number_last 437.
      - `number_last_suffix` string
      - `street_name` string: The name alone, without the type: Sydney, not Sydney Road.
      - `street_type` string
      - `street_suffix` string: A direction, where the street carries one.
      - `locality_name` string: The suburb. Repeated here so an address maps into your own type from one object.
      - `state` string
      - `postcode` string
      - `lot_number` string: The lot, for an address identified by one rather than by a street number. On a new subdivision it is the only number the address has, and `formatted` writes it as "Lot 3".
  - `generated_at` string, date-time

## Other responses

- `401`: No key, or not a valid one. Revoked and unknown keys answer the same way.
- `402`: The period's units are spent. X-Quota-Reset says when they return. Distinct from 429 so a client can tell "buy more" from "slow down".
- `429`: Too many requests a second. Back off for Retry-After seconds; refused requests are not charged.

---

[API](https://skmtc.dev/locio/apis/locio-api.md) · [All operations](https://skmtc.dev/locio/apis/locio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/locio/apis/locio-api/revisions/c259c9f9b329?raw)