swagger: '2.0'
info:
  description: |
    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: Index
      description: |
        returns a list of available APIs within the `Link` headers
      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/Index'
          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
        500:
          description: unexpected error
  /addresses:
    get:
      summary: Search for a list of addresses
      description: |
        returns a list of addresses matching the search string
      tags:
        - address
      parameters:
        - name: q
          in: query
          description: search string
          type: string
          required: true
      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
        503:
          description: service unavailable
        500:
          description: unexpected error
  /addresses/{addressId}:
    get:
      summary: Get Address
      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: '<(.*)>;(.*)'
        404:
          description: not found
        503:
          description: service unavailable
        500:
          description: unexpected error
definitions:
  Index:
    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
        - pid
      properties:
        sla:
          $ref: '#/definitions/SingleLineAddress'
        ssla:
          $ref: '#/definitions/SingleLineAddress'
        highlight:
          type: object
          required:
            - sla
          properties:
            sla:
              type: string
              description: The full address flattened to a single line with matching search tokens highlighted
              example: |
                <em>LEVEL</em> <em>25</em>, <em>TOWER</em> <em>3</em>, <em>300</em> BARANGAROO AV, BARANGAROO NSW 2000
            ssla:
              description: The full address flattened to a single line with matching search tokens highlighted
              example: |
                L25, 2512/9 <em>POWER</em> ST, SOUTHBANK VIC <em>3006</em>
        score:
          type: number
          description: strength of the match relative to the other matches
          example: 0.985051936618461
        pid:
          type: string
          description: The Persistent Identifier is unique to the real world feature this record represents.
          example: GANSW719386656
    example:
      - sla: LEVEL 25, TOWER 3, 300 BARANGAROO AV, BARANGAROO NSW 2000
        highlight:
          sla: |
            <em>LEVEL</em> <em>25</em>, <em>TOWER</em> <em>3</em>, <em>300</em> BARANGAROO AV, BARANGAROO NSW 2000
        score: 1
        pid: GANSW719386656
      - sla: |
          UNIT 1, 109 KIRRIBILLI AV, KIRRIBILLI NSW 2061
        ssla: |
          1/109 KIRRIBILLI AV, KIRRIBILLI NSW 2061
        highlight:
          sla: |
            UNIT 1, <em>109</em> <em>KIRRIBILLI</em> <em>AV</em>, <em>KIRRIBILLI</em> NSW 2061
          ssla: |
            1/<em>109</em> <em>KIRRIBILLI</em> <em>AV</em>, <em>KIRRIBILLI</em> NSW 2061
        score: 0.985051936618461
        pid: GANSW717102496
  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 an
      `smla` field, a shortened version of `mla`. e.g. (12/32 SOME ST...)

      Corrected 2026-08-09: this description previously also promised `ssla` on this
      representation. It is not served here. `ssla` is real, but it belongs to the search
      result, not the address detail: the loader lifts `sla` and `ssla` out before building
      the stored object this endpoint spreads, so `ssla` never reaches it. Same class as the
      `geo` name corrected below - a shipped spec naming something the endpoint does not
      return.
    required:
      - 'pid'
      - 'structured'
      - 'sla'
      - 'mla'
    properties:
      pid:
        type: string
        description: The Persistent Identifier is unique to the real world feature this record represents.
        example: GANSW719386656
      structured:
        $ref: '#/definitions/StructuredAddress'
      sla:
        $ref: '#/definitions/SingleLineAddress'
      mla:
        $ref: '#/definitions/MultiLineAddress'
      smla:
        $ref: '#/definitions/MultiLineAddress'
      geocoding:
        # Renamed from `geo` on 2026-08-09. The API has never served a `geo` key —
        # `mapAddressDetails` emits `geocoding`. This file named a property that does
        # not exist, which is worse than omitting one, and it ships in the tarball.
        $ref: '#/definitions/AddressGeocoding'
      precedence:
        type: string
        description: >-
          DEPRECATED - do not depend on this field. It carries the source dataset's
          primary/secondary flag and has never been part of any published spec. It is
          documented here only so its removal is announced rather than silent.
          (Swagger 2.0 has no `deprecated` keyword for schema properties, so the
          signal is carried in this description; the OpenAPI 3 spec served at
          /api-docs sets `deprecated: true`.)
      sla_range_expanded:
        type: array
        items:
          type: string
        description: >-
          DEPRECATED - do not depend on this field, and do not use it for search.
          It holds the two endpoint forms of a range address, but it has NEVER been
          searchable: it was written to a path the index mapping does not cover, so no
          query has ever matched it. Range addresses are already reachable by either
          endpoint without it. Scheduled for removal; retained for now only so the
          response body and ETag of existing range addresses do not change.
          (Swagger 2.0 has no `deprecated` keyword for schema properties, so the
          signal is carried in this description; the OpenAPI 3 spec served at
          /api-docs sets `deprecated: true`.)
  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.).