openapi: 3.1.0
info:
  title: OpenAPI definition
  version: v0
servers:
  - url: http://localhost:8085
    description: Generated server url
tags:
  - name: Addresses
    description: Swiss address search API
paths:
  /api/addresses/{id}:
    get:
      tags:
        - Addresses
      summary: Get address by ID
      description: Retrieves a single address by its federal address identifier (EGAID)
      operationId: getAddress
      parameters:
        - name: id
          in: path
          description: Federal address identifier (EGAID)
          required: true
          schema:
            type: integer
            format: int64
          example: 100001234
        - name: X-ALPAddress-API-Version
          in: header
          schema:
            type: string
            default: 1.0.0
            enum:
              - 1.0.0
      responses:
        '200':
          description: Address found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '404':
          description: Address not found
  /api/addresses/search:
    get:
      tags:
        - Addresses
      summary: Search addresses
      description: >
        Search for addresses using structured criteria. All parameters are
        optional and can be combined.

        At least one search criterion must be provided.


        Examples:

        - Search by postal code: ?zip4=8001

        - Search by canton and locality: ?canton=ZH&localityName=Zürich

        - Search by municipality: ?municipalityName=Bern
      operationId: searchAddresses
      parameters:
        - name: zip4
          in: query
          description: 4-digit postal code (PLZ/NPA)
          required: false
          schema:
            type: integer
            format: int32
            maximum: 9999
            minimum: 1000
          example: 8001
        - name: zipId
          in: query
          description: Postal locality identifier (ONRP)
          required: false
          schema:
            type: integer
            format: int64
          example: 4000
        - name: localityName
          in: query
          description: Locality name (partial match)
          required: false
          schema:
            type: string
            maxLength: 100
            minLength: 0
          example: Zürich
        - name: municipalityName
          in: query
          description: Municipality name (partial match)
          required: false
          schema:
            type: string
            maxLength: 100
            minLength: 0
          example: Zürich
        - name: canton
          in: query
          description: Canton abbreviation (2 letters)
          required: false
          schema:
            type: string
            maxLength: 2
            minLength: 2
          example: ZH
        - name: streetName
          in: query
          description: Street name
          required: false
          schema:
            type: string
          example: Rue de la Gare
        - name: addressStatus
          in: query
          description: Address status
          required: false
          schema:
            type: string
            default: REAL
            enum:
              - PLANNED
              - REAL
              - OUTDATED
          example: REAL
        - name: addressCategories
          in: query
          description: Address categories
          required: false
          schema:
            type: array
            default:
              - RESIDENTIAL
            items:
              type: string
              enum:
                - UNCATEGORIZED
                - TEMPORARY
                - RESIDENTIAL
                - OTHER_RESIDENTIAL
                - PARTLY_RESIDENTIAL
                - NON_RESIDENTIAL
                - SPECIAL
          example: RESIDENTIAL,TEMPORARY
        - name: limit
          in: query
          description: Maximum number of results (1-100)
          required: false
          schema:
            type: integer
            format: int32
            default: 100
            maximum: 100
            minimum: 1
          example: 10
        - name: X-ALPAddress-API-Version
          in: header
          schema:
            type: string
            default: 1.0.0
            enum:
              - 1.0.0
      responses:
        '200':
          description: List of matching addresses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          description: Invalid search criteria or no criteria provided
  /api/addresses/autocomplete:
    get:
      tags:
        - Addresses
      summary: Autocomplete addresses
      description: >
        Search for addresses using full-text search with relevance scoring.

        Returns addresses that match the query with a relevance score above the
        threshold.


        Examples:

        - ?query=Bahnhofstrasse Zürich

        - ?query=Bundesplatz 10&threshold=0.5

        - ?query=8001 Zürich&limit=5
      operationId: autocomplete
      parameters:
        - name: query
          in: query
          description: Search query for autocomplete
          required: true
          schema:
            type: string
            maxLength: 2147483647
            minLength: 1
          example: Bahnhofstrasse Zürich
        - name: threshold
          in: query
          description: Minimum relevance score threshold (0.0 to 1.0)
          required: false
          schema:
            type: number
            format: double
            default: 0.5
            maximum: 1
            minimum: 0
          example: 0.5
        - name: limit
          in: query
          description: Maximum number of results (1-20)
          required: false
          schema:
            type: integer
            format: int32
            default: 10
            maximum: 20
            minimum: 1
          example: 10
        - name: addressStatus
          in: query
          description: Address status
          required: false
          schema:
            type: string
            default: REAL
            enum:
              - PLANNED
              - REAL
              - OUTDATED
          example: REAL
        - name: addressCategories
          in: query
          description: Address categories
          required: false
          schema:
            type: array
            default:
              - RESIDENTIAL
            items:
              type: string
              enum:
                - UNCATEGORIZED
                - TEMPORARY
                - RESIDENTIAL
                - OTHER_RESIDENTIAL
                - PARTLY_RESIDENTIAL
                - NON_RESIDENTIAL
                - SPECIAL
          example: RESIDENTIAL,TEMPORARY
        - name: X-ALPAddress-API-Version
          in: header
          schema:
            type: string
            default: 1.0.0
            enum:
              - 1.0.0
      responses:
        '200':
          description: List of matching addresses with scores
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressResult'
        '400':
          description: Invalid query parameter
components:
  schemas:
    Address:
      type: object
      description: Swiss building address
      properties:
        id:
          type: integer
          format: int64
          description: Federal address identifier (EGAID)
          example: 100001234
        streetName:
          type: string
          description: Street name
          example: Bahnhofstrasse
        houseNumber:
          type: string
          description: House/building number
          example: 1a
        postalCode:
          type: integer
          format: int32
          description: 4-digit postal code (PLZ/NPA)
          example: 8001
          maximum: 9999
          minimum: 1000
        locality:
          type: string
          description: Locality name
          example: Zürich
        status:
          type: string
          enum:
            - PLANNED
            - REAL
            - OUTDATED
        category:
          type: string
          enum:
            - UNCATEGORIZED
            - TEMPORARY
            - RESIDENTIAL
            - OTHER_RESIDENTIAL
            - PARTLY_RESIDENTIAL
            - NON_RESIDENTIAL
            - SPECIAL
        municipality:
          $ref: '#/components/schemas/Municipality'
          description: Municipality information
    Canton:
      type: object
      description: Swiss canton (Kanton)
      properties:
        abbreviation:
          type: string
          description: Canton abbreviation (2 letters)
          example: ZH
        name:
          type: string
          description: Full canton name
          example: Zürich
    District:
      type: object
      description: Swiss district (Bezirk)
      properties:
        name:
          type: string
          description: District name
          example: Bezirk Zürich
        canton:
          $ref: '#/components/schemas/Canton'
          description: Canton information
    Municipality:
      type: object
      description: Swiss municipality (Gemeinde)
      properties:
        longName:
          type: string
          description: Full municipality name
          example: Zürich
        shortName:
          type: string
          description: Short municipality name
          example: Zürich
        district:
          $ref: '#/components/schemas/District'
          description: District information
    AddressResult:
      type: object
      description: Address with relevance score from autocomplete search
      properties:
        id:
          type: integer
          format: int64
          description: Federal address identifier (EGAID)
          example: 100001234
        streetName:
          type: string
          description: Street name
          example: Bahnhofstrasse
        houseNumber:
          type: string
          description: House number
          example: 1a
        buildingName:
          type: string
          description: Building name
          example: 1a
        zip4:
          type: integer
          format: int32
          description: 4-digit postal code (PLZ/NPA)
          example: 8001
          maximum: 9999
          minimum: 1000
        zipa:
          type: integer
          format: int32
          description: additional postal code
          example: 25
          maximum: 100
          minimum: 0
        locality:
          type: string
          description: Locality name
          example: Zürich
        municipality:
          type: string
          description: Municipality name
          example: Zürich
        canton:
          type: string
          description: Canton Abbreviation
          enum:
            - ZH
            - BE
            - LU
            - UR
            - SZ
            - OW
            - NW
            - GL
            - ZG
            - FR
            - SO
            - BS
            - BL
            - SH
            - AR
            - AI
            - SG
            - GR
            - AG
            - TG
            - TI
            - VD
            - VS
            - NE
            - GE
            - JU
          example: VD
        score:
          type: number
          format: double
          description: Relevance score from full-text search (0.0 to 1.0)
          example: 0.85
