--- title: "Retrieve one address by its id" method: GET path: "/v1/addresses/{id}" tags: ["G-NAF Addresses"] --- # Retrieve one address by its id `GET /v1/addresses/{id}` ## Request - Base URL: `https://api.locio.com.au` - URL: `https://api.locio.com.au/v1/addresses/{id}` - Auth: HTTP bearer The pid a search or a resolve returned. This is the endpoint that makes storing a pid worthwhile: the address can be read back a year later without knowing how it was originally typed. A 404 means G-NAF retired the id between releases, which does happen. Search for the address again to get its current one. ## Path parameters - `id` string, required ## Query parameters - `country` string ## Response `200` The address. - object - `data` Address: One G-NAF record, resolved. - `id` string: The id of this address in its country's register, and the one key every address carries. In Australia it is G-NAF's ADDRESS_DETAIL_PID, written under `address_detail_pid` as well. Another register numbers its addresses its own way, and those ids appear under `id` alone. Ids are unique within a country, so store the `country_code` beside it. - `address_detail_pid` string: G-NAF's ADDRESS_DETAIL_PID. 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. Not to be confused with gnaf.primary_pid, which identifies the parcel this address sits on rather than this address. - `gnaf_pid` string: Former name for address_detail_pid. Same value. Removed in the next release. - `formatted` string: The address on one line, as it would be written on an envelope. Composed from the components, so the two can never disagree. - `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". - `lat` number - `lng` number - `country` string: The country, as a name. Absent when this address sits outside the areas the directory has seeded. - `region` string: The state or territory, as a name. Absent when this address sits outside the areas the directory has seeded. - `locality` string: The suburb, as a name. - `mesh_block` string: The ABS mesh block: the smallest geographic unit the census publishes, and the join key to ABS statistics about the area. - `gnaf` GNAFRecord: The rest of the G-NAF row: the parcel it sits on, whether it is a unit under another address, and how the coordinate was derived. Absent on a record loaded before this was carried. - `date_created` string, date: When G-NAF first published this address. - `address_site_name` string: G-NAF's name for the site, where the address is part of a named one: a school, a hospital, a caravan park. - `legal_parcel_id` string: The title reference for the parcel, and the join to a state land registry. - `alias_principal` 'PRINCIPAL' | 'ALIAS': Whether G-NAF treats this as the principal record for the address or as an alias of one. Only principal records are served. - `primary_secondary` 'PRIMARY' | 'SECONDARY': SECONDARY means the address is a unit under another. 90 Bay Road, Sandringham is one PRIMARY parcel and five SECONDARY units. - `primary_pid` string: The gnaf_pid of the parcel this address sits under, on a SECONDARY record. The only thing in the data saying several addresses are one building. - `geocode_type` string: How the coordinate was derived. The difference between a pin on the door and a pin in the middle of the property. - `country_code` string: Which register this address came from, as a two letter ISO 3166-1 code. Absent on an Australian record, which is the default. The G-NAF specific fields -- `address_detail_pid`, `gnaf_pid`, `mesh_block` and `gnaf` -- appear only on Australian records. - `country_code` string: The country these results were searched in. `AU` today. Distinct from an address's own `country`, which is the country's name. - `note` string: Why the answer is empty when empty is correct: no address data is loaded for this country, or the country could not be determined. Absent on an ordinary answer. ## Other responses - `400`: That is not the shape of a G-NAF address id. - `401`: No key, or a key we do not recognise. Send it as `Authorization: Bearer pf_live_...`. - `402`: The quota for this billing period is spent. `X-Quota-Reset` says when it returns; the billing portal is how to raise it sooner. - `404`: No address with that id. Also when the address is outside the country this key may search: an id either resolves for you or it does not, and which ids exist elsewhere is not something a key can probe for. - `429`: Too many requests a second for this plan. `RateLimit-Limit` says the rate and `Retry-After` says how long to wait; this is a rate, not a quota, so it clears in a second. --- [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)