api/swagger.yaml
swagger: '2.0'
info:
description: |
Free Australian Address Validation, Search and Autocomplete
version: '1.0.0'
title: 'Addressr by Mountain Pass'
basePath: '/'
tags:
- name: address
schemes:
- 'https'
produces:
- 'application/json'
paths:
/:
get:
summary: API Root
operationId: getApiRoot
x-swagger-router-controller: Default
x-root-rel: self
description: |
returns a list of available APIs within the `Link` headers
responses:
200:
description: successful operation
schema:
$ref: '#/definitions/Root'
headers:
link:
description: rfc5988 Links
type: array
collectionFormat: csv
items:
type: string
pattern: '<(.*)>;(.*)'
link-template:
description: rfc6570 Links Templates
type: array
collectionFormat: csv
items:
type: string
pattern: '<(.*)>;(.*)'
503:
description: service unavailable
schema:
$ref: "#/definitions/Error"
500:
description: unexpected error
schema:
$ref: "#/definitions/Error"
/addresses:
get:
summary: Get List of Addresses
operationId: getAddresses
x-swagger-router-controller: Addresses
x-root-rel: https://addressr.mountain-pass.com.au/rels/address-search
description: |
returns a list of addresses matching the search string
tags:
- address
parameters:
- name: q
in: query
description: search string
type: string
minLength: 3
required: true
- name: p
in: query
description: page number
type: integer
minimum: 2
required: false
responses:
200:
description: successful query
schema:
$ref: '#/definitions/SearchResponse'
headers:
link:
description: rfc5988 Links
type: array
collectionFormat: csv
items:
type: string
pattern: '<(.*)>;(.*)'
link-template:
description: rfc6570 Links Templates
type: array
collectionFormat: csv
items:
type: string
pattern: '<(.*)>;(.*)'
400:
description: invalid query
schema:
$ref: '#/definitions/ValidationError'
503:
description: service unavailable
schema:
$ref: "#/definitions/Error"
500:
description: unexpected error
schema:
$ref: "#/definitions/Error"
/addresses/{addressId}:
get:
summary: Get Address
operationId: getAddress
x-swagger-router-controller: Addresses
description: |
returns detailed information about a specific address
tags:
- address
parameters:
- name: addressId
in: path
description: ID of the address.
type: string
required: true
responses:
200:
description: successful query
schema:
$ref: '#/definitions/Address'
headers:
link:
description: rfc5988 Links
type: array
collectionFormat: csv
items:
type: string
pattern: '<(.*)>;(.*)'
link-template:
description: rfc6570 Links Templates
type: array
collectionFormat: csv
items:
type: string
pattern: '<(.*)>;(.*)'
503:
description: service unavailable
schema:
$ref: "#/definitions/Error"
500:
description: unexpected error
schema:
$ref: "#/definitions/Error"
definitions:
Root:
type: object
SearchResponse:
type: array
description: |
The list of addresses matching the search string. The list may be paginated.
A the `Link` header with a `rel` of `next` will be provided if there are additional results.
items:
type: object
title: Flattened Address
required:
- sla
- score
- links
properties:
sla:
$ref: '#/definitions/SingleLineAddress'
score:
type: number
description: strength of the match relative to the other matches
links:
type: object
required:
- self
properties:
self:
type: object
required:
- href
properties:
href:
type: string
title: Link
description: |
The URL for the address, where additional information can be retrieved
example:
- sla: LEVEL 25, TOWER 3, 300 BARANGAROO AV, BARANGAROO NSW 2000
score: 1
links:
self:
href: /addresses/GANT_718592778
- sla: 109 KIRRIBILLI AV, KIRRIBILLI NSW 2061
score: 0.985051936618461
links:
self:
href: /addresses/GANT_718592782
Address:
type: object
title: Physical Australian Address
description: |
A physical Australian address in structured and unstructured formats.
If an address has a "flat" component (e.g. UNIT 12, 32 SOME ST...), then it will also have a
the `ssla` and `smla` fields, which are shortended versions of `sla` and `mla`. e.g. (12/32 SOME ST...)
required:
- 'pid'
- 'structured'
- 'sla'
- 'mla'
properties:
pid:
type: string
description: The Persistent Identifier is unique to the real world feature this record represents.
example: GANT_718592778
structured:
$ref: '#/definitions/StructuredAddress'
sla:
$ref: '#/definitions/SingleLineAddress'
ssla:
$ref: '#/definitions/SingleLineAddress'
mla:
$ref: '#/definitions/MultiLineAddress'
smla:
$ref: '#/definitions/MultiLineAddress'
geo:
$ref: '#/definitions/AddressGeocoding'
AddressGeocoding:
type: object
description: Geocoding information about the address
properties:
level:
type: object
properties:
code:
type: integer
maxLength: 2
description: |
Binary indicator of the level of geocoding this address has. e.g. 0 = 000 = (No geocode), 1 = 001 = (No Locality geocode, No Street geocode, Address geocode), etc.
example: 7
name:
type: string
maxLength: 50
description: |
Name of the geocode level type code.
example: LOCALITY,STREET, ADDRESS
geocodes:
type: array
items:
type: object
properties:
default:
type: boolean
description: |
Indicates if the geocode is the default or a site geocode (i.e. from *_ADDRESS_DEFAULT_GEOCODE_psv or from *_ADDRESS_SITE_GEOCODE_psv)
latitude:
type: number
example: -33.85351875
longitude:
type: number
example: 150.8947369
reliability:
type: object
properties:
code:
type: integer
maxLength: 1
description: |
Spatial precision of the geocode expressed as number in the range, 1 (unique identification of feature) to 6 (feature associated to region i.e. postcode).
example: 2
name:
type: string
maxLength: 50
description: |
Name of the geocode reliability code.
example: WITHIN ADDRESS SITE BOUNDARY OR ACCESS POINT
type:
type: object
properties:
code:
type: integer
maxLength: 1
description: |
Unique abbreviation for geocode feature. (e.g. "PRCL") (SAWG 7.4.1).
example: 2
name:
type: string
maxLength: 50
description: |
Name of the geocode type code.
example: PROPERTY CENTROID
description:
type: string
maxLength: 50
description: |
Additional textual data
example: REAR
SingleLineAddress:
type: string
title: Single Line Address
description: |
The full address flattened to a single line. The primary use is for search results and for autocomplete.
example: LEVEL 25, TOWER 3, 300 BARANGAROO AV, BARANGAROO NSW 2000
MultiLineAddress:
type: array
items:
type: string
minItems: 2
maxItems: 4
title: Multi Line Address
description: |
The full address flattened to at most four lines. The primary use is for address labels
example:
- LEVEL 25
- TOWER 3
- 300 BARANGAROO AV
- BARANGAROO NSW 2000
StructuredAddress:
type: object
properties:
buildingName:
type: string
maxLength: 200
example: Vickery Lodge
description: |
Combines both building/property name fields. (AS4590:2006 5.7).
lotNumber:
type: object
properties:
prefix:
type: string
example: A
maxLength: 2
number:
type: string
example: CP
maxLength: 5
suffix:
type: string
example: B
maxLength: 2
flat:
type: object
properties:
type:
type: object
properties:
name:
type: string
example: Tower
maxLength: 50
code:
type: string
example: Twr
maxLength: 7
prefix:
type: string
example: CT
maxLength: 2
number:
type: integer
example: 20114
suffix:
type: string
example: AG
maxLength: 2
level:
type: object
properties:
type:
type: object
properties:
na,e:
type: string
example: Observation Deck
maxLength: 50
code:
type: string
example: OD
maxLength: 4
prefix:
type: string
example: A
maxLength: 2
number:
type: integer
example: '64'
maxLength: 5
suffix:
type: string
example: QG
maxLength: 2
number:
type: object
properties:
prefix:
type: string
example: RMB
maxLength: 3
number:
type: integer
example: '20114'
maxLength: 6
suffix:
type: string
example: 'AA'
maxLength: 2
last:
type: object
properties:
prefix:
type: string
example: RMB
maxLength: 3
number:
type: integer
example: '20114'
maxLength: 6
suffix:
type: string
example: 'C'
maxLength: 2
street:
type: object
properties:
name:
type: string
example: Barangaroo
maxLength: 100
type:
type: object
properties:
name:
type: string
example: Av
maxLength: 15
code:
type: string
example: Avenue
maxLength: 50
suffix:
type: object
properties:
name:
type: string
example: Deviation
maxLength: 50
code:
type: string
example: De
maxLength: 15
locality:
type: object
properties:
name:
type: string
example: Sydney
maxLength: 100
class:
type: object
properties:
code:
type: string
example: G
maxLength: 1
name:
type: string
example: GAZETTED LOCALITY
maxLength: 50
state:
type: object
properties:
name:
type: string
example: New South Wales
maxLength: 50
abbreviation:
type: string
example: NSW
maxLength: 3
postcode:
type: string
example: '2000'
maxLength: 4
confidence:
type: integer
description: |
Reflects how many contributor databases this address appears in (0 = 1 database, 1 = 2 database etc.).
ValidationError:
type: object
properties:
code:
type: string
failedValidation:
type: boolean
path:
type: array
items:
type: string
paramName:
type: string
message:
type: string
Error:
type: object
properties:
error:
type: string