openapi: 3.0.3
info:
  version: v1.0.0
  title: LE-KO Addresses API
  license:
    name: private
    url: https://le-ko.deggex.com
  contact:
    email: denis@deggex.awsapps.com
  description: LE-KO Address management and geocoding API for managing user addresses, geocoding, reverse geocoding, and location suggestions.
servers:
  - url: https://booking-{env}.le-ko.deggex.com/{basePath}
    description: Addresses endpoint
    variables:
      basePath:
        default: v1
      env:
        default: dev
security:
  - bearerHttpAuthentication: []
tags:
  - name: Addresses
    description: Address management and geocoding
paths:
  /addresses:
    get:
      summary: Get filtered addresses
      operationId: getFilteredAddresses
      description: |
        ✨ Gets addresses by filters. You must specify either `userId` or a combination of  `lat`, `lng`, and `distanceMeters` to filter the addresses.
      tags:
        - Addresses
      parameters:
        - name: userId
          in: query
          required: false
          description: The user ID to filter addresses
          schema:
            $ref: '#/components/schemas/Id'
        - name: lat
          in: query
          required: false
          description: Latitude for location-based filtering
          schema:
            type: number
            format: double
        - name: lng
          in: query
          required: false
          description: Longitude for location-based filtering
          schema:
            type: number
            format: double
        - name: distanceMeters
          in: query
          required: false
          description: Distance in meters for location-based filtering
          schema:
            type: integer
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of filtered addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Address'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      summary: Register a new address
      operationId: createAddress
      description: |
        ✨ Register a new address. The formatted address should ideally match exactly the format returned by the geosuggest API. This ensures consistency and accuracy when storing and retrieving address information.
      tags:
        - Addresses
      parameters:
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressCreate'
      responses:
        '200':
          description: Address registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /addresses/{addressId}:
    get:
      summary: Get an address by ID
      operationId: getAddressById
      description: ✨ Retrieve a specific address using its unique ID.
      tags:
        - Addresses
      parameters:
        - name: addressId
          in: path
          required: true
          description: The address ID
          schema:
            $ref: '#/components/schemas/Id'
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Address details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Address not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update an address
      operationId: updateAddress
      description: ✨ Update an address by replacing all fields.
      tags:
        - Addresses
      parameters:
        - name: addressId
          in: path
          required: true
          description: The address ID
          schema:
            $ref: '#/components/schemas/Id'
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressCreate'
      responses:
        '200':
          description: Address updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressUpdateResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Address not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete an address
      operationId: deleteAddress
      description: ✨ Delete an address by ID.
      tags:
        - Addresses
      parameters:
        - name: addressId
          in: path
          required: true
          description: The address ID
          schema:
            $ref: '#/components/schemas/Id'
        - name: currentUserId
          in: query
          required: true
          description: The user of the ID attempting this operation
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '204':
          description: Address deleted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Current user is forbidden from this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Address not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /addresses/{addressId}/type:
    post:
      operationId: setUserAddressType
      summary: Set the type of an address
      description: ✨ Sets the type of an address and unsets any other addresses of said type for the  same user
      tags:
        - Addresses
      parameters:
        - name: addressId
          in: path
          required: true
          description: The address ID
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetUserAddressType'
      responses:
        '200':
          description: Status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Address doesn't exist or user has no permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /addresses/geocode:
    get:
      summary: Geocode addresses
      operationId: geocodeAddresses
      description: |
        ✨ Geocoding is the process of converting addresses into geographic coordinates. This endpoint suggests addresses based on a query string and returns their corresponding geographic coordinates.
      tags:
        - Addresses
      parameters:
        - name: query
          in: query
          required: true
          description: The query string to suggest addresses
          schema:
            type: string
            minLength: 1
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of geocoded addresses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GeocodedAddress'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /addresses/reverse-geocode:
    get:
      summary: Reverse geocode.
      operationId: reverseGeocode
      description: |
        ✨ Reverse geocoding is the process of converting geographic coordinates into human-readable addresses. This endpoint returns suggested addresses based on the provided geographic coordinates in the query string.
      tags:
        - Addresses
      parameters:
        - name: latitude
          in: query
          required: true
          description: Latitude to reverse geocode.
          schema:
            type: number
            format: double
            minimum: -90
            maximum: 90
        - name: longitude
          in: query
          required: true
          description: longitude to reverse geocode.
          schema:
            type: number
            format: double
            minimum: -180
            maximum: 180
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of geocoded addresses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodedAddress'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /addresses/suggest:
    get:
      summary: Suggest addresses
      operationId: suggestAddresses
      description: ✨ Suggest addresses based on a query string.
      tags:
        - Addresses
      parameters:
        - name: query
          in: query
          required: true
          description: The query string to suggest addresses
          schema:
            type: string
        - name: baseLat
          in: query
          required: false
          description: Optional base latitude for location-based suggestions
          schema:
            type: number
            format: float
            minimum: -90
            maximum: 90
        - name: baseLong
          in: query
          required: false
          description: Optional base longitude for location-based suggestions
          schema:
            type: number
            format: float
            minimum: -180
            maximum: 180
        - name: addressType
          in: query
          required: false
          description: |
            Filter suggestion results by address granularity. "Specific" returns entrance, business, and house-level results only. "General" returns all result types including businesses and geographic objects. "NoHouses" returns broader results excluding house-level addresses (streets, metro stations, districts, regions).
          schema:
            $ref: '#/components/schemas/GeosuggestType'
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of suggested addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GeosuggestedAddress'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /nearby:
    get:
      summary: Get nearby users based on addresses
      operationId: getNearbyUsers
      description: |
        ✨ Retrieves user IDs of nearby users based on a provided
        latitude and longitude. This endpoint returns a list of
        user IDs for users located within a certain radius of the
        given coordinates.
      tags:
        - Addresses
      parameters:
        - name: userId
          in: query
          required: true
          description: The ID of the user which is requesting other nearby users. This is used to filter them out of the results.
          schema:
            type: string
            format: uuid
        - name: latitude
          in: query
          required: true
          schema:
            type: number
            format: double
        - name: longitude
          in: query
          required: true
          schema:
            type: number
            format: double
        - name: maxDistanceInMeters
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of nearby user IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uuid
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer token using a JWT
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Id:
      type: string
      example: 4b72d209-debd-45e1-93cc-7640bf7d39bf
      description: Database entity primary key uuid
      format: uuid
      maxLength: 36
      minLength: 36
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    AddressType:
      type: string
      enum:
        - Main
    Address:
      type: object
      properties:
        id:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        title:
          type: string
        formattedAddress:
          type: string
        addressType:
          $ref: '#/components/schemas/AddressType'
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        entrance:
          type: string
        floor:
          type: string
        locationComment:
          type: string
        city:
          type: string
        street:
          type: string
        subtitle:
          type: string
        tags:
          type: array
          items:
            type: string
      required:
        - id
        - userId
        - formattedAddress
    Error:
      type: object
      required:
        - code
        - message
        - endpoint
        - requestId
      properties:
        code:
          type: string
          description: Error unique code
          enum:
            - validation
            - internal
            - oops
            - unexpected
            - tooManyRequests
            - notFound
            - unauthorized
            - forbidden
        message:
          type: string
          description: Error message
        endpoint:
          type: string
        requestId:
          type: string
    Errors:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    AddressCreate:
      type: object
      properties:
        userId:
          type: string
          format: uuid
        title:
          type: string
        formattedAddress:
          type: string
        entrance:
          type: string
        floor:
          type: string
        locationComment:
          type: string
        type:
          $ref: '#/components/schemas/AddressType'
        subtitle:
          type: string
        tags:
          type: array
          items:
            type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
      required:
        - userId
        - formattedAddress
    AddressUpdateResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/Address'
        - type: object
          properties:
            affectedBookingIds:
              type: array
              description: Booking IDs with status Accepted on future events that were affected by this address change. Present only when the updated address had future events referencing it.
              items:
                type: string
                format: uuid
    SetUserAddressType:
      type: object
      properties:
        currentUserId:
          type: string
          format: uuid
        addressType:
          $ref: '#/components/schemas/AddressType'
      required:
        - currentUserId
        - addressType
    GeocodedAddress:
      type: object
      required:
        - formattedAddress
        - latitude
        - longitude
        - street
        - region
        - city
        - uri
      properties:
        formattedAddress:
          type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        street:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        uri:
          type: string
    GeosuggestType:
      type: string
      enum:
        - Specific
        - General
        - NoHouses
    GeosuggestedAddress:
      type: object
      required:
        - title
        - formattedAddress
        - street
        - region
        - city
        - uri
      properties:
        title:
          type: string
        formattedAddress:
          type: string
        street:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
          nullable: true
        subtitle:
          type: string
          nullable: true
        uri:
          type: string
  parameters:
    TraceparentHeader:
      name: traceparent
      in: header
      required: false
      description: W3C Trace Context traceparent header for request tracing
      schema:
        type: string
        pattern: ^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$
        example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01