openapi: 3.1.0
info:
  title: Bird GBFS Feed
  version: 2.3.0
  summary: Bird's Public General Bikeshare Feed Specification Feed
  description: >-
    OpenAPI description of Bird's public General Bikeshare Feed Specification
    (GBFS) v2.3 surface hosted at https://mds.bird.co/gbfs/v2/public/{city}.
    Each Bird city exposes the same nine GBFS sub-feeds — gbfs (auto-discovery),
    gbfs_versions, system_information, vehicle_types, free_bike_status,
    station_information, station_status, geofencing_zones, system_pricing_plans,
    and system_regions — with a 60-second TTL. Bird operates 88+ city feeds
    across Austria, Belgium, Canada, Switzerland, Germany, Spain, Finland,
    France, Israel, Italy, Portugal, and the United States. Data is licensed
    under Bird's GBFS Data License Agreement.
  contact:
    name: Bird Government Partnerships
    email: city@bird.co
    url: https://www.bird.co/cities
  license:
    name: Bird GBFS Data License Agreement
    url: https://www.bird.co/wp-content/uploads/2019/03/GBFS-Data-License-Agreement-2018-09-25.pdf
servers:
  - url: https://mds.bird.co/gbfs/v2/public/{city}
    description: Bird GBFS public feed for a given city
    variables:
      city:
        default: los-angeles
        description: >-
          City slug for the desired Bird market. Examples include
          los-angeles, madrid, barcelona, helsinki, munich, ulm, calgary,
          edmonton, ottawa, halifax, antwerp, zurich, basel, biel, ulm,
          wienerneustadt. The canonical list lives in the MobilityData
          systems.csv at
          https://github.com/MobilityData/gbfs/blob/master/systems.csv.
paths:
  /gbfs.json:
    get:
      operationId: getGbfsDiscovery
      summary: Get GBFS Auto-Discovery
      description: >-
        Returns the GBFS auto-discovery document listing every sub-feed
        available for this Bird city, with URLs and feed names. Per GBFS
        v2.3, the response is wrapped in language-keyed feeds objects.
      tags:
        - Discovery
      responses:
        '200':
          description: GBFS auto-discovery payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GbfsDiscovery'
  /gbfs_versions.json:
    get:
      operationId: getGbfsVersions
      summary: List GBFS Versions
      description: Lists the GBFS specification versions supported by this Bird city feed.
      tags:
        - Discovery
      responses:
        '200':
          description: Supported GBFS versions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GbfsVersions'
  /system_information.json:
    get:
      operationId: getSystemInformation
      summary: Get System Information
      description: >-
        Returns identifying information about this Bird city deployment —
        system_id, name, operator, language, timezone, license_url, and the
        rental_apps discovery / store URIs for iOS and Android.
      tags:
        - System
      responses:
        '200':
          description: System information payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemInformation'
  /vehicle_types.json:
    get:
      operationId: getVehicleTypes
      summary: List Vehicle Types
      description: >-
        Returns every vehicle type operating in this Bird city. Typical
        responses include an `electric` scooter (form_factor=scooter) and an
        `electric_assist` bicycle (form_factor=bicycle), each with a
        max_range_meters value.
      tags:
        - Vehicles
      responses:
        '200':
          description: Vehicle types payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VehicleTypes'
  /free_bike_status.json:
    get:
      operationId: getFreeBikeStatus
      summary: List Free-Floating Vehicles
      description: >-
        Returns the real-time list of available free-floating Bird vehicles
        in this city. Each entry includes bike_id, lat, lon, is_reserved,
        is_disabled, vehicle_type_id, and current_range_meters / battery
        information. Updated every 60 seconds.
      tags:
        - Vehicles
        - Realtime
      responses:
        '200':
          description: Free bike status payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FreeBikeStatus'
  /station_information.json:
    get:
      operationId: getStationInformation
      summary: List Station Information
      description: >-
        Returns any docking or hub stations defined for this Bird city. Most
        Bird markets are free-floating, so the stations array is often empty.
      tags:
        - Stations
      responses:
        '200':
          description: Station information payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StationInformation'
  /station_status.json:
    get:
      operationId: getStationStatus
      summary: Get Station Status
      description: >-
        Returns the real-time vehicle counts at each station defined in
        station_information.json. Free-floating Bird markets return an empty
        stations array.
      tags:
        - Stations
        - Realtime
      responses:
        '200':
          description: Station status payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StationStatus'
  /geofencing_zones.json:
    get:
      operationId: getGeofencingZones
      summary: Get Geofencing Zones
      description: >-
        Returns the GeoJSON FeatureCollection of no-ride, no-parking, and
        reduced-speed zones enforced by the Bird app for this city.
      tags:
        - Geofencing
      responses:
        '200':
          description: Geofencing zones payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeofencingZones'
  /system_pricing_plans.json:
    get:
      operationId: getSystemPricingPlans
      summary: List System Pricing Plans
      description: >-
        Returns the rider-facing pricing plans for this Bird city. Many
        Bird feeds return an empty plans array — pricing is set in-app and
        per-market.
      tags:
        - Pricing
      responses:
        '200':
          description: Pricing plans payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemPricingPlans'
  /system_regions.json:
    get:
      operationId: getSystemRegions
      summary: List System Regions
      description: Returns named regions / service-area subdivisions used by this Bird city deployment.
      tags:
        - System
      responses:
        '200':
          description: System regions payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemRegions'
components:
  schemas:
    GbfsEnvelope:
      type: object
      required: [version, data, last_updated, ttl]
      properties:
        version:
          type: string
          description: GBFS spec version (e.g. "2.3")
        last_updated:
          type: integer
          format: int64
          description: POSIX timestamp at which the data was last updated
        ttl:
          type: integer
          description: Seconds before the consumer should re-fetch this feed
        data:
          type: object
    GbfsDiscovery:
      allOf:
        - $ref: '#/components/schemas/GbfsEnvelope'
        - type: object
          properties:
            data:
              type: object
              additionalProperties:
                type: object
                properties:
                  feeds:
                    type: array
                    items:
                      type: object
                      required: [name, url]
                      properties:
                        name:
                          type: string
                        url:
                          type: string
                          format: uri
    GbfsVersions:
      allOf:
        - $ref: '#/components/schemas/GbfsEnvelope'
        - type: object
          properties:
            data:
              type: object
              properties:
                versions:
                  type: array
                  items:
                    type: object
                    required: [version, url]
                    properties:
                      version:
                        type: string
                      url:
                        type: string
                        format: uri
    SystemInformation:
      allOf:
        - $ref: '#/components/schemas/GbfsEnvelope'
        - type: object
          properties:
            data:
              type: object
              required: [system_id, name, language, timezone]
              properties:
                system_id:
                  type: string
                  example: bird-los-angeles
                name:
                  type: string
                operator:
                  type: string
                language:
                  type: string
                timezone:
                  type: string
                license_url:
                  type: string
                  format: uri
                rental_apps:
                  type: object
                  properties:
                    android:
                      $ref: '#/components/schemas/RentalApp'
                    ios:
                      $ref: '#/components/schemas/RentalApp'
    RentalApp:
      type: object
      properties:
        discovery_uri:
          type: string
        store_uri:
          type: string
          format: uri
    VehicleTypes:
      allOf:
        - $ref: '#/components/schemas/GbfsEnvelope'
        - type: object
          properties:
            data:
              type: object
              properties:
                vehicle_types:
                  type: array
                  items:
                    $ref: '#/components/schemas/VehicleType'
    VehicleType:
      type: object
      required: [vehicle_type_id, form_factor, propulsion_type]
      properties:
        vehicle_type_id:
          type: string
        form_factor:
          type: string
          enum: [scooter, bicycle, car, moped, other]
        propulsion_type:
          type: string
          enum: [human, electric_assist, electric, combustion, other]
        max_range_meters:
          type: number
    FreeBikeStatus:
      allOf:
        - $ref: '#/components/schemas/GbfsEnvelope'
        - type: object
          properties:
            data:
              type: object
              properties:
                bikes:
                  type: array
                  items:
                    $ref: '#/components/schemas/Vehicle'
    Vehicle:
      type: object
      required: [bike_id, lat, lon, is_reserved, is_disabled]
      properties:
        bike_id:
          type: string
          description: Anonymized rotating identifier for this vehicle
        lat:
          type: number
        lon:
          type: number
        is_reserved:
          type: boolean
        is_disabled:
          type: boolean
        vehicle_type_id:
          type: string
        current_range_meters:
          type: number
        last_reported:
          type: integer
          format: int64
    StationInformation:
      allOf:
        - $ref: '#/components/schemas/GbfsEnvelope'
        - type: object
          properties:
            data:
              type: object
              properties:
                stations:
                  type: array
                  items:
                    $ref: '#/components/schemas/Station'
    Station:
      type: object
      required: [station_id, name, lat, lon]
      properties:
        station_id:
          type: string
        name:
          type: string
        lat:
          type: number
        lon:
          type: number
        capacity:
          type: integer
    StationStatus:
      allOf:
        - $ref: '#/components/schemas/GbfsEnvelope'
        - type: object
          properties:
            data:
              type: object
              properties:
                stations:
                  type: array
                  items:
                    type: object
                    required: [station_id]
                    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
    GeofencingZones:
      allOf:
        - $ref: '#/components/schemas/GbfsEnvelope'
        - type: object
          properties:
            data:
              type: object
              properties:
                geofencing_zones:
                  type: object
                  description: GeoJSON FeatureCollection of geofence polygons
                  properties:
                    type:
                      type: string
                      enum: [FeatureCollection]
                    features:
                      type: array
                      items:
                        $ref: '#/components/schemas/GeofencingFeature'
    GeofencingFeature:
      type: object
      properties:
        type:
          type: string
          enum: [Feature]
        geometry:
          type: object
        properties:
          type: object
          properties:
            name:
              type: string
            start:
              type: integer
              format: int64
            end:
              type: integer
              format: int64
            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: number
    SystemPricingPlans:
      allOf:
        - $ref: '#/components/schemas/GbfsEnvelope'
        - type: object
          properties:
            data:
              type: object
              properties:
                plans:
                  type: array
                  items:
                    type: object
                    properties:
                      plan_id:
                        type: string
                      name:
                        type: string
                      currency:
                        type: string
                      price:
                        type: number
    SystemRegions:
      allOf:
        - $ref: '#/components/schemas/GbfsEnvelope'
        - type: object
          properties:
            data:
              type: object
              properties:
                regions:
                  type: array
                  items:
                    type: object
                    required: [region_id, name]
                    properties:
                      region_id:
                        type: string
                      name:
                        type: string
tags:
  - name: Discovery
    description: GBFS auto-discovery and version metadata
  - name: System
    description: System-level information and regions
  - name: Vehicles
    description: Vehicle inventory and real-time availability
  - name: Stations
    description: Docking-station information (mostly empty for free-floating Bird markets)
  - name: Geofencing
    description: No-ride / no-parking polygon zones
  - name: Pricing
    description: Rider-facing pricing plans
  - name: Realtime
    description: Real-time feeds with 60-second TTL