openapi: 3.0.3
info:
  title: TIER / Dott GBFS Discovery Vehicles API
  version: '2.3'
  description: 'Public GBFS (General Bikeshare Feed Specification) 2.3 endpoints for TIER / Dott shared micromobility systems. After the 2024 TIER + Dott merger, all GBFS feeds are served under the unified ridedott.com infrastructure at https://gbfs.api.ridedott.com/public/v2. Each city or zone is a separate "system" identified by a slug (e.g. `berlin`, `paris`, `london`, `madrid`, `dubai`). The API exposes a discovery document plus a standard set of GBFS feeds: system information, vehicle types, station information, station status, free-floating vehicle status, geofencing zones, and system pricing plans. All endpoints are unauthenticated and return JSON.'
  contact:
    name: Dott (formerly TIER)
    url: https://ridedott.com/
servers:
- url: https://gbfs.api.ridedott.com/public/v2
  description: Production GBFS feeds (TIER and Dott systems unified)
tags:
- name: Vehicles
  description: Vehicle inventory, types, and real-time status
paths:
  /{system_id}/vehicle_types.json:
    get:
      tags:
      - Vehicles
      summary: Get Vehicle Types
      description: Returns the form factors (scooter, bicycle), propulsion types, max range, and pricing-plan associations for vehicles operated in the system.
      operationId: getVehicleTypes
      parameters:
      - $ref: '#/components/parameters/SystemId'
      responses:
        '200':
          description: Vehicle types feed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VehicleTypes'
  /{system_id}/free_bike_status.json:
    get:
      tags:
      - Vehicles
      summary: Get Free Vehicle Status
      description: Real-time list of free-floating vehicles available for rent, including position, battery level (`current_fuel_percent`), remaining range, pricing plan, and rental URIs.
      operationId: getFreeBikeStatus
      parameters:
      - $ref: '#/components/parameters/SystemId'
      responses:
        '200':
          description: Free vehicle status feed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FreeBikeStatus'
components:
  parameters:
    SystemId:
      name: system_id
      in: path
      required: true
      description: The Dott/TIER system slug, e.g. `berlin`, `paris`, `london`, `madrid`, `rome`, `brussels`, `dubai`. Listed in the MobilityData GBFS systems registry.
      schema:
        type: string
        example: berlin
  schemas:
    FeedMeta:
      type: object
      required:
      - last_updated
      - ttl
      - version
      properties:
        last_updated:
          type: integer
          format: int64
          description: POSIX timestamp when the feed was last updated.
        ttl:
          type: integer
          description: Seconds until the next regeneration.
        version:
          type: string
          example: '2.3'
    VehicleTypes:
      allOf:
      - $ref: '#/components/schemas/FeedMeta'
      - type: object
        properties:
          data:
            type: object
            properties:
              vehicle_types:
                type: array
                items:
                  type: object
                  properties:
                    vehicle_type_id:
                      type: string
                    form_factor:
                      type: string
                      enum:
                      - scooter
                      - bicycle
                      - car
                      - moped
                      - other
                      - cargo_bicycle
                    propulsion_type:
                      type: string
                      enum:
                      - human
                      - electric_assist
                      - electric
                      - combustion
                      - combustion_diesel
                      - hybrid
                      - plug_in_hybrid
                      - hydrogen_fuel_cell
                    max_range_meters:
                      type: integer
                    pricing_plan_ids:
                      type: array
                      items:
                        type: string
    FreeBikeStatus:
      allOf:
      - $ref: '#/components/schemas/FeedMeta'
      - type: object
        properties:
          data:
            type: object
            properties:
              bikes:
                type: array
                items:
                  type: object
                  properties:
                    bike_id:
                      type: string
                    lat:
                      type: number
                      format: double
                    lon:
                      type: number
                      format: double
                    is_reserved:
                      type: boolean
                    is_disabled:
                      type: boolean
                    current_range_meters:
                      type: integer
                    current_fuel_percent:
                      type: number
                      format: float
                    vehicle_type_id:
                      type: string
                    pricing_plan_id:
                      type: string
                    last_reported:
                      type: integer
                      format: int64
                    rental_uris:
                      type: object
                      properties:
                        android:
                          type: string
                          format: uri
                        ios:
                          type: string
                          format: uri
                        web:
                          type: string
                          format: uri