{ "openapi": "3.0.3", "info": { "title": "getAddress()", "description": "Simple APIs for Australian addresses, backed by G-NAF. Autocomplete, Location, Typeahead and Distance are free and rate limited; resolving a suggestion with Get or Get Location, a Validate that finds its address, and asking for the Nearest Location, each count as one look-up. Supply your API key as the \u0060api-key\u0060 query parameter \u2014 it is the only place the key is read from. Browser code should use a domain token in place of the API key. Usage takes the subscription\u0027s admin key. Address data is G-NAF Core \u00C2\u00A9 Geoscape Australia, licensed by Geoscape Australia under the Open G-NAF Core End User Licence Agreement; it must not be used to generate or compile addresses for sending mail unless each is verified against another source. Attribution: https://getaddress.io/docs/attribution.", "version": "1.0.0", "contact": { "email": "support@getaddress.io" } }, "servers": [ { "url": "https://api.getaddress.io" } ], "security": [ { "ApiKeyQuery": [] } ], "paths": { "/autocomplete/{term}": { "get": { "operationId": "autocomplete", "summary": "Suggest partial address results for a term", "description": "Returns up to \u0060top\u0060 suggestions for the given term. Autocomplete queries are rate limited but do not increase your usage.", "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The partial address to search for, e.g. \u0060200 george st\u0060.", "schema": { "type": "string" } }, { "name": "top", "in": "query", "required": false, "description": "Number of suggestions to return (max 6).", "schema": { "type": "integer", "default": 6, "maximum": 6 } }, { "name": "template", "in": "query", "required": false, "description": "Suggestion text template, e.g. \u0060{formatted_address}\u0060. \u0060{name,prefix,suffix}\u0060 wraps a non-empty field with the given prefix/suffix. Available fields: formatted_address, locality_name, locality, suburb, state, postcode.", "schema": { "type": "string", "default": "{formatted_address}" } } ], "responses": { "200": { "description": "Suggestions for the term.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suggestions" }, "example": { "suggestions": [ { "address": "200 GEORGE ST, LAUNCESTON TAS 7250", "url": "/get/GATAS702238303", "id": "GATAS702238303" }, { "address": "UNIT 2 200 GEORGE ST, WINDSOR NSW 2756", "url": "/get/GANSW712891236", "id": "GANSW712891236" } ] } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded for your plan\u0027s 5-minute span.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The address data is briefly unavailable (never answered as an empty list). Retry shortly.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } }, "post": { "operationId": "autocompletePost", "summary": "Suggest partial address results for a term (options body)", "description": "Identical to the GET, with an optional JSON body carrying top, template, a filter (state, locality, postcode, radius) and a location to prefer nearby suggestions.", "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The partial address to search for, e.g. \u0060200 george st\u0060.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutocompleteOptions" }, "example": { "top": 6, "filter": { "state": "WA" }, "location": { "latitude": -31.9505, "longitude": 115.8605 } } } } }, "responses": { "200": { "description": "Suggestions for the term.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suggestions" } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded for your plan\u0027s 5-minute span.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The address data is briefly unavailable (never answered as an empty list). Retry shortly.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/get/{id}": { "get": { "operationId": "get", "summary": "Resolve a suggestion id to the full address", "description": "Returns the full address for a suggestion id. Each successful request counts as one look-up against your plan\u0027s daily allowance.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The address\u0027s G-NAF \u0060address_detail_pid\u0060, as returned in the \u0060id\u0060 of an \u0060/autocomplete/{term}\u0060 suggestion.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The full address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" }, "example": { "address_label": "SYDNEY OPERA HOUSE 2 CIRCULAR QUAY EAST, SYDNEY NSW 2000", "address_detail_pid": "GANSW718642855", "address_site_name": "SYDNEY OPERA HOUSE", "address_status": "current", "alias_principal": "PRINCIPAL", "building_name": "SYDNEY OPERA HOUSE", "cleaning_provenance": {}, "date_created": "2015-10-23", "flat_number": "", "flat_type": "", "geocode_type": "PROPERTY CENTROID", "legal_parcel_id": "4/787933", "level_number": "", "level_type": "", "locality_name": "SYDNEY", "lot_number": "", "mb_code": "10741860000", "number_first": "2", "number_last": "", "postcode": "2000", "primary_pid": "", "primary_secondary": "PRIMARY", "principal_pid": "", "state": "NSW", "street_name": "CIRCULAR QUAY EAST", "street_suffix": "", "street_type": "", "coordinates": { "latitude": -33.8587646484375, "longitude": 151.21322631835938 } } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "No address exists for the given id." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded, or the plan\u0027s daily look-up limit reached.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The address data is briefly unavailable. Retry shortly.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/validate/{address}": { "get": { "operationId": "validate", "summary": "Confirm a one-line address", "description": "Confirms a one-line address against G-NAF: 200 with the address when exactly one fits, 300 with candidate ids when the line is ambiguous, 404 when none fits. Only a 200 counts as a look-up.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The address on one line, e.g. \u006012 Acland St, St Kilda VIC 3182\u0060. URL-encode it, but leave a unit\u0027s slash as it is: \u00603/12 Chapel St ...\u0060 reads as unit 3, number 12.", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Exactly one address fits: it is returned exactly as /get/{id} returns it. Counts one look-up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } } }, "300": { "description": "Several addresses fit, the line names no suburb or postcode, or it names a building G-NAF holds only as its units. Their ids, up to 10. Costs nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateCandidates" }, "example": { "candidates": [ "GANSW705419145", "GAVIC421516744", "GANSW716822204" ] } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "No address fits every word of the line. Costs nothing." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded, or the plan\u0027s daily look-up limit reached.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The address data is briefly unavailable. Retry shortly." } } }, "post": { "operationId": "validatePost", "summary": "Confirm a one-line address (POST)", "description": "Confirms a one-line address against G-NAF: 200 with the address when exactly one fits, 300 with candidate ids when the line is ambiguous, 404 when none fits. Only a 200 counts as a look-up.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The address on one line, e.g. \u006012 Acland St, St Kilda VIC 3182\u0060. URL-encode it, but leave a unit\u0027s slash as it is: \u00603/12 Chapel St ...\u0060 reads as unit 3, number 12.", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Exactly one address fits: it is returned exactly as /get/{id} returns it. Counts one look-up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } } }, "300": { "description": "Several addresses fit, the line names no suburb or postcode, or it names a building G-NAF holds only as its units. Their ids, up to 10. Costs nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateCandidates" }, "example": { "candidates": [ "GANSW705419145", "GAVIC421516744", "GANSW716822204" ] } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "No address fits every word of the line. Costs nothing." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded, or the plan\u0027s daily look-up limit reached.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The address data is briefly unavailable. Retry shortly." } } } }, "/distance/{from}/{to}": { "get": { "operationId": "distance", "summary": "Distance between two addresses or locations", "description": "Returns the straight-line distance in metres between two G-NAF addresses (by address_detail_pid) or two places (by location id, measured from the centre), in any mix. Metres only, never coordinates. Rate limited but does not increase your usage.", "parameters": [ { "name": "from", "in": "path", "required": true, "description": "The first address\u0027s address_detail_pid, e.g. \u0060GANSW721316793\u0060, or a location id, e.g. \u0060sydney-nsw-2000\u0060.", "schema": { "type": "string" } }, { "name": "to", "in": "path", "required": true, "description": "The second address\u0027s address_detail_pid or location id, e.g. \u0060melbourne-vic-3000\u0060.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The straight-line distance in whole metres.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Distance" }, "example": { "metres": 716312 } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "An id is unknown, or its address has no geocode. The problem names which, from or to." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded for your plan\u0027s 5-minute span.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The address data is briefly unavailable. Retry shortly." } } } }, "/distance/{fromLatitude}/{fromLongitude}/to/{toLatitude}/{toLongitude}": { "get": { "operationId": "distanceBetweenPoints", "summary": "Distance between two points", "description": "Returns the straight-line distance in metres between two latitude/longitude points. Rate limited but does not increase your usage.", "parameters": [ { "name": "fromLatitude", "in": "path", "required": true, "description": "Latitude of the first point.", "schema": { "type": "number", "format": "double", "minimum": -90, "maximum": 90 } }, { "name": "fromLongitude", "in": "path", "required": true, "description": "Longitude of the first point.", "schema": { "type": "number", "format": "double", "minimum": -180, "maximum": 180 } }, { "name": "toLatitude", "in": "path", "required": true, "description": "Latitude of the second point.", "schema": { "type": "number", "format": "double", "minimum": -90, "maximum": 90 } }, { "name": "toLongitude", "in": "path", "required": true, "description": "Longitude of the second point.", "schema": { "type": "number", "format": "double", "minimum": -180, "maximum": 180 } } ], "responses": { "200": { "description": "The straight-line distance in whole metres.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Distance" }, "example": { "metres": 322 } } } }, "400": { "description": "A latitude or longitude is out of range." }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded for your plan\u0027s 5-minute span.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The address data is briefly unavailable. Retry shortly." } } } }, "/location/{term}": { "get": { "operationId": "location", "summary": "Suggest places for a partly typed suburb or postcode", "description": "Returns up to \u0060top\u0060 places \u2014 one per suburb, state and postcode \u2014 for the given term. Location queries are rate limited but do not increase your usage.", "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The partly typed suburb or postcode, e.g. \u0060northb\u0060.", "schema": { "type": "string" } }, { "name": "top", "in": "query", "required": false, "description": "Number of suggestions to return (max 20).", "schema": { "type": "integer", "default": 6, "maximum": 20 } } ], "responses": { "200": { "description": "Places matching the term.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationSuggestions" }, "example": { "suggestions": [ { "location": "NORTHBRIDGE NSW 2063", "url": "/get-location/northbridge-nsw-2063", "id": "northbridge-nsw-2063" }, { "location": "NORTHBRIDGE WA 6003", "url": "/get-location/northbridge-wa-6003", "id": "northbridge-wa-6003" } ] } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded for your plan\u0027s 5-minute span.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The data is briefly unavailable (never answered as an empty list). Retry shortly.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } }, "post": { "operationId": "locationPost", "summary": "Suggest places for a partly typed suburb or postcode (options body)", "description": "Identical to the GET, with an optional JSON body carrying top, a filter (state, postcode, radius), a location to prefer nearby places, and your end user\u0027s ip_address.", "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The partly typed suburb or postcode, e.g. \u0060northb\u0060.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationOptions" }, "example": { "top": 6, "filter": { "state": "WA" }, "location": { "latitude": -31.9505, "longitude": 115.8605 } } } } }, "responses": { "200": { "description": "Places matching the term.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationSuggestions" } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded for your plan\u0027s 5-minute span.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The data is briefly unavailable (never answered as an empty list). Retry shortly.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/get-location/{id}": { "get": { "operationId": "getLocation", "summary": "Resolve a location id to the place and its centre", "description": "Returns the suburb, state, postcode and centre for a location suggestion id. Each successful request counts as one look-up against your plan\u0027s daily allowance.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The place\u0027s location id, as returned in the \u0060id\u0060 of a \u0060/location/{term}\u0060 suggestion, e.g. \u0060northbridge-wa-6003\u0060.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The place and its centre.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Place" }, "example": { "id": "darwin-city-nt-0800", "location": "DARWIN CITY NT 0800", "locality_name": "DARWIN CITY", "state": "NT", "postcode": "0800", "coordinates": { "latitude": -12.460733, "longitude": 130.841415 } } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "No place exists for the given id." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded, or the plan\u0027s daily look-up limit reached.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The data is briefly unavailable (never answered as an empty list). Retry shortly.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/nearest-location/{latitude}/{longitude}": { "get": { "operationId": "nearestLocation", "summary": "The places nearest a point", "description": "Returns up to \u0060top\u0060 places whose centres are nearest the point, nearest first, each with its distance in metres. A request that finds a place counts as one look-up against your plan\u0027s daily allowance; a point with no Australian place within reach returns an empty list and costs nothing.", "parameters": [ { "name": "latitude", "in": "path", "required": true, "description": "Latitude in decimal degrees, e.g. \u0060-33.8612\u0060.", "schema": { "type": "number", "format": "double", "minimum": -90, "maximum": 90 } }, { "name": "longitude", "in": "path", "required": true, "description": "Longitude in decimal degrees, e.g. \u0060151.2107\u0060.", "schema": { "type": "number", "format": "double", "minimum": -180, "maximum": 180 } }, { "name": "top", "in": "query", "required": false, "description": "Number of places to return (max 20).", "schema": { "type": "integer", "default": 6, "maximum": 20 } } ], "responses": { "200": { "description": "The nearest places, nearest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NearestLocations" }, "example": { "suggestions": [ { "location": "THE ROCKS NSW 2000", "url": "/get-location/the-rocks-nsw-2000", "id": "the-rocks-nsw-2000", "distance": 322 }, { "location": "MILLERS POINT NSW 2000", "url": "/get-location/millers-point-nsw-2000", "id": "millers-point-nsw-2000", "distance": 654 } ] } } } }, "400": { "description": "The latitude or longitude is out of range." }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded, or the plan\u0027s daily look-up limit reached.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The data is briefly unavailable (never answered as an empty list). Retry shortly.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/typeahead/{term}": { "get": { "operationId": "typeahead", "summary": "Complete a partly typed suburb, postcode, street or state", "description": "Returns up to \u0060top\u0060 values as a JSON array of strings. Values are drawn from every field alike. Typeahead queries are rate limited but do not increase your usage.", "parameters": [ { "name": "term", "in": "path", "required": true, "description": "What has been typed so far, e.g. \u0060bon\u0060 or \u006020\u0060.", "schema": { "type": "string", "minLength": 1, "maxLength": 50 } }, { "name": "top", "in": "query", "required": false, "description": "Number of values to return (max 20).", "schema": { "type": "integer", "default": 6, "maximum": 20 } } ], "responses": { "200": { "description": "Completed values, best first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeaheadValues" }, "example": [ "BONDI JUNCTION", "BONDI BEACH", "BONDI", "BONGAREE", "BONBEACH", "BONNYRIGG" ] } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded for your plan\u0027s 5-minute span.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The data is briefly unavailable (never answered as an empty list). Retry shortly.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } }, "post": { "operationId": "typeaheadPost", "summary": "Complete a partly typed suburb, postcode, street or state (options body)", "description": "Identical to the GET, with an optional JSON body carrying top, search (the fields to complete), a filter (state, locality, postcode) and same.", "parameters": [ { "name": "term", "in": "path", "required": true, "description": "What has been typed so far, e.g. \u0060bon\u0060 or \u006020\u0060.", "schema": { "type": "string", "minLength": 1, "maxLength": 50 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeaheadOptions" }, "example": { "search": [ "street" ], "filter": { "locality": "SYDNEY" } } } } }, "responses": { "200": { "description": "Completed values, best first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeaheadValues" }, "example": [ "PIER STREET", "PITT STREET" ] } } }, "400": { "description": "An unknown search field, or a term over 50 characters." }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The key is valid but cannot make this request: the subscription has expired, or the key is the admin key (which reads usage only) or is tied to no subscription." }, "429": { "description": "Rate limit exceeded for your plan\u0027s 5-minute span.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } }, "503": { "description": "The data is briefly unavailable (never answered as an empty list). Retry shortly.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }, "/usage": { "get": { "operationId": "usage", "summary": "Today\u0027s look-up usage", "description": "Returns today\u0027s metered look-up count (UTC) with the plan\u0027s daily limit and monthly buffer. Only /get/{id} counts. Requires the subscription\u0027s admin key; the address API key and domain tokens are refused. Also served at /v4/usage.", "responses": { "200": { "description": "Today\u0027s usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" }, "example": { "date": "2026-09-14T00:00:00Z", "usage_today": 42, "daily_limit": 2000, "monthly_buffer": 1000, "monthly_buffer_used": 150 } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The key is valid but is not the subscription\u0027s admin key." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/usage/{day}/{month}/{year}": { "get": { "operationId": "usageForDay", "summary": "One day\u0027s look-up usage", "description": "Returns the metered look-up count for a single UTC day. Requires the subscription\u0027s admin key. Also served under /v4.", "parameters": [ { "name": "day", "in": "path", "required": true, "description": "Day of the month, 1-31.", "schema": { "type": "integer" } }, { "name": "month", "in": "path", "required": true, "description": "Month, 1-12.", "schema": { "type": "integer" } }, { "name": "year", "in": "path", "required": true, "description": "Four-digit year.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "That day\u0027s usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "400": { "description": "The day, month and year are not a real date." }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The key is valid but is not the subscription\u0027s admin key." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/usage/from/{fromDay}/{fromMonth}/{fromYear}/to/{toDay}/{toMonth}/{toYear}": { "get": { "operationId": "usageForRange", "summary": "A range of daily look-up usage", "description": "Returns one row per UTC day across an inclusive range, newest first. Days with no look-ups are returned as zero rather than omitted. A range may not exceed 366 days. Requires the subscription\u0027s admin key. Also served under /v4.", "parameters": [ { "name": "fromDay", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fromMonth", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fromYear", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "toDay", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "toMonth", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "toYear", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "One row per day, newest first.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Usage" } } } } }, "400": { "description": "Either end is not a real date, or the range is longer than 366 days." }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The key is valid but is not the subscription\u0027s admin key." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/subscription/label": { "put": { "operationId": "renameSubscription", "summary": "Rename the subscription", "description": "Sets what the subscription is called in the console and in emails. Its name, keys, domain tokens and usage do not change. A blank label puts back the subscription\u0027s own name. Labels must be unique on the account, ignoring case. Requires the subscription\u0027s admin key; the address API key and domain tokens are refused.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 50, "description": "What to call the subscription. Blank puts back its own name." } } }, "example": { "label": "Main site" } } } }, "responses": { "200": { "description": "The subscription as it is now called.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The subscription\u0027s identifier. Never changes." }, "label": { "type": "string", "description": "What the subscription is called." } } }, "example": { "name": "500-per-day", "label": "Main site" } } } }, "400": { "description": "The label is too long, or another subscription on the account is already called that." }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The key is valid but is not the subscription\u0027s admin key." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/info": { "get": { "operationId": "apiInfo", "summary": "Self-describing manifest for coding agents", "description": "Returns the API\u0027s name, description, OpenAPI and reference URLs, how to authenticate and the error code dictionary. No key needed.", "security": [], "responses": { "200": { "description": "The manifest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiInfo" } } } } } } }, "/api/examples": { "get": { "operationId": "apiExamples", "summary": "Worked request and response examples", "description": "Returns copy-pasteable examples of every endpoint and the common errors, written for coding agents. No key needed.", "security": [], "responses": { "200": { "description": "The examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiExamples" } } } } } } }, "/.well-known/api-catalog": { "get": { "operationId": "apiCatalog", "summary": "API discovery catalog", "description": "The entry point for automated tooling, following the IETF API Catalog draft: a linkset pointing at the OpenAPI description, the interactive reference, /api/info and /api/examples. No key needed.", "security": [], "responses": { "200": { "description": "The catalog.", "content": { "application/linkset\u002Bjson": { "schema": { "$ref": "#/components/schemas/ApiCatalog" } } } } } } } }, "components": { "responses": { "RateLimited": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until a successful retry can be made.", "schema": { "type": "integer" } } } } }, "securitySchemes": { "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "api-key", "description": "API key (or a domain token for browser use) as a query parameter. /usage takes the subscription\u0027s admin key here instead." } }, "schemas": { "Suggestions": { "type": "object", "required": [ "suggestions" ], "properties": { "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/Suggestion" } }, "fallback": { "$ref": "#/components/schemas/SuggestionsFallback" } } }, "SuggestionsFallback": { "type": "object", "description": "Only present when there are no suggestions, the request used a domain token, and the subscription has the Google Places fallback switched on. The JavaScript Autocomplete uses it to search Google for businesses and places from the browser.", "required": [ "provider", "key" ], "properties": { "provider": { "type": "string", "enum": [ "google_places" ] }, "key": { "type": "string", "description": "The customer\u0027s own Google API key, as saved in the console." } } }, "Suggestion": { "type": "object", "required": [ "address", "url", "id" ], "properties": { "address": { "type": "string", "description": "The suggestion display text, e.g. \u00223/12 Chapel Street, Melbourne VIC 3000\u0022." }, "url": { "type": "string", "description": "Relative URL that resolves this suggestion, e.g. \u0022/get/GAVIC421677561\u0022." }, "id": { "type": "string", "description": "The address\u0027s G-NAF address_detail_pid, e.g. \u0022GAVIC421677561\u0022. Passed to /get/{id}." } } }, "Address": { "type": "object", "description": "An Australian address, exactly as G-NAF holds it: the field names are the G-NAF ones and nothing is derived, aliased or composed. Every string field is present on every address, empty when that address has no value for it.", "properties": { "address_label": { "type": "string", "description": "The one-line display label, e.g. \u0022UNIT 4 269 STIRLING ST, PERTH WA 6000\u0022. The same text a suggestion shows." }, "address_detail_pid": { "type": "string", "description": "G-NAF\u0027s own identifier for this address detail record." }, "address_site_name": { "type": "string", "description": "The name of the site the address sits on, when it has one." }, "address_status": { "type": "string", "description": "\u0022current\u0022 when G-NAF still publishes this address, \u0022retired\u0022 when it has been withdrawn since. A retired address still resolves, so an id you stored months ago keeps working, but it will never be suggested again. The one field here that is not G-NAF\u0027s own.", "enum": [ "current", "retired" ] }, "alias_principal": { "type": "string", "description": "Whether the record is G-NAF\u0027s principal address (\u0022PRINCIPAL\u0022) or an alias of one (\u0022ALIAS\u0022)." }, "building_name": { "type": "string" }, "cleaning_provenance": { "type": "object", "additionalProperties": true, "description": "An object noting the values cleaned when G-NAF was loaded, keyed by field. {} when nothing was, which is almost every record. A record the widget builds from the Google Places fallback has {\u0022Source\u0022: \u0022GOOGLE\u0022} here instead.", "example": {} }, "date_created": { "type": "string", "description": "The date G-NAF created the address, as an ISO 8601 date with no time (yyyy-MM-dd). Empty when absent.", "example": "2015-10-23" }, "flat_number": { "type": "string" }, "flat_type": { "type": "string", "description": "The flat or unit type, e.g. \u0022UNIT\u0022. Empty when the address has none." }, "geocode_type": { "type": "string", "description": "What the geocode points at, e.g. \u0022PROPERTY CENTROID\u0022." }, "legal_parcel_id": { "type": "string", "description": "The land title / legal parcel identifier." }, "level_number": { "type": "string" }, "level_type": { "type": "string", "description": "The level type within the building, e.g. \u0022Level\u0022. Usually empty." }, "locality_name": { "type": "string", "description": "The G-NAF locality, e.g. \u0022PERTH\u0022." }, "lot_number": { "type": "string", "description": "The lot number, for addresses identified by lot rather than street number." }, "mb_code": { "type": "string", "description": "The ABS mesh block code the address falls in." }, "number_first": { "type": "string", "description": "The street number, or the first of a range." }, "number_last": { "type": "string", "description": "The last street number of a range. Empty for a single number." }, "postcode": { "type": "string", "description": "The 4-digit Australian postcode, e.g. \u00222000\u0022." }, "primary_pid": { "type": "string", "description": "The primary address this one is secondary to, when it is a secondary address." }, "primary_secondary": { "type": "string", "description": "Whether the address is a primary (\u0022PRIMARY\u0022) or a secondary (\u0022SECONDARY\u0022) one." }, "principal_pid": { "type": "string", "description": "The principal address this one aliases, when it is an alias." }, "state": { "type": "string", "description": "State or territory abbreviation: NSW, VIC, QLD, SA, WA, TAS, NT or ACT.", "enum": [ "NSW", "VIC", "QLD", "SA", "WA", "TAS", "NT", "ACT" ] }, "street_name": { "type": "string", "description": "The street name without its type, e.g. \u0022STIRLING\u0022." }, "street_suffix": { "type": "string", "description": "The street suffix, e.g. \u0022EAST\u0022." }, "street_type": { "type": "string", "description": "The street type, e.g. \u0022STREET\u0022." }, "coordinates": { "type": "object", "nullable": true, "description": "The address geocode (GDA2020). Null when the address carries no coordinates.", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } } } } }, "AutocompleteOptions": { "type": "object", "description": "Optional body for the POST autocomplete variant. All properties are optional.", "properties": { "top": { "type": "integer", "default": 6, "maximum": 6, "description": "Number of suggestions to return (max 6)." }, "template": { "type": "string", "default": "{formatted_address}", "description": "Suggestion text template. Available fields: formatted_address, locality_name, locality, suburb, state, postcode." }, "filter": { "type": "object", "description": "Limits suggestions to matching addresses.", "properties": { "state": { "type": "string", "description": "State or territory abbreviation, e.g. \u0022NSW\u0022." }, "locality": { "type": "string", "description": "Locality / suburb." }, "postcode": { "type": "string", "description": "4-digit postcode." }, "radius": { "type": "object", "description": "Only suggest addresses within km of the point.", "properties": { "km": { "type": "number" }, "latitude": { "type": "number" }, "longitude": { "type": "number" } } } } }, "location": { "type": "object", "description": "Prefer suggestions closer to this point.", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } } } } }, "LocationSuggestions": { "type": "object", "required": [ "suggestions" ], "properties": { "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/LocationSuggestion" } } } }, "LocationSuggestion": { "type": "object", "required": [ "location", "url", "id" ], "properties": { "location": { "type": "string", "description": "The place as it should be shown, e.g. \u0022NORTHBRIDGE WA 6003\u0022." }, "url": { "type": "string", "description": "Relative URL that resolves this place, e.g. \u0022/get-location/northbridge-wa-6003\u0022." }, "id": { "type": "string", "description": "The place\u0027s location id, e.g. \u0022northbridge-wa-6003\u0022. The same in every G-NAF release. Passed to /get-location/{id}." } } }, "NearestLocations": { "type": "object", "required": [ "suggestions" ], "properties": { "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/NearestLocation" } } } }, "NearestLocation": { "allOf": [ { "$ref": "#/components/schemas/LocationSuggestion" }, { "type": "object", "required": [ "distance" ], "properties": { "distance": { "type": "integer", "format": "int64", "description": "Straight-line distance from the point to the place\u0027s centre, in whole metres." } } } ] }, "Place": { "type": "object", "required": [ "id", "location", "locality_name", "state", "postcode", "coordinates" ], "properties": { "id": { "type": "string", "description": "The place\u0027s location id, e.g. \u0022darwin-city-nt-0800\u0022." }, "location": { "type": "string", "description": "The label, e.g. \u0022DARWIN CITY NT 0800\u0022." }, "locality_name": { "type": "string", "description": "The suburb, as G-NAF names it." }, "state": { "type": "string", "description": "NSW, VIC, QLD, SA, WA, TAS, NT, ACT, or OT for the other territories." }, "postcode": { "type": "string", "description": "The 4-digit postcode." }, "coordinates": { "type": "object", "nullable": true, "description": "The centre of the place (GDA2020): the mean position of its addresses.", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } } } } }, "LocationOptions": { "type": "object", "description": "Optional body for the POST location variant. All properties are optional.", "properties": { "top": { "type": "integer", "default": 6, "maximum": 20, "description": "Number of suggestions to return (max 20)." }, "filter": { "type": "object", "description": "Limits suggestions to matching places.", "properties": { "state": { "type": "string", "description": "State or territory abbreviation, e.g. \u0022NSW\u0022." }, "postcode": { "type": "string", "description": "4-digit postcode." }, "radius": { "type": "object", "description": "Only suggest places whose centre is within km of the point.", "properties": { "km": { "type": "number" }, "latitude": { "type": "number" }, "longitude": { "type": "number" } } } } }, "location": { "type": "object", "description": "Prefer places closer to this point.", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } } }, "ip_address": { "type": "string", "description": "Your end user\u0027s IP address, to prefer places near them. Read only on an API-key request." } } }, "TypeaheadValues": { "type": "array", "description": "Completed values: plain strings, in G-NAF upper case.", "items": { "type": "string" } }, "TypeaheadOptions": { "type": "object", "description": "Optional body for the POST typeahead variants. All properties are optional.", "properties": { "top": { "type": "integer", "default": 6, "maximum": 20, "description": "Number of values to return (max 20)." }, "search": { "type": "array", "description": "The fields to complete. Omitted, every field is completed alike. A street is its name and type, e.g. \u0022PITT STREET\u0022.", "items": { "type": "string", "enum": [ "locality", "postcode", "street", "state" ] } }, "filter": { "type": "object", "description": "Only values held by addresses matching every field set.", "properties": { "state": { "type": "string", "description": "State or territory abbreviation, e.g. \u0022NSW\u0022." }, "locality": { "type": "string", "description": "Suburb, e.g. \u0022SYDNEY\u0022." }, "postcode": { "type": "string", "description": "4-digit postcode." } } }, "same": { "type": "boolean", "default": true, "description": "False drops a lone value that only repeats the term." } } }, "ValidateCandidates": { "type": "object", "required": [ "candidates" ], "properties": { "candidates": { "type": "array", "description": "The candidates\u0027 G-NAF address_detail_pids, best first. Pass one to /get/{id}.", "items": { "type": "string" } } } }, "Distance": { "type": "object", "required": [ "metres" ], "properties": { "metres": { "type": "integer", "format": "int64", "description": "The straight-line (great-circle) distance in whole metres. Not a driving distance." } } }, "Usage": { "type": "object", "description": "One UTC day\u0027s metered look-ups for a subscription.", "required": [ "date", "usage_today", "daily_limit", "monthly_buffer", "monthly_buffer_used" ], "properties": { "date": { "type": "string", "format": "date-time", "description": "The UTC day this row covers." }, "usage_today": { "type": "integer", "format": "int64", "description": "Metered look-ups on that day." }, "daily_limit": { "type": "integer", "description": "The plan\u0027s daily allowance. 2147483647 when the plan has no daily limit." }, "monthly_buffer": { "type": "integer", "description": "The plan\u0027s monthly overflow allowance. 0 when the plan has none." }, "monthly_buffer_used": { "type": "integer", "format": "int64", "description": "How much of the buffer the day\u0027s whole calendar month has used, so it repeats on every row of a month." } } }, "ApiInfo": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "openapi_url": { "type": "string" }, "documentation_url": { "type": "string" }, "examples_url": { "type": "string" }, "authentication": { "type": "object", "properties": { "type": { "type": "string", "example": "api-key" }, "description": { "type": "string" } } }, "error_codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "unauthorized" }, "status": { "type": "integer", "example": 401 }, "description": { "type": "string" } } } } } }, "ApiExamples": { "type": "object", "properties": { "examples": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "autocomplete" }, "title": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "example": "GET" }, "path": { "type": "string", "example": "/autocomplete/12%20chapel%20st%20melb?api-key=YOUR-API-KEY\u0026top=6" }, "request_body": { "type": "object", "nullable": true }, "response_status": { "type": "integer", "example": 200 }, "response_example": { "type": "object" } } } } } }, "ApiCatalog": { "type": "object", "properties": { "linkset": { "type": "array", "items": { "type": "object", "properties": { "anchor": { "type": "string" }, "rel": { "type": "string", "example": "service-desc" }, "href": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" } } } } } } } } }