openapi: 3.0.3
info:
  title: TIER / Dott GBFS 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: Discovery
    description: GBFS discovery and versioning
  - name: System
    description: System-level metadata and pricing
  - name: Vehicles
    description: Vehicle inventory, types, and real-time status
  - name: Stations
    description: Station information and availability
  - name: Zones
    description: Geofencing rules and operational zones
paths:
  /gbfs_versions.json:
    get:
      tags: [Discovery]
      summary: List GBFS Versions
      description: Returns all GBFS schema versions exposed by Dott across systems.
      operationId: listGbfsVersions
      responses:
        '200':
          description: GBFS versions document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GbfsVersions'
  /{system_id}/gbfs.json:
    get:
      tags: [Discovery]
      summary: Get GBFS Discovery Document
      description: >-
        Returns the GBFS auto-discovery document for a given city/system,
        listing every available feed URL.
      operationId: getGbfsDiscovery
      parameters:
        - $ref: '#/components/parameters/SystemId'
      responses:
        '200':
          description: GBFS discovery document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GbfsDiscovery'
  /{system_id}/system_information.json:
    get:
      tags: [System]
      summary: Get System Information
      description: >-
        Returns operator name, language, timezone, rental app deep links,
        and system identifier for the given city.
      operationId: getSystemInformation
      parameters:
        - $ref: '#/components/parameters/SystemId'
      responses:
        '200':
          description: System information feed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemInformation'
  /{system_id}/system_pricing_plans.json:
    get:
      tags: [System]
      summary: Get System Pricing Plans
      description: >-
        Returns unlock price, per-minute rate, currency, and plan IDs for
        each vehicle type in the system.
      operationId: getSystemPricingPlans
      parameters:
        - $ref: '#/components/parameters/SystemId'
      responses:
        '200':
          description: Pricing plans feed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemPricingPlans'
  /{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'
  /{system_id}/station_information.json:
    get:
      tags: [Stations]
      summary: Get Station Information
      description: Static station definitions (where stations are deployed in the system).
      operationId: getStationInformation
      parameters:
        - $ref: '#/components/parameters/SystemId'
      responses:
        '200':
          description: Station information feed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StationInformation'
  /{system_id}/station_status.json:
    get:
      tags: [Stations]
      summary: Get Station Status
      description: Real-time docking station availability and vehicle counts.
      operationId: getStationStatus
      parameters:
        - $ref: '#/components/parameters/SystemId'
      responses:
        '200':
          description: Station status feed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StationStatus'
  /{system_id}/geofencing_zones.json:
    get:
      tags: [Zones]
      summary: Get Geofencing Zones
      description: >-
        GeoJSON FeatureCollection describing no-ride, no-park, low-speed,
        and operational zones within the system.
      operationId: getGeofencingZones
      parameters:
        - $ref: '#/components/parameters/SystemId'
      responses:
        '200':
          description: Geofencing zones feed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeofencingZones'
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'
    GbfsVersions:
      allOf:
        - $ref: '#/components/schemas/FeedMeta'
        - type: object
          properties:
            data:
              type: object
              properties:
                versions:
                  type: array
                  items:
                    type: object
                    properties:
                      version: { type: string }
                      url: { type: string, format: uri }
    GbfsDiscovery:
      allOf:
        - $ref: '#/components/schemas/FeedMeta'
        - type: object
          properties:
            data:
              type: object
              additionalProperties:
                type: object
                properties:
                  feeds:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string }
                        url: { type: string, format: uri }
    SystemInformation:
      allOf:
        - $ref: '#/components/schemas/FeedMeta'
        - type: object
          properties:
            data:
              type: object
              properties:
                system_id: { type: string }
                language: { type: string }
                name: { type: string }
                timezone: { type: string }
                rental_apps:
                  type: object
                  properties:
                    android:
                      type: object
                      properties:
                        discovery_uri: { type: string }
                        store_uri: { type: string, format: uri }
                    ios:
                      type: object
                      properties:
                        discovery_uri: { type: string }
                        store_uri: { type: string, format: uri }
    SystemPricingPlans:
      allOf:
        - $ref: '#/components/schemas/FeedMeta'
        - type: object
          properties:
            data:
              type: object
              properties:
                plans:
                  type: array
                  items:
                    type: object
                    properties:
                      plan_id: { type: string }
                      name: { type: string }
                      description: { type: string }
                      currency: { type: string }
                      price: { type: number, format: float }
                      is_taxable: { type: boolean }
                      per_min_pricing:
                        type: array
                        items:
                          type: object
                          properties:
                            interval: { type: integer }
                            rate: { type: number, format: float }
                            start: { type: integer }
    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 }
    StationInformation:
      allOf:
        - $ref: '#/components/schemas/FeedMeta'
        - type: object
          properties:
            data:
              type: object
              properties:
                stations:
                  type: array
                  items:
                    type: object
                    properties:
                      station_id: { type: string }
                      name: { type: string }
                      lat: { type: number, format: double }
                      lon: { type: number, format: double }
                      capacity: { type: integer }
    StationStatus:
      allOf:
        - $ref: '#/components/schemas/FeedMeta'
        - type: object
          properties:
            data:
              type: object
              properties:
                stations:
                  type: array
                  items:
                    type: object
                    properties:
                      station_id: { type: string }
                      num_bikes_available: { type: integer }
                      num_docks_available: { type: integer }
                      is_installed: { type: boolean }
                      is_renting: { type: boolean }
                      is_returning: { type: boolean }
                      last_reported: { type: integer, format: int64 }
    GeofencingZones:
      allOf:
        - $ref: '#/components/schemas/FeedMeta'
        - type: object
          properties:
            data:
              type: object
              properties:
                geofencing_zones:
                  type: object
                  properties:
                    type:
                      type: string
                      enum: [FeatureCollection]
                    features:
                      type: array
                      items:
                        type: object
                        properties:
                          type: { type: string, enum: [Feature] }
                          geometry: { type: object }
                          properties:
                            type: object
                            properties:
                              name: { type: string }
                              start: { type: integer }
                              end: { type: integer }
                              rules:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    vehicle_type_id:
                                      type: array
                                      items: { type: string }
                                    ride_allowed: { type: boolean }
                                    ride_through_allowed: { type: boolean }
                                    maximum_speed_kph: { type: integer }
                                    station_parking: { type: boolean }