{"openapi":"3.1.0","info":{"title":"yepthere","version":"1.0.0","license":{"name":"MIT","identifier":"MIT"},"description":"Australian address lookup using G-NAF. Incorporates or developed using G-NAF © Geoscape Australia licensed by the Commonwealth of Australia under the Open Geo-coded National Address File (G-NAF) End User Licence Agreement. MIT covers the software; address data remains subject to the G-NAF licence."},"servers":[{"url":"https://yepthere.au"}],"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"paths":{"/v1/addresses":{"get":{"operationId":"searchAddresses","summary":"Search addresses","description":"Supply exactly one of q or postcode. They are mutually exclusive. Text search uses word-level AND matching with a default limit of 8 and a cap of 20. Postcode listing defaults to 100 and caps at 500. Offset pagination is not implemented in the current route. Requires the search action group.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":3,"maxLength":200},"description":"Address text. Required when postcode is absent.","example":"example street"},{"name":"postcode","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}$"},"description":"Four digits. Required when q is absent."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500},"description":"Text: default 8, cap 20. Postcode: default 100, cap 500. Larger values are capped.","example":8},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Reserved for postcode pagination. Currently ignored by the server.","x-status":"preview"}],"responses":{"200":{"description":"Successful response.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"description":"Private client caching with the configured freshness; shared caches must not store lookup responses. Responses vary on Authorization and X-API-Key, plus Origin and Referer for browser keys."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Address"}}},"required":["results"]}]},"example":{"ok":true,"release":"AUG 2026 - Geoscape G-NAF - GDA2020","boundaries":{"edition":"ASGS Edition 3 (2021)"},"results":[{"uprn":"GNAF_SAMPLE","line1":"10 Example Street","line2":null,"suburb":"Melbourne","state":"VIC","postcode":"3000","latitude":-37.81,"longitude":144.96}]}}}},"304":{"description":"The cached representation is unchanged. The validator is derived from the response body, so the lookup still runs, but a 304 response consumes no monthly allowance but does consume burst capacity."},"400":{"description":"Invalid query, path parameter or request body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key: invalid-api-key or key-revoked.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"plan-required: a capability requires an upgrade; see message and upgradeUrl.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account-suspended, insufficient-scope, ip-not-allowed, origin-not-allowed or scope-denied. An IP mismatch returns \"This key is not allowed from <address>.\" Browser keys require an allowed website and only permit their selected GET or HEAD action groups.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate-limited, quota-exceeded or mcp-free-limit. Free accounts share 500 MCP lookups per UTC month; paid plans use their full allowance.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Lookup or internal error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Address data is unavailable.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"search"}},"/v1/addresses/{id}":{"get":{"operationId":"getAddress","summary":"Resolve an address","description":"Resolve a G-NAF address ID. Returns zero or one address; an unknown ID returns an empty results array. Requires the resolve action group.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100},"example":"GNAF_SAMPLE"}],"responses":{"200":{"description":"Successful response.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"description":"Private client caching with the configured freshness; shared caches must not store lookup responses. Responses vary on Authorization and X-API-Key, plus Origin and Referer for browser keys."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Address"}}},"required":["results"]}]},"example":{"ok":true,"release":"AUG 2026 - Geoscape G-NAF - GDA2020","boundaries":{"edition":"ASGS Edition 3 (2021)"},"results":[{"uprn":"GNAF_SAMPLE","line1":"10 Example Street","line2":null,"suburb":"Melbourne","state":"VIC","postcode":"3000","latitude":-37.81,"longitude":144.96}]}}}},"304":{"description":"The cached representation is unchanged. The validator is derived from the response body, so the lookup still runs, but a 304 response consumes no monthly allowance but does consume burst capacity."},"400":{"description":"Invalid query, path parameter or request body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key: invalid-api-key or key-revoked.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"plan-required: a capability requires an upgrade; see message and upgradeUrl.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account-suspended, insufficient-scope, ip-not-allowed, origin-not-allowed or scope-denied. An IP mismatch returns \"This key is not allowed from <address>.\" Browser keys require an allowed website and only permit their selected GET or HEAD action groups.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate-limited, quota-exceeded or mcp-free-limit. Free accounts share 500 MCP lookups per UTC month; paid plans use their full allowance.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Lookup or internal error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Address data is unavailable.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"resolve"}},"/v1/nearest":{"get":{"operationId":"nearestAddresses","summary":"Find nearby addresses","description":"Find geocoded addresses near a point, including distance in metres. Requires the nearest action group.","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"Latitude.","example":-37.81},{"name":"lng","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180},"description":"Longitude.","example":144.96},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":5},"description":"Maximum 20; larger values are capped.","example":5}],"responses":{"200":{"description":"Successful response.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"description":"Private client caching with the configured freshness; shared caches must not store lookup responses. Responses vary on Authorization and X-API-Key, plus Origin and Referer for browser keys."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"results":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"distanceMetres":{"type":"number","minimum":0}},"required":["distanceMetres"]}]}}},"required":["results"]}]},"example":{"ok":true,"release":"AUG 2026 - Geoscape G-NAF - GDA2020","boundaries":{"edition":"ASGS Edition 3 (2021)"},"results":[{"uprn":"GNAF_SAMPLE","line1":"10 Example Street","line2":null,"suburb":"Melbourne","state":"VIC","postcode":"3000","latitude":-37.81,"longitude":144.96,"distanceMetres":12.4}]}}}},"304":{"description":"The cached representation is unchanged. The validator is derived from the response body, so the lookup still runs, but a 304 response consumes no monthly allowance but does consume burst capacity."},"400":{"description":"Invalid query, path parameter or request body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key: invalid-api-key or key-revoked.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"plan-required: a capability requires an upgrade; see message and upgradeUrl.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account-suspended, insufficient-scope, ip-not-allowed, origin-not-allowed or scope-denied. An IP mismatch returns \"This key is not allowed from <address>.\" Browser keys require an allowed website and only permit their selected GET or HEAD action groups.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate-limited, quota-exceeded or mcp-free-limit. Free accounts share 500 MCP lookups per UTC month; paid plans use their full allowance.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Lookup or internal error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Address data is unavailable.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"nearest"}},"/v1/postcodes/{postcode}":{"get":{"operationId":"getPostcode","summary":"Resolve a postcode","description":"One aggregate per state, with suburbs, address count and geocoded centroid. With include=suburbs, suburbRanking adds name, state and addressCount per suburb, ordered by count descending. Requires the postcodes action group.","parameters":[{"name":"postcode","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{4}$"},"example":"3000"},{"name":"include","in":"query","required":false,"description":"Set to suburbs to add suburbRanking.","schema":{"type":"string","enum":["suburbs"]}}],"responses":{"200":{"description":"Successful response.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"description":"Private client caching with the configured freshness; shared caches must not store lookup responses. Responses vary on Authorization and X-API-Key, plus Origin and Referer for browser keys."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Postcode"}}},"required":["results"]}]},"example":{"ok":true,"release":"AUG 2026 - Geoscape G-NAF - GDA2020","boundaries":{"edition":"ASGS Edition 3 (2021)"},"results":[{"postcode":"3000","state":"VIC","suburbs":["Melbourne"],"addressCount":100,"latitude":-37.81,"longitude":144.96,"suburbRanking":[{"name":"Melbourne","state":"VIC","addressCount":100}]}]}}}},"304":{"description":"The cached representation is unchanged. The validator is derived from the response body, so the lookup still runs, but a 304 response consumes no monthly allowance but does consume burst capacity."},"400":{"description":"Invalid query, path parameter or request body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key: invalid-api-key or key-revoked.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"plan-required: a capability requires an upgrade; see message and upgradeUrl.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account-suspended, insufficient-scope, ip-not-allowed, origin-not-allowed or scope-denied. An IP mismatch returns \"This key is not allowed from <address>.\" Browser keys require an allowed website and only permit their selected GET or HEAD action groups.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"postcode-not-found.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate-limited, quota-exceeded or mcp-free-limit. Free accounts share 500 MCP lookups per UTC month; paid plans use their full allowance.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Lookup or internal error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Address data is unavailable.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"postcodes"}},"/v1/postcodes":{"get":{"operationId":"searchPostcodes","summary":"Search postcodes","description":"Search a postcode prefix of one to four digits or a suburb name. Requires the postcodes action group.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100},"description":"Postcode prefix or suburb name.","example":"melbourne"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":8},"description":"Maximum 20; larger values are capped.","example":8}],"responses":{"200":{"description":"Successful response.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"description":"Private client caching with the configured freshness; shared caches must not store lookup responses. Responses vary on Authorization and X-API-Key, plus Origin and Referer for browser keys."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Postcode"}}},"required":["results"]}]},"example":{"ok":true,"release":"AUG 2026 - Geoscape G-NAF - GDA2020","boundaries":{"edition":"ASGS Edition 3 (2021)"},"results":[{"postcode":"3000","state":"VIC","suburbs":["Melbourne"],"addressCount":100,"latitude":-37.81,"longitude":144.96}]}}}},"304":{"description":"The cached representation is unchanged. The validator is derived from the response body, so the lookup still runs, but a 304 response consumes no monthly allowance but does consume burst capacity."},"400":{"description":"Invalid query, path parameter or request body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key: invalid-api-key or key-revoked.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"plan-required: a capability requires an upgrade; see message and upgradeUrl.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account-suspended, insufficient-scope, ip-not-allowed, origin-not-allowed or scope-denied. An IP mismatch returns \"This key is not allowed from <address>.\" Browser keys require an allowed website and only permit their selected GET or HEAD action groups.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate-limited, quota-exceeded or mcp-free-limit. Free accounts share 500 MCP lookups per UTC month; paid plans use their full allowance.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Lookup or internal error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Address data is unavailable.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"postcodes"}},"/v1/addresses/bulk":{"post":{"operationId":"bulkAddresses","summary":"Look up several addresses","description":"Run 1 to 100 queries in input order. Each query counts as one lookup. Each limit defaults to 1 and caps at 5. Request body limit: 64 KiB. Requires the bulk action group.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queries":{"type":"array","items":{"type":"object","properties":{"q":{"type":"string","minLength":3,"maxLength":200},"limit":{"type":"integer","minimum":1,"default":1,"maximum":5,"description":"Capped at 5."}},"required":["q"]},"minItems":1,"maxItems":100}},"required":["queries"]},"example":{"queries":[{"q":"example street"}]}}}},"responses":{"200":{"description":"Successful response.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/BulkResult"}}},"required":["results"]}]},"example":{"ok":true,"release":"AUG 2026 - Geoscape G-NAF - GDA2020","boundaries":{"edition":"ASGS Edition 3 (2021)"},"results":[{"q":"example street","results":[{"uprn":"GNAF_SAMPLE","line1":"10 Example Street","line2":null,"suburb":"Melbourne","state":"VIC","postcode":"3000","latitude":-37.81,"longitude":144.96}]}]}}}},"400":{"description":"Invalid query, path parameter or request body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key: invalid-api-key or key-revoked.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"plan-required: a capability requires an upgrade; see message and upgradeUrl.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account-suspended, insufficient-scope, ip-not-allowed, origin-not-allowed or scope-denied. An IP mismatch returns \"This key is not allowed from <address>.\" Browser keys require an allowed website and only permit their selected GET or HEAD action groups.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate-limited, quota-exceeded or mcp-free-limit. Free accounts share 500 MCP lookups per UTC month; paid plans use their full allowance.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Lookup or internal error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Address data is unavailable.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"bulk"}},"/v1/parse":{"post":{"operationId":"parseAddress","summary":"Parse a messy address","description":"Split free-text address input into components with a deterministic Australian parser, optionally libpostal and an OVH model when the rules are unsure, then rank G-NAF candidates with a confidence and the components that matched. PO boxes are recognised and never matched. Requires the parse scope. Body limit 4 KiB. Requires the parse action group.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","minLength":3,"maxLength":300},"limit":{"type":"integer","minimum":1,"maximum":20}},"required":["q"]},"example":{"q":"unit 3/42 wallaby way syd 2000","limit":3}}}},"responses":{"200":{"description":"Successful response.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ParseCandidate"}}},"required":["results"]},{"type":"object","properties":{"parsed":{"type":"object","additionalProperties":true}},"required":["parsed"]}]},"example":{"ok":true,"release":"AUG 2026 - Geoscape G-NAF - GDA2020","boundaries":{"edition":"ASGS Edition 3 (2021)"},"results":[{"uprn":"GNAF_SAMPLE","line1":"10 Example Street","line2":null,"suburb":"Melbourne","state":"VIC","postcode":"3000","latitude":-37.81,"longitude":144.96,"confidence":0.94,"matchedOn":["number","street","suburb"]}],"parsed":{"unit":"3","number":"42","numberTo":null,"street":"WALLABY","streetType":"WAY","suburb":"SYDNEY","state":"NSW","postcode":"2000","kind":"street","method":"rules","confidence":0.94}}}}},"400":{"description":"Invalid query, path parameter or request body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key: invalid-api-key or key-revoked.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"plan-required: a capability requires an upgrade; see message and upgradeUrl.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account-suspended, insufficient-scope, ip-not-allowed, origin-not-allowed or scope-denied. An IP mismatch returns \"This key is not allowed from <address>.\" Browser keys require an allowed website and only permit their selected GET or HEAD action groups.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate-limited, quota-exceeded or mcp-free-limit. Free accounts share 500 MCP lookups per UTC month; paid plans use their full allowance.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Lookup or internal error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Address data is unavailable.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"parse"}},"/v1/boundaries/{layer}/{code}":{"get":{"operationId":"getBoundary","summary":"Resolve a boundary","description":"A boundary by layer (mmm, remoteness, lga, sa2, sa3, sa4, federal, state, poa, sal) and code: its name and the postcodes it touches with address counts. Returns 404 boundary-not-found for an unknown code or until a boundary set is loaded. Requires the postcodes action group.","parameters":[{"name":"layer","in":"path","required":true,"schema":{"type":"string"},"example":"federal"},{"name":"code","in":"path","required":true,"schema":{"type":"string"},"example":"107"}],"responses":{"200":{"description":"Successful response.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"description":"Private client caching with the configured freshness; shared caches must not store lookup responses. Responses vary on Authorization and X-API-Key, plus Origin and Referer for browser keys."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Boundary"}}},"required":["results"]}]},"example":{"ok":true,"release":"AUG 2026 - Geoscape G-NAF - GDA2020","boundaries":{"edition":"ASGS Edition 3 (2021)"},"results":[{"layer":"federal","code":"107","name":"Calare","postcodes":[{"postcode":"2795","addresses":17787}]}]}}}},"304":{"description":"The cached representation is unchanged. The validator is derived from the response body, so the lookup still runs, but a 304 response consumes no monthly allowance but does consume burst capacity."},"400":{"description":"Invalid query, path parameter or request body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key: invalid-api-key or key-revoked.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"plan-required: a capability requires an upgrade; see message and upgradeUrl.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account-suspended, insufficient-scope, ip-not-allowed, origin-not-allowed or scope-denied. An IP mismatch returns \"This key is not allowed from <address>.\" Browser keys require an allowed website and only permit their selected GET or HEAD action groups.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"boundary-not-found.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate-limited, quota-exceeded or mcp-free-limit. Free accounts share 500 MCP lookups per UTC month; paid plans use their full allowance.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Lookup or internal error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Address data is unavailable.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"postcodes"}},"/v1/jobs":{"post":{"operationId":"submitJob","summary":"Submit a CSV job","description":"Send the CSV itself with Content-Type text/csv (10,485,760 bytes, up to 50,000 rows). Header x-job-column names the address column (default address; a 1-based index for headerless files) and x-job-filename names the file, percent-encoded as UTF-8. Every successfully processed row counts one job row; error rows cost nothing. Failed row lookups are retried twice, then written with a match_error marker and counted in errorRows. Only database connection errors or a failed readiness probe stop the job. Requires the jobs scope. 503 jobs-unavailable when storage is not configured. estimatedSecondsRemaining includes work scheduled ahead; estimatedReadyAt is its ISO 8601 UTC ready time. Estimates change with measured throughput. Requires the jobs action group.","parameters":[],"requestBody":{"required":true,"content":{"text/csv":{"schema":{"type":"string"},"example":"address\n10 Example Street Melbourne VIC 3000\n"}}},"responses":{"202":{"description":"Job accepted.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}},"required":["results"]}]},"example":{"ok":true,"release":"AUG 2026 - Geoscape G-NAF - GDA2020","boundaries":{"edition":"ASGS Edition 3 (2021)"},"results":[{"id":"job_sample","estimatedSecondsRemaining":0,"estimatedReadyAt":"2026-10-24T00:00:00.000Z","status":"queued","rowCount":120,"matchedHigh":0,"matchedLow":0,"unmatched":0,"errorRows":0,"downloadUrl":null,"expiresAt":null}]}}}},"400":{"description":"Invalid query, path parameter or request body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key: invalid-api-key or key-revoked.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"plan-required: a capability requires an upgrade; see message and upgradeUrl.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account-suspended, insufficient-scope, ip-not-allowed, origin-not-allowed or scope-denied. An IP mismatch returns \"This key is not allowed from <address>.\" Browser keys require an allowed website and only permit their selected GET or HEAD action groups.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate-limited, quota-exceeded or mcp-free-limit. Free accounts share 500 MCP lookups per UTC month; paid plans use their full allowance.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Lookup or internal error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Address data is unavailable.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"jobs"},"get":{"operationId":"listJobs","summary":"List recent jobs","description":"The last 50 jobs for the account. Requires the jobs action group.","parameters":[],"responses":{"200":{"description":"Successful response.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}},"required":["results"]}]},"example":{"ok":true,"release":"AUG 2026 - Geoscape G-NAF - GDA2020","boundaries":{"edition":"ASGS Edition 3 (2021)"},"results":[{"id":"job_sample","estimatedSecondsRemaining":0,"estimatedReadyAt":"2026-10-24T00:00:00.000Z","status":"done","rowCount":120,"matchedHigh":100,"matchedLow":15,"unmatched":5,"errorRows":0,"downloadUrl":null,"expiresAt":null}]}}}},"400":{"description":"Invalid query, path parameter or request body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key: invalid-api-key or key-revoked.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"plan-required: a capability requires an upgrade; see message and upgradeUrl.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account-suspended, insufficient-scope, ip-not-allowed, origin-not-allowed or scope-denied. An IP mismatch returns \"This key is not allowed from <address>.\" Browser keys require an allowed website and only permit their selected GET or HEAD action groups.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate-limited, quota-exceeded or mcp-free-limit. Free accounts share 500 MCP lookups per UTC month; paid plans use their full allowance.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Lookup or internal error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Address data is unavailable.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"jobs"}},"/v1/jobs/{id}":{"get":{"operationId":"getJob","summary":"Check a CSV job","description":"Job state, counts by confidence band, and an authenticated download route once done. Send the jobs-scoped account key; downloads redirect to a five-minute storage URL. Requires the jobs action group.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"job_sample"}],"responses":{"200":{"description":"Successful response.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}},"required":["results"]}]},"example":{"ok":true,"release":"AUG 2026 - Geoscape G-NAF - GDA2020","boundaries":{"edition":"ASGS Edition 3 (2021)"},"results":[{"id":"job_sample","estimatedSecondsRemaining":0,"estimatedReadyAt":"2026-10-24T00:00:00.000Z","status":"done","rowCount":120,"matchedHigh":100,"matchedLow":15,"unmatched":5,"errorRows":0,"downloadUrl":"https://yepthere.au/v1/jobs/job_sample/download","expiresAt":"2026-09-18T00:00:00.000Z"}]}}}},"400":{"description":"Invalid query, path parameter or request body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key: invalid-api-key or key-revoked.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"plan-required: a capability requires an upgrade; see message and upgradeUrl.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account-suspended, insufficient-scope, ip-not-allowed, origin-not-allowed or scope-denied. An IP mismatch returns \"This key is not allowed from <address>.\" Browser keys require an allowed website and only permit their selected GET or HEAD action groups.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Job not found.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate-limited, quota-exceeded or mcp-free-limit. Free accounts share 500 MCP lookups per UTC month; paid plans use their full allowance.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Lookup or internal error.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Address data is unavailable.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"jobs"}},"/health":{"get":{"operationId":"health","summary":"Check process health","description":"Process liveness. Does not query PostgreSQL. No key required.","security":[],"responses":{"200":{"description":"Process is running.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]},"example":{"ok":true}}}}}}},"/ready":{"get":{"operationId":"ready","summary":"Check data readiness","description":"Reports data readiness and release metadata. No key required.","security":[],"responses":{"200":{"description":"Address data is ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"},"example":{"ok":true,"ready":true,"rowCount":100,"releaseId":"sample","releaseName":"AUG 2026 - Geoscape G-NAF - GDA2020","loadedAt":"2026-09-01T00:00:00.000Z"}}}},"503":{"description":"Data is not loaded or the database is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"},"example":{"ok":false,"ready":false,"rowCount":0,"releaseId":null,"releaseName":null,"loadedAt":null,"error":"database-unavailable"}}}}}}},"/v1/jobs/{id}/download":{"get":{"operationId":"downloadJob","summary":"Download CSV results","description":"Requires an owning account key with jobs scope and any configured IP allowlist. Redirects to storage for five minutes. Do not forward credentials to storage. Requires the jobs action group.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"job_sample"}],"responses":{"302":{"description":"Download ready.","headers":{"Location":{"schema":{"type":"string","format":"uri"}}}},"401":{"description":"Missing, unknown or revoked API key (invalid-api-key or key-revoked).","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"plan-required: a capability requires an upgrade; see message and upgradeUrl.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient-scope, account-suspended, ip-not-allowed, origin-not-allowed or scope-denied.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown or expired job.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Job is not done.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage unavailable.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"jobs"}}},"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Per-key action groups: search (addresses by q or postcode), resolve (address ID), nearest, postcodes (both postcode routes and boundaries), bulk, parse and jobs. Search is always included. Parse requires a positive parse allowance and jobs a positive job row allowance. Browser keys may hold only search, resolve, nearest and postcodes. Server keys may restrict callers to up to 20 IP addresses or CIDR ranges."},"BearerAuth":{"type":"http","scheme":"bearer","description":"Per-key action groups: search (addresses by q or postcode), resolve (address ID), nearest, postcodes (both postcode routes and boundaries), bulk, parse and jobs. Search is always included. Parse requires a positive parse allowance and jobs a positive job row allowance. Browser keys may hold only search, resolve, nearest and postcodes. Server keys may restrict callers to up to 20 IP addresses or CIDR ranges."}},"headers":{"X-RateLimit-Limit":{"description":"Monthly lookup allowance for a registered key. Absent for the system key.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Lookups remaining after a successful response. Not guaranteed on authentication or throttle failures.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Start of the next UTC calendar month.","schema":{"type":"string","format":"date-time"}},"Retry-After":{"description":"Seconds until another request can be attempted.","schema":{"type":"integer","minimum":0}}},"schemas":{"Address":{"type":"object","properties":{"uprn":{"type":"string"},"line1":{"type":"string"},"line2":{"type":["string","null"]},"suburb":{"type":"string"},"state":{"type":"string","enum":["ACT","NSW","NT","OT","QLD","SA","TAS","VIC","WA"]},"postcode":{"type":"string","pattern":"^\\d{4}$"},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"boundaries":{"$ref":"#/components/schemas/Boundaries"}},"required":["uprn","line1","line2","suburb","state","postcode","latitude","longitude"]},"Boundaries":{"type":["object","null"],"description":"Null until a boundary set is loaded. The edition field identifies the loaded ABS ASGS allocation files (Edition 3 or 4), the Modified Monash Model 2023 by Mesh Block.","properties":{"edition":{"type":["string","null"]},"sa1":{"type":["string","null"]},"sa2":{"$ref":"#/components/schemas/CodeName"},"sa3":{"$ref":"#/components/schemas/CodeName"},"sa4":{"$ref":"#/components/schemas/CodeName"},"gccsa":{"$ref":"#/components/schemas/CodeName"},"remoteness":{"$ref":"#/components/schemas/CodeName"},"lga":{"$ref":"#/components/schemas/CodeName"},"electorate":{"type":"object","properties":{"federal":{"$ref":"#/components/schemas/CodeName"},"state":{"$ref":"#/components/schemas/CodeName"}},"required":["federal","state"]},"postalArea":{"type":["string","null"]},"suburb":{"$ref":"#/components/schemas/CodeName"},"mmm":{"type":"object","properties":{"category":{"type":["integer","null"],"minimum":1,"maximum":7},"name":{"type":["string","null"]}},"required":["category","name"]}}},"CodeName":{"type":"object","properties":{"code":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["code","name"]},"Boundary":{"type":"object","properties":{"boundaries":{"type":"object","properties":{"edition":{"type":["string","null"]}},"required":["edition"]},"layer":{"type":"string"},"code":{"type":"string"},"name":{"type":["string","null"]},"postcodes":{"type":"array","items":{"type":"object","properties":{"postcode":{"type":"string","pattern":"^\\d{4}$"},"addresses":{"type":"integer"}},"required":["postcode","addresses"]}}},"required":["layer","code","postcodes"]},"Envelope":{"type":"object","properties":{"ok":{"const":true},"release":{"type":["string","null"]},"boundaries":{"type":"object","properties":{"edition":{"type":["string","null"]}},"required":["edition"],"description":"Loaded ASGS edition metadata on successful address, boundary and postcode lookups. Null edition until recognised ASGS provenance is loaded."},"results":{"type":"array","items":{}}},"required":["ok","release","results"]},"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"string"},"message":{"type":"string"},"results":{"type":"array","maxItems":0},"upgradeUrl":{"type":"string","format":"uri"},"minimumPlan":{"type":["string","null"]}},"required":["ok","error","message","results"]},"Postcode":{"type":"object","properties":{"postcode":{"type":"string","pattern":"^\\d{4}$"},"state":{"type":"string","enum":["ACT","NSW","NT","OT","QLD","SA","TAS","VIC","WA"]},"suburbs":{"type":"array","items":{"type":"string"}},"suburbRanking":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"state":{"type":"string"},"addressCount":{"type":"integer","minimum":0}},"required":["name","state","addressCount"]},"description":"Postcode detail only. Suburbs ordered by addressCount descending, then name."},"addressCount":{"type":"integer","minimum":0},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]}},"required":["postcode","state","suburbs","addressCount","latitude","longitude"]},"BulkResult":{"type":"object","properties":{"q":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Address"}}},"required":["q","results"]},"ParseCandidate":{"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"confidence":{"type":"number","minimum":0,"maximum":1},"matchedOn":{"type":"array","items":{"type":"string"}}},"required":["confidence","matchedOn"]}],"description":"The parse envelope also carries a top-level parsed object: unit, number, numberTo, street, streetType, suburb, state, postcode, kind (po_box when detected), method (rules, libpostal or model) and confidence."},"Job":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","failed"]},"rowCount":{"type":["integer","null"]},"matchedHigh":{"type":"integer"},"matchedLow":{"type":"integer"},"unmatched":{"type":"integer"},"errorRows":{"type":"integer","minimum":0},"estimatedSecondsRemaining":{"type":"integer","minimum":0,"description":"Estimated seconds until ready, including scheduled work ahead. Zero for terminal jobs."},"estimatedReadyAt":{"type":"string","format":"date-time","description":"Estimated ready time in ISO 8601 UTC, or finish time for terminal jobs."},"error":{"type":["string","null"]},"downloadUrl":{"type":["string","null"]},"expiresAt":{"type":["string","null"]}},"required":["id","status","estimatedSecondsRemaining","estimatedReadyAt"]},"Readiness":{"type":"object","properties":{"ok":{"type":"boolean"},"ready":{"type":"boolean"},"rowCount":{"type":"integer","minimum":0},"releaseId":{"type":["string","null"]},"releaseName":{"type":["string","null"]},"loadedAt":{"type":["string","null"],"format":"date-time"},"error":{"type":"string"}},"required":["ok","ready","rowCount","releaseId","releaseName","loadedAt"]}}}}