openapi: 3.2.0
info:
  title: ROOTE Mobility API
  version: 2.0.0
  description: Worldwide live mobility near a coordinate.
servers:
- url: https://api.roote.ai
  description: ROOTE API
tags:
- name: Mobility
paths:
  /v1/mobility/nearby:
    get:
      operationId: getNearbyMobility
      security:
      - {}
      - bearerAuth: []
      summary: Find nearby shared mobility
      description: Returns canonical ROOTE mobility entities. High-confidence observations of the same physical station are resolved and merged before counts, pagination and billing. Provider identity, provenance, cache, usage, protection and orchestration diagnostics are included only when debug=true. A valid token with data:read is required. Radius is capped at 400 metres.
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          minimum: -90
          maximum: 90
        description: Latitude of query_origin
      - name: lon
        in: query
        required: false
        schema:
          type: number
          minimum: -180
          maximum: 180
        description: Longitude of query_origin; supply lon or lng
      - name: lng
        in: query
        required: false
        schema:
          type: number
          minimum: -180
          maximum: 180
        description: Alias of lon
      - name: radius
        in: query
        required: false
        schema:
          type: number
          minimum: 1
          default: 400
        description: Requested metres; maximum applied is 400
      - name: modes
        in: query
        required: false
        schema:
          type: string
          default: bicycle,scooter,moped,car
        description: Comma-separated ROOTE modes
      - name: include
        in: query
        required: false
        schema:
          type: string
          default: stations,vehicles
        description: Comma-separated result families
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 100
        description: Requested count; plan limits apply
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Pagination offset
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - geojson
          default: json
        description: Response format
      - name: debug
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: Include provider provenance and internal execution diagnostics
      - name: token
        in: query
        deprecated: true
        schema:
          type: string
        description: Compatibility API token; prefer Authorization Bearer.
      responses:
        '200':
          description: Compact nearby mobility result
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - coverage_complete
                - query_origin
                - radius
                - total
                - results
                - available_actions
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                    - partial
                  coverage_complete:
                    type: boolean
                    description: True only when all relevant requested sources completed sufficiently.
                  message:
                    type: string
                    description: Deterministic human-readable convenience text generated by api.roote.ai; machine consumers must use status, coverage_complete, total, results and warnings.
                  query_origin:
                    type: object
                    required:
                    - lat
                    - lon
                    properties:
                      lat:
                        type: number
                      lon:
                        type: number
                    description: Exact point used to execute the nearby search and calculate distance_meters.
                  radius:
                    type: number
                    maximum: 400
                  total:
                    type: integer
                    minimum: 0
                    description: Number of mode-matching normalized public objects after identity resolution and deduplication, before pagination and plan limits.
                  results:
                    type: object
                    required:
                    - places
                    - lines
                    - stations
                    - vehicles
                    - alerts
                    properties:
                      places:
                        type: array
                        items:
                          type: object
                      lines:
                        type: array
                        items:
                          type: object
                      stations:
                        type: array
                        items:
                          type: object
                          required:
                          - id
                          - type
                          - name
                          - network
                          - location
                          - availability
                          - distance_meters
                          properties:
                            id:
                              type: string
                              pattern: ^roote_station_
                            type:
                              type: string
                              const: station
                            name:
                              type: string
                            network:
                              type: object
                              required:
                              - id
                              - name
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                            location:
                              type: object
                              required:
                              - lat
                              - lon
                              properties:
                                lat:
                                  type: number
                                lon:
                                  type: number
                            capacity:
                              type:
                              - integer
                              - 'null'
                            availability:
                              type: object
                            distance_meters:
                              type: number
                            entity_type:
                              type:
                              - string
                              - 'null'
                              enum:
                              - bicycle_vehicle
                              - bicycle_station
                              - scooter_vehicle
                              - motorscooter_vehicle
                              - car_vehicle
                              - parking
                              - transit_stop
                              - transit_station
                              - null
                            mode:
                              type:
                              - string
                              - 'null'
                            data_class:
                              type: string
                              enum:
                              - realtime
                              - semi_static
                              - static
                            service_status:
                              type: object
                              required:
                              - state
                              properties:
                                state:
                                  type: string
                                  enum:
                                  - operational
                                  - degraded
                                  - unavailable
                                  - maintenance
                                  - unknown
                            capabilities:
                              type: object
                              required:
                              - pickup
                              - return
                              - park
                              - charge
                              - reserve
                              - navigate
                              properties:
                                pickup:
                                  type: boolean
                                return:
                                  type: boolean
                                park:
                                  type: boolean
                                charge:
                                  type: boolean
                                reserve:
                                  type: boolean
                                navigate:
                                  type: boolean
                            action_state:
                              type: object
                              additionalProperties:
                                type: string
                                enum:
                                - available_now
                                - unavailable_now
                                - unknown
                            context_actions:
                              type: array
                              items:
                                type: object
                                required:
                                - id
                                - intent
                                - mode
                                properties:
                                  id:
                                    type: string
                                  intent:
                                    type: string
                                    enum:
                                    - explore
                                    - pickup
                                    - return
                                    - depart
                                    - arrive
                                    - park
                                    - charge
                                    - reserve
                                  mode:
                                    type: string
                                    enum:
                                    - bicycle
                                    - scooter
                                    - moped
                                    - car
                                    - other
                      vehicles:
                        type: array
                        items:
                          type: object
                          required:
                          - source
                          - source_id
                          - network_id
                          properties:
                            source:
                              type: object
                              required:
                              - entity_type
                              - mode
                              - data_class
                              - service_status
                              - capabilities
                              - action_state
                              - context_actions
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                                location:
                                  type: object
                                  required:
                                  - lat
                                  - lon
                                  properties:
                                    lat:
                                      type: number
                                    lon:
                                      type: number
                                source_kind:
                                  type: string
                                  enum:
                                  - provider
                                  - gbfs
                                distance_meters:
                                  type: number
                                  description: Straight-line distance in meters from query_origin to the entity location.
                                entity_type:
                                  type:
                                  - string
                                  - 'null'
                                  enum:
                                  - bicycle_vehicle
                                  - bicycle_station
                                  - scooter_vehicle
                                  - motorscooter_vehicle
                                  - car_vehicle
                                  - parking
                                  - transit_stop
                                  - transit_station
                                  - null
                                mode:
                                  type:
                                  - string
                                  - 'null'
                                data_class:
                                  type: string
                                  enum:
                                  - realtime
                                  - semi_static
                                  - static
                                service_status:
                                  type: object
                                  required:
                                  - state
                                  properties:
                                    state:
                                      type: string
                                      enum:
                                      - operational
                                      - degraded
                                      - unavailable
                                      - maintenance
                                      - unknown
                                capabilities:
                                  type: object
                                  required:
                                  - pickup
                                  - return
                                  - park
                                  - charge
                                  - reserve
                                  - navigate
                                  properties:
                                    pickup:
                                      type: boolean
                                    return:
                                      type: boolean
                                    park:
                                      type: boolean
                                    charge:
                                      type: boolean
                                    reserve:
                                      type: boolean
                                    navigate:
                                      type: boolean
                                action_state:
                                  type: object
                                  additionalProperties:
                                    type: string
                                    enum:
                                    - available_now
                                    - unavailable_now
                                    - unknown
                                context_actions:
                                  type: array
                                  items:
                                    type: object
                                    required:
                                    - id
                                    - intent
                                    - mode
                                    properties:
                                      id:
                                        type: string
                                      intent:
                                        type: string
                                        enum:
                                        - explore
                                        - pickup
                                        - return
                                        - depart
                                        - arrive
                                        - park
                                        - charge
                                        - reserve
                                      mode:
                                        type: string
                                        enum:
                                        - bicycle
                                        - scooter
                                        - moped
                                        - car
                                        - other
                            source_id:
                              type: string
                            network_id:
                              type: string
                            canonical_id:
                              type: 'null'
                            resolution_status:
                              type: string
                              enum:
                              - unresolved
                              - merged
                              - possible_match
                            roote_id:
                              type: string
                            entity_source:
                              type: string
                              const: roote
                            resolution_confidence:
                              type: number
                              minimum: 0
                              maximum: 1
                            provenance:
                              type: array
                              items:
                                type: object
                                properties:
                                  kind:
                                    type: string
                                    enum:
                                    - provider
                                    - roote_internal
                                  source:
                                    type: string
                                  provider:
                                    type: string
                                  entity_id:
                                    type: string
                                  source_id:
                                    type: string
                                  network_id:
                                    type: string
                                  fields:
                                    type: array
                                    items:
                                      type: string
                            conflicts:
                              type: array
                              items:
                                type: object
                      alerts:
                        type: array
                        items:
                          type: object
                  available_actions:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - intent
                      - mode
                      properties:
                        id:
                          type: string
                        intent:
                          type: string
                          enum:
                          - explore
                          - pickup
                          - return
                          - depart
                          - arrive
                          - park
                          - charge
                          - reserve
                        mode:
                          type: string
                          enum:
                          - bicycle
                          - scooter
                          - moped
                          - car
                          - other
                  requested_radius:
                    type: number
                  requested_limit:
                    type: integer
                  limit:
                    type: integer
                  warnings:
                    type: array
                    items:
                      type: object
                      required:
                      - code
                      - message
                      - requested
                      - applied
                      properties:
                        code:
                          type: string
                          enum:
                          - radius_capped
                          - limit_capped
                        message:
                          type: string
                        requested:
                          type: number
                        applied:
                          type: number
                  debug:
                    type: object
                    properties:
                      sources:
                        type: array
                        items:
                          type: object
                          properties:
                            source_id:
                              type: string
                            status:
                              type: string
                            raw_count:
                              type: integer
                            matched_count:
                              type: integer
                            reason:
                              type:
                              - string
                              - 'null'
                      resolution:
                        type: object
                      entities:
                        type: array
                        description: Canonical station provenance and entity-resolution diagnostics.
                        items:
                          type: object
                      realtime:
                        type: object
                      warnings:
                        type: array
                        items:
                          type: string
                      usage:
                        type: object
                      protection:
                        type: object
                      orchestration:
                        type: object
                      requested_radius:
                        type: number
                      applied_radius:
                        type: number
                      requested_limit:
                        type: integer
                      applied_limit:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
                      coverage:
                        type: string
                    description: Safe internal diagnostics returned only when debug=true.
            application/geo+json:
              schema:
                type: object
                required:
                - query_origin
                - type
                - features
                - available_actions
                properties:
                  query_origin:
                    type: object
                    required:
                    - lat
                    - lon
                    properties:
                      lat:
                        type: number
                      lon:
                        type: number
                    description: Coordinates used as the spatial origin for this GeoJSON query.
                  type:
                    type: string
                    const: FeatureCollection
                  features:
                    type: array
                    items:
                      type: object
                  available_actions:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - intent
                      - mode
                      properties:
                        id:
                          type: string
                        intent:
                          type: string
                          enum:
                          - explore
                          - pickup
                          - return
                          - depart
                          - arrive
                          - park
                          - charge
                          - reserve
                        mode:
                          type: string
                          enum:
                          - bicycle
                          - scooter
                          - moped
                          - car
                          - other
                  meta:
                    type: object
        '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
      tags:
      - Mobility
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rt_live_...