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: [email protected]
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