openapi: 3.2.0
info:
  title: ROOTE Services API
  version: 2.0.0
  description: Worldwide live mobility near a coordinate.
servers:
- url: https://api.roote.ai
  description: ROOTE API
tags:
- name: Services
paths:
  /v1/services/nearby:
    get:
      operationId: getNearbyServices
      security:
      - {}
      - bearerAuth: []
      summary: Find nearby urban services
      description: Returns a compact service result with per-type counts. Parking and charging reuse the same Google adapter as their specialized endpoints; lockers use the public, non-guaranteed InPost Geowidget source behind a defensive adapter. Provider failures produce partial coverage; provider orchestration and counters are returned only when debug=true.
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          minimum: -90
          maximum: 90
        description: Latitude of query_origin
      - name: lon
        in: query
        required: true
        schema:
          type: number
          minimum: -180
          maximum: 180
        description: Longitude of query_origin
      - name: types
        in: query
        required: true
        schema:
          type: string
        description: 'Comma-separated types: aed, toilets, wifi, fountain, parking, charging, locker. drinking_water remains a compatibility alias.'
      - name: country
        in: query
        required: false
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
        description: Optional ISO 3166-1 alpha-2 country hint passed to providers that support it, including InPost.
      - name: radius
        in: query
        required: false
        schema:
          type: number
          exclusiveMinimum: 0
          maximum: 10000
          default: 1500
        description: Requested metres; values above 10000 are clamped to 10000
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        description: Requested aggregate count; values above 200 are clamped to 200. Google returns at most 20 items for each Google-backed category; InPost returns at most 100.
      - name: debug
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: Include internal provider, cache and requested/applied diagnostics
      - name: token
        in: query
        deprecated: true
        schema:
          type: string
        description: Compatibility API token; prefer Authorization Bearer.
      responses:
        '200':
          description: Compact nearby urban services result
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - query_origin
                - radius
                - total
                - summary
                - results
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    - empty
                    - partial
                    - error
                  message:
                    type: string
                    description: Deterministic convenience message for empty or incomplete coverage.
                  query_origin:
                    type: object
                    required:
                    - lat
                    - lon
                    properties:
                      lat:
                        type: number
                      lon:
                        type: number
                    description: Exact canonical coordinates used for the services search and distance calculation.
                  radius:
                    type: number
                    maximum: 10000
                    description: Effective search radius in metres.
                  total:
                    type: integer
                    minimum: 0
                  summary:
                    type: object
                    description: Returned result count for every requested service type, including zero counts.
                    additionalProperties:
                      type: integer
                      minimum: 0
                  results:
                    type: array
                    maxItems: 200
                    items:
                      type: object
                      required:
                      - id
                      - type
                      - service_type
                      - name
                      - location
                      - distance_meters
                      - attributes
                      - source_id
                      - source_type
                      properties:
                        id:
                          type: string
                        type:
                          type: string
                          const: service
                        service_type:
                          type: string
                          enum:
                          - aed
                          - toilets
                          - drinking_water
                          - fountain
                          - wifi
                          - parking
                          - charging
                          - locker
                        provider:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                        external_id:
                          type: string
                        name:
                          type: string
                        location:
                          type: object
                          required:
                          - lat
                          - lon
                          properties:
                            lat:
                              type: number
                            lon:
                              type: number
                        distance_meters:
                          type: integer
                          minimum: 0
                        attributes:
                          type: object
                        source_id:
                          type: string
                          enum:
                          - aedmap
                          - refuge
                          - openstreetmap
                          - google
                          - inpost
                        source_type:
                          type: string
                          enum:
                          - partner_api
                          - community
                  attributions:
                    type: array
                    description: Attributions required when Google-backed parking or charging types are requested.
                    items:
                      type: object
                      required:
                      - provider
                      - display_name
                      - required
                      properties:
                        provider:
                          type: string
                          const: Google
                        display_name:
                          type: string
                          const: Google
                        required:
                          type: boolean
                          const: true
                  debug:
                    type: object
                    description: Internal provider diagnostics returned only when debug=true.
                    properties:
                      providers:
                        type: object
                        additionalProperties:
                          type: object
                          required:
                          - status
                          - raw_count
                          - returned_count
                          properties:
                            status:
                              type: string
                              enum:
                              - ok
                              - timeout
                              - error
                              - unauthorized
                              - unavailable
                            raw_count:
                              type: integer
                              minimum: 0
                            returned_count:
                              type: integer
                              minimum: 0
                      provider_calls:
                        type: integer
                      cache:
                        type: string
                        enum:
                        - hit
                        - miss
                        - partial
                      requested_radius:
                        type: number
                      applied_radius:
                        type: number
                      requested_limit:
                        type: integer
                      applied_limit:
                        type: integer
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '401':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '402':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '403':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '429':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '503':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
      tags:
      - Services
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rt_live_...