@bradleyhodges/addresskit 2.2.3

package/dist/api/swagger.yaml

@@ -0,0 +1,826 @@
+swagger: '2.0'
+info:
+  description: |
+    Scalable address ingestion, validation, search, and autocomplete engine for Australian addresses.
+    
+    This API conforms to the [JSON:API v1.1 specification](https://jsonapi.org/format/).
+    All responses use the `application/vnd.api+json` media type.
+  version: '2.0.0'
+  title: 'AddressKit'
+  contact:
+    name: 'AddressKit Support'
+  license:
+    name: 'MIT'
+basePath: '/'
+tags:
+  - name: address
+    description: Australian address lookup and autocomplete operations
+schemes:
+  - 'https'
+  - 'http'
+consumes:
+  - 'application/vnd.api+json'
+produces:
+  - 'application/vnd.api+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.
+        This endpoint serves as the HATEOAS entry point for API discoverability.
+      responses:
+        200:
+          description: successful operation
+          schema:
+            $ref: '#/definitions/Root'
+          headers:
+            link:
+              description: RFC 5988 Links for resource discovery
+              type: array
+              collectionFormat: csv
+              items:
+                type: string
+                pattern: '<(.*)>;(.*)'
+            link-template:
+              description: RFC 6570 Link Templates for parameterized endpoints
+              type: array
+              collectionFormat: csv
+              items:
+                type: string
+                pattern: '<(.*)>;(.*)'
+        503:
+          description: service unavailable
+          schema:
+            $ref: "#/definitions/JsonApiErrorDocument"
+        500:
+          description: unexpected error 
+          schema:
+            $ref: "#/definitions/JsonApiErrorDocument"
+  /addresses:
+    get:
+      summary: Search Addresses (Autocomplete)
+      operationId: getAddresses
+      x-swagger-router-controller: Addresses
+      description: |
+        Searches for addresses matching the query string and returns lightweight
+        autocomplete suggestions optimized for typeahead UX.
+        
+        Each result contains only the display text (SLA) and address ID. Use the
+        `/addresses/{addressId}` endpoint to retrieve full address details.
+        
+        Results are paginated using JSON:API pagination parameters.
+      tags:
+        - address
+      parameters:
+        - name: q
+          in: query
+          description: |
+            Search query string. Supports fuzzy matching against single-line
+            addresses (SLA). Minimum 3 characters required.
+          type: string
+          minLength: 3
+          required: true
+        - name: page[number]
+          in: query
+          description: |
+            Page number for pagination (1-indexed). Defaults to 1.
+          type: integer
+          minimum: 1
+          required: false
+        - name: page[size]
+          in: query
+          description: |
+            Number of results per page. Defaults to 10, maximum 100.
+          type: integer
+          minimum: 1
+          maximum: 100
+          required: false
+      responses:
+        200:
+          description: successful query
+          schema:
+            $ref: '#/definitions/AddressAutocompleteDocument'
+          headers:
+            link:
+              description: RFC 5988 Links for pagination
+              type: array
+              collectionFormat: csv
+              items:
+                type: string
+                pattern: '<(.*)>;(.*)'
+            link-template:
+              description: RFC 6570 Link Templates
+              type: array
+              collectionFormat: csv
+              items:
+                type: string
+                pattern: '<(.*)>;(.*)'
+        400:
+          description: invalid query parameters
+          schema:
+            $ref: '#/definitions/JsonApiErrorDocument'
+        503:
+          description: service unavailable
+          schema:
+            $ref: "#/definitions/JsonApiErrorDocument"
+        504:
+          description: gateway timeout
+          schema:
+            $ref: "#/definitions/JsonApiErrorDocument"
+        500:
+          description: unexpected error 
+          schema:
+            $ref: "#/definitions/JsonApiErrorDocument"
+  /addresses/{addressId}:
+    get:
+      summary: Get Address Details
+      operationId: getAddress
+      x-swagger-router-controller: Addresses
+      description: |
+        Returns comprehensive details about a specific address by its unique
+        G-NAF Persistent Identifier (PID).
+        
+        The response includes:
+        - Single-line and multi-line address formats
+        - Fully structured address components (flat, level, street, locality, etc.)
+        - Geocoding information when available
+      tags:
+        - address
+      parameters:
+        - name: addressId
+          in: path
+          description: |
+            The unique G-NAF Persistent Identifier (PID) for the address.
+            Example: `GANT_718592778`
+          type: string
+          required: true
+      responses:
+        200:
+          description: successful query
+          schema:
+            $ref: '#/definitions/AddressDetailDocument'
+          headers:
+            link:
+              description: RFC 5988 Links
+              type: array
+              collectionFormat: csv
+              items:
+                type: string
+                pattern: '<(.*)>;(.*)'
+            ETag:
+              description: Entity tag for cache validation
+              type: string
+        404:
+          description: address not found
+          schema:
+            $ref: "#/definitions/JsonApiErrorDocument"
+        503:
+          description: service unavailable
+          schema:
+            $ref: "#/definitions/JsonApiErrorDocument"
+        500:
+          description: unexpected error 
+          schema:
+            $ref: "#/definitions/JsonApiErrorDocument"
+definitions:
+  # ============================================================================
+  # JSON:API Core Types
+  # ============================================================================
+  JsonApiVersion:
+    type: object
+    description: JSON:API implementation information
+    properties:
+      version:
+        type: string
+        example: "1.1"
+        description: JSON:API specification version
+  
+  JsonApiLinks:
+    type: object
+    description: JSON:API links object for HATEOAS navigation
+    properties:
+      self:
+        type: string
+        description: Link to the current resource or page
+        example: /addresses?q=sydney
+      first:
+        type: string
+        description: Link to the first page of results
+        example: /addresses?q=sydney
+      prev:
+        type: string
+        description: Link to the previous page of results (null if on first page)
+        x-nullable: true
+      next:
+        type: string
+        description: Link to the next page of results (null if on last page)
+        x-nullable: true
+      last:
+        type: string
+        description: Link to the last page of results
+        example: /addresses?q=sydney&page[number]=5
+      describedby:
+        type: object
+        description: Link to API documentation
+        properties:
+          href:
+            type: string
+            example: /docs/#operations-addresses-getAddresses
+          title:
+            type: string
+            example: getAddresses API Docs
+          type:
+            type: string
+            example: text/html
+  
+  JsonApiMeta:
+    type: object
+    description: Pagination and response metadata
+    properties:
+      total:
+        type: integer
+        description: Total number of resources matching the query
+        example: 42
+      page:
+        type: integer
+        description: Current page number (1-indexed)
+        example: 1
+      pageSize:
+        type: integer
+        description: Number of items per page
+        example: 10
+      totalPages:
+        type: integer
+        description: Total number of pages available
+        example: 5
+      responseTime:
+        type: integer
+        description: Query processing time in milliseconds
+        example: 45
+  
+  JsonApiError:
+    type: object
+    description: JSON:API error object
+    properties:
+      status:
+        type: string
+        description: HTTP status code as a string
+        example: "404"
+      code:
+        type: string
+        description: Application-specific error code
+        example: RESOURCE_NOT_FOUND
+      title:
+        type: string
+        description: Short human-readable summary
+        example: Not Found
+      detail:
+        type: string
+        description: Detailed explanation of the error
+        example: The address with ID 'INVALID_123' does not exist.
+      source:
+        type: object
+        description: Error source information
+        properties:
+          pointer:
+            type: string
+            description: JSON Pointer to the request value that caused the error
+          parameter:
+            type: string
+            description: Query parameter that caused the error
+  
+  JsonApiErrorDocument:
+    type: object
+    description: JSON:API error response document
+    required:
+      - errors
+    properties:
+      jsonapi:
+        $ref: '#/definitions/JsonApiVersion'
+      errors:
+        type: array
+        items:
+          $ref: '#/definitions/JsonApiError'
+        minItems: 1
+      meta:
+        type: object
+        description: Document-level metadata
+        properties:
+          retryAfter:
+            type: integer
+            description: Seconds to wait before retrying (for 503 responses)
+            example: 30
+  
+  # ============================================================================
+  # Address Autocomplete Types
+  # ============================================================================
+  AddressAutocompleteAttributes:
+    type: object
+    description: Minimal address data for autocomplete suggestions
+    required:
+      - sla
+      - rank
+    properties:
+      sla:
+        type: string
+        description: Single-line address for display in autocomplete dropdown
+        example: LEVEL 25, TOWER 3, 300 BARANGAROO AV, BARANGAROO NSW 2000
+      ssla:
+        type: string
+        description: Short single-line address (for unit addresses)
+        example: 25/300 BARANGAROO AV, BARANGAROO NSW 2000
+      rank:
+        type: number
+        format: float
+        description: Relevance score normalized to 0-1 range (1 = best match)
+        minimum: 0
+        maximum: 1
+        example: 0.95
+  
+  AddressAutocompleteResource:
+    type: object
+    description: JSON:API resource for an autocomplete suggestion
+    required:
+      - type
+      - id
+      - attributes
+    properties:
+      type:
+        type: string
+        enum: [address-suggestion]
+        description: Resource type identifier
+        example: address-suggestion
+      id:
+        type: string
+        description: Unique address identifier (G-NAF PID)
+        example: GANT_718592778
+      attributes:
+        $ref: '#/definitions/AddressAutocompleteAttributes'
+      links:
+        type: object
+        properties:
+          self:
+            type: string
+            description: Link to full address details
+            example: /addresses/GANT_718592778
+  
+  AddressAutocompleteDocument:
+    type: object
+    description: JSON:API document containing autocomplete results
+    required:
+      - data
+    properties:
+      jsonapi:
+        $ref: '#/definitions/JsonApiVersion'
+      data:
+        type: array
+        items:
+          $ref: '#/definitions/AddressAutocompleteResource'
+        description: Array of autocomplete suggestion resources
+      links:
+        $ref: '#/definitions/JsonApiLinks'
+      meta:
+        $ref: '#/definitions/JsonApiMeta'
+    example:
+      jsonapi:
+        version: "1.1"
+      data:
+        - type: address-suggestion
+          id: GANT_718592778
+          attributes:
+            sla: LEVEL 25, TOWER 3, 300 BARANGAROO AV, BARANGAROO NSW 2000
+            rank: 1
+          links:
+            self: /addresses/GANT_718592778
+        - type: address-suggestion
+          id: GANT_718592782
+          attributes:
+            sla: 109 KIRRIBILLI AV, KIRRIBILLI NSW 2061
+            rank: 0.85
+          links:
+            self: /addresses/GANT_718592782
+      links:
+        self: /addresses?q=barangaroo
+        first: /addresses?q=barangaroo
+        prev: null
+        next: /addresses?q=barangaroo&page[number]=2
+        last: /addresses?q=barangaroo&page[number]=5
+      meta:
+        total: 42
+        page: 1
+        pageSize: 10
+        totalPages: 5
+  
+  # ============================================================================
+  # Address Detail Types
+  # ============================================================================
+  AddressNumberRange:
+    type: object
+    description: Number component with optional prefix and suffix
+    properties:
+      prefix:
+        type: string
+        maxLength: 3
+        example: RMB
+      number:
+        type: integer
+        example: 42
+      suffix:
+        type: string
+        maxLength: 2
+        example: A
+  
+  AddressNumber:
+    type: object
+    description: Street number with optional range
+    allOf:
+      - $ref: '#/definitions/AddressNumberRange'
+      - type: object
+        properties:
+          last:
+            $ref: '#/definitions/AddressNumberRange'
+            description: End of number range (for "10-12 Smith St" style)
+  
+  AddressFlat:
+    type: object
+    description: Flat/unit details
+    properties:
+      type:
+        type: object
+        properties:
+          name:
+            type: string
+            example: Unit
+            maxLength: 50
+          code:
+            type: string
+            example: U
+            maxLength: 7
+      prefix:
+        type: string
+        maxLength: 2
+      number:
+        type: integer
+        example: 12
+      suffix:
+        type: string
+        maxLength: 2
+  
+  AddressLevel:
+    type: object
+    description: Building level/floor details
+    properties:
+      type:
+        type: object
+        properties:
+          name:
+            type: string
+            example: Level
+            maxLength: 50
+          code:
+            type: string
+            example: L
+            maxLength: 4
+      prefix:
+        type: string
+        maxLength: 2
+      number:
+        type: integer
+        example: 25
+      suffix:
+        type: string
+        maxLength: 2
+  
+  AddressStreet:
+    type: object
+    description: Street details
+    properties:
+      name:
+        type: string
+        example: Barangaroo
+        maxLength: 100
+      type:
+        type: object
+        properties:
+          name:
+            type: string
+            example: Avenue
+            maxLength: 50
+          code:
+            type: string
+            example: AV
+            maxLength: 15
+      suffix:
+        type: object
+        properties:
+          name:
+            type: string
+            example: North
+            maxLength: 50
+          code:
+            type: string
+            example: N
+            maxLength: 15
+  
+  AddressLocality:
+    type: object
+    description: Locality (suburb/town) details
+    properties:
+      name:
+        type: string
+        example: Barangaroo
+        maxLength: 100
+      class:
+        type: object
+        properties:
+          code:
+            type: string
+            example: G
+            maxLength: 1
+          name:
+            type: string
+            example: GAZETTED LOCALITY
+            maxLength: 50
+  
+  AddressState:
+    type: object
+    description: Australian state/territory
+    properties:
+      name:
+        type: string
+        example: New South Wales
+        maxLength: 50
+      abbreviation:
+        type: string
+        example: NSW
+        maxLength: 3
+  
+  AddressLotNumber:
+    type: object
+    description: Lot number for rural/unaddressed properties
+    properties:
+      prefix:
+        type: string
+        maxLength: 2
+      number:
+        type: string
+        maxLength: 5
+      suffix:
+        type: string
+        maxLength: 2
+  
+  AddressGeocode:
+    type: object
+    description: Geographic coordinate for the address
+    properties:
+      latitude:
+        type: number
+        format: double
+        example: -33.85351875
+      longitude:
+        type: number
+        format: double
+        example: 150.8947369
+      isDefault:
+        type: boolean
+        description: Whether this is the default geocode for the address
+        example: true
+      reliability:
+        type: object
+        properties:
+          code:
+            type: integer
+            description: Reliability code (1=best, 6=worst)
+            example: 2
+          name:
+            type: string
+            example: WITHIN ADDRESS SITE BOUNDARY OR ACCESS POINT
+      type:
+        type: object
+        properties:
+          code:
+            type: integer
+            example: 2
+          name:
+            type: string
+            example: PROPERTY CENTROID
+      description:
+        type: string
+        description: Additional textual description
+        example: REAR
+  
+  AddressGeoLevel:
+    type: object
+    description: Geocoding level achieved for this address
+    properties:
+      code:
+        type: integer
+        description: Binary indicator of geocoding level (0-7)
+        example: 7
+      name:
+        type: string
+        description: Human-readable geocoding level description
+        example: LOCALITY, STREET, ADDRESS
+  
+  StructuredAddress:
+    type: object
+    description: Fully parsed address components
+    properties:
+      buildingName:
+        type: string
+        description: Building or property name
+        maxLength: 200
+        example: Tower 3
+      lotNumber:
+        $ref: '#/definitions/AddressLotNumber'
+      flat:
+        $ref: '#/definitions/AddressFlat'
+      level:
+        $ref: '#/definitions/AddressLevel'
+      number:
+        $ref: '#/definitions/AddressNumber'
+      street:
+        $ref: '#/definitions/AddressStreet'
+      locality:
+        $ref: '#/definitions/AddressLocality'
+      state:
+        $ref: '#/definitions/AddressState'
+      postcode:
+        type: string
+        pattern: '^\d{4}$'
+        example: '2000'
+        description: Australian 4-digit postcode
+      confidence:
+        type: integer
+        description: Address confidence score (0-2, higher = more confidence)
+        minimum: 0
+        maximum: 2
+        example: 2
+  
+  AddressGeo:
+    type: object
+    description: Geocoding information for the address
+    properties:
+      level:
+        $ref: '#/definitions/AddressGeoLevel'
+      geocodes:
+        type: array
+        items:
+          $ref: '#/definitions/AddressGeocode'
+        description: Array of geocode points for this address
+  
+  AddressDetailAttributes:
+    type: object
+    description: Complete address details including structured components
+    required:
+      - pid
+      - sla
+      - structured
+    properties:
+      pid:
+        type: string
+        description: G-NAF Persistent Identifier (unique address ID)
+        example: GANT_718592778
+      sla:
+        type: string
+        description: Single-line address for display
+        example: LEVEL 25, TOWER 3, 300 BARANGAROO AV, BARANGAROO NSW 2000
+      ssla:
+        type: string
+        description: Short single-line address (for unit addresses)
+        example: 25/300 BARANGAROO AV, BARANGAROO NSW 2000
+      mla:
+        type: array
+        items:
+          type: string
+        minItems: 2
+        maxItems: 4
+        description: Multi-line address for mailing labels
+        example:
+          - LEVEL 25
+          - TOWER 3
+          - 300 BARANGAROO AV
+          - BARANGAROO NSW 2000
+      smla:
+        type: array
+        items:
+          type: string
+        minItems: 2
+        maxItems: 4
+        description: Short multi-line address
+      structured:
+        $ref: '#/definitions/StructuredAddress'
+      geo:
+        $ref: '#/definitions/AddressGeo'
+  
+  AddressDetailResource:
+    type: object
+    description: JSON:API resource for a detailed address
+    required:
+      - type
+      - id
+      - attributes
+    properties:
+      type:
+        type: string
+        enum: [address]
+        description: Resource type identifier
+        example: address
+      id:
+        type: string
+        description: Unique address identifier (G-NAF PID)
+        example: GANT_718592778
+      attributes:
+        $ref: '#/definitions/AddressDetailAttributes'
+      links:
+        type: object
+        properties:
+          self:
+            type: string
+            description: Self-referential link
+            example: /addresses/GANT_718592778
+  
+  AddressDetailDocument:
+    type: object
+    description: JSON:API document containing detailed address information
+    required:
+      - data
+    properties:
+      jsonapi:
+        $ref: '#/definitions/JsonApiVersion'
+      data:
+        $ref: '#/definitions/AddressDetailResource'
+      links:
+        type: object
+        properties:
+          self:
+            type: string
+            example: /addresses/GANT_718592778
+    example:
+      jsonapi:
+        version: "1.1"
+      data:
+        type: address
+        id: GANT_718592778
+        attributes:
+          pid: GANT_718592778
+          sla: LEVEL 25, TOWER 3, 300 BARANGAROO AV, BARANGAROO NSW 2000
+          ssla: 25/300 BARANGAROO AV, BARANGAROO NSW 2000
+          mla:
+            - LEVEL 25
+            - TOWER 3
+            - 300 BARANGAROO AV
+            - BARANGAROO NSW 2000
+          structured:
+            buildingName: Tower 3
+            level:
+              type:
+                name: Level
+                code: L
+              number: 25
+            number:
+              number: 300
+            street:
+              name: Barangaroo
+              type:
+                name: Avenue
+                code: AV
+            locality:
+              name: Barangaroo
+              class:
+                code: G
+                name: GAZETTED LOCALITY
+            state:
+              name: New South Wales
+              abbreviation: NSW
+            postcode: '2000'
+            confidence: 2
+          geo:
+            level:
+              code: 7
+              name: LOCALITY, STREET, ADDRESS
+            geocodes:
+              - latitude: -33.85351875
+                longitude: 150.8947369
+                isDefault: true
+                reliability:
+                  code: 2
+                  name: WITHIN ADDRESS SITE BOUNDARY OR ACCESS POINT
+                type:
+                  code: 2
+                  name: PROPERTY CENTROID
+        links:
+          self: /addresses/GANT_718592778
+      links:
+        self: /addresses/GANT_718592778
+  
+  # ============================================================================
+  # Root Types
+  # ============================================================================
+  Root:
+    type: object
+    description: API root response (links provided in headers)