migrate a gbfs feed from v2.3 to v3.0 without breaking existing consumers

domain: gbfs.org · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Publish the new v3.0 feed set at a new path (e.g. /gbfs/3/) while keeping the existing v2.3 feed live at its current path, since GBFS versions are not interchangeable in place.
  2. Update gbfs_versions.json to list both a "2.3" and a "3.0" entry with their respective feed URLs, and add manifest.json if you publish more than one city/system.
  3. Convert renamed v3.0 fields: free_bike_status.json becomes vehicle_status.json, and bikes/bike_id/num_bikes_available/num_bikes_disabled become vehicles/vehicle_id/num_vehicles_available/num_vehicles_disabled.
  4. Reformat data types required by v3.0: timestamps to RFC3339 strings, enum values to lowercase, prices in system_pricing_plans.json to non-negative floats (not strings), and phone numbers to E.164.
  5. Populate the now-required feed_contact_email and a license_id or license_url in system_information.json, and add required opening_hours in OpenStreetMap format.
  6. Validate both feeds with the GBFS Validator before publishing, and plan to keep the v2.3 feed live for about a year per MobilityData's migration guidance.

Known gotchas

Related routes

handle non-standard or authenticated public gbfs feeds like veo's when building a multi-operator aggregator
veoride.com · 5 steps · unrated
Migrate an AWS SDK for JavaScript v2 integration to v3 before end of support
docs.aws.amazon.com · 5 steps · unrated
Validate a GBFS feed against the official schema before publishing or consuming it
gbfs-validator.mobilitydata.org · 5 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans