{"openapi":"3.1.0","info":{"title":"CityBikes Public API (Citybik.es) - OpenAPI 3.1","description":"Official CityBikes (citybik.es) public API. Provides real-time bike-share networks, stations, vehicles and GBFS feeds.\n\nAuthentication: Most endpoints are public and do not require an API key. CityBikes enforces a default rate limit of 300 requests per hour on the public API. If you need more requests, contact info@citybik.es to request an API key. If you receive an API key, include it as an HTTP header named `x-api-key` on requests.\n\nHow to obtain an API key: Email info@citybik.es with project details and requested limits. When you receive a key, set header `x-api-key: <your-key>`.\n\nRate limit headers (present on responses): `x-ratelimit-limit-hour`, `x-ratelimit-remaining-hour`, `ratelimit-reset`, `ratelimit-limit`, `ratelimit-remaining`.","version":"v2"},"servers":[{"url":"https://api.onestop.sh/v1/invoke/one-stop/worldwide-bike-share-stations-city-bikes"}],"security":[{"oneStopApiKey":[]}],"components":{"securitySchemes":{"oneStopApiKey":{"type":"http","scheme":"bearer"}}},"paths":{"/v2/networks":{"get":{"operationId":"getNetworks","summary":"List all bike-share networks","description":"Returns a list of available bike-share networks with basic metadata (id, name, location, company and href to the network resource). Supports limiting returned fields with the `fields` query parameter.\n\nRate limit: 300 requests/hour by default. Optional `x-api-key` header may be used if you have an API key (contact info@citybik.es).","parameters":[{"name":"fields","in":"query","description":"Comma-separated list of top-level fields to include for each network (e.g. `id,name,href`). Field filtering currently applies to the first document and top-level fields.","required":false,"style":"form","explode":true,"schema":{"type":"string","example":"id,name,href"}}],"responses":{"200":{"description":"Successful response with networks array.","content":{"application/json":{"schema":{"type":"object","properties":{"networks":{"type":"array","items":{"type":"object","properties":{"company":{"type":"string"},"href":{"type":"string","description":"Relative API href for the network (prefix with /v2/networks/...)."},"location":{"type":"object","properties":{"latitude":{"type":"number","format":"float"},"longitude":{"type":"number","format":"float"},"city":{"type":"string"},"country":{"type":"string"}}},"name":{"type":"string"},"id":{"type":"string"}},"required":["id","name","href"]}}},"required":["networks"]}}}},"400":{"description":"Bad request — invalid query parameter (e.g. malformed fields).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Too many requests — rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v2/networks/{network_id}":{"get":{"operationId":"getNetwork","summary":"Get a single network's information (optionally include stations/vehicles)","description":"Returns detail about a network identified by {network_id}. The response includes network metadata and, when available, `stations` and `vehicles`. Use the `fields` query parameter to selectively return fields (e.g. `?fields=stations` to include stations). Timestamps are UTC.\n\nExample network IDs: velib, divvy, bicing, citi-bike-nyc.\n\nNote: station objects include `id`, `name`, `latitude`, `longitude`, `timestamp`, `free_bikes`, `empty_slots`, and an `extra` object with additional network-specific fields.","parameters":[{"name":"network_id","in":"path","description":"The CityBikes network id (case-sensitive). Examples: `velib`, `divvy`, `bicing`, `citi-bike-nyc`.","required":true,"style":"simple","explode":false,"schema":{"type":"string","example":"velib"}},{"name":"fields","in":"query","description":"Comma-separated list of top-level fields to include in the response (e.g. `stations`, `vehicles`).","required":false,"style":"form","explode":true,"schema":{"type":"string","example":"stations"}}],"responses":{"200":{"description":"Network details returned successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"network":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"location":{"type":"object","properties":{"latitude":{"type":"number","format":"float"},"longitude":{"type":"number","format":"float"},"city":{"type":"string"},"country":{"type":"string"}}},"href":{"type":"string"},"company":{"type":"array","items":{"type":"string"}},"gbfs_href":{"type":"string","description":"URL to the network GBFS manifest (when available)."},"ebikes":{"type":"boolean"},"stations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"latitude":{"type":"number","format":"float"},"longitude":{"type":"number","format":"float"},"timestamp":{"type":"string","format":"date-time"},"free_bikes":{"type":"integer"},"empty_slots":{"type":"integer"},"extra":{"type":"object","description":"Network-specific extra fields (uid, renting, returning, last_updated, has_ebikes, ebikes, payment, payment-terminal, slots, rental_uris, etc.)"}}}},"vehicles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"latitude":{"type":"number","format":"float"},"longitude":{"type":"number","format":"float"},"timestamp":{"type":"string","format":"date-time"},"extra":{"type":"object"},"kind":{"type":"string","description":"Vehicle type: bike, ebike, scooter"}}}}},"required":["id","name","location","href"]}},"required":["network"]}}}},"400":{"description":"Bad request - invalid network id format or query parameter.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthorized - provided x-api-key is invalid (only applies if API key required for your account).","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Network not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Too many requests — rate limit exceeded.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/gbfs/{major}/{network_id}/gbfs.json":{"get":{"operationId":"getGbfsDiscovery","summary":"GBFS discovery feed (gbfs.json) for a network and GBFS major version","description":"Discovery endpoint for a network's GBFS feeds. Returns available feeds and their urls. URL structure: /gbfs/{major}/{network_id}/gbfs.json. Major is the GBFS major version you support (e.g. 2 or 3).\n\nExamples of network ids: bicing, velib, citi-bike-nyc, divvy.\n\nSee GBFS docs for feed semantics. CityBikes supports GBFS v2.3 and v3.0 feeds (depending on network).","parameters":[{"name":"major","in":"path","description":"GBFS major version (use 2 or 3).","required":true,"style":"simple","explode":false,"schema":{"type":"integer","enum":[2,3],"example":2}},{"name":"network_id","in":"path","description":"CityBikes network id (e.g. `bicing`, `velib`, `citi-bike-nyc`).","required":true,"style":"simple","explode":false,"schema":{"type":"string","example":"bicing"}}],"responses":{"200":{"description":"GBFS discovery response with data.en.feeds array.","content":{"application/json":{"schema":{"type":"object","properties":{"last_updated":{"type":"integer"},"ttl":{"type":"integer"},"version":{"type":"string"},"data":{"type":"object","properties":{"en":{"type":"object","properties":{"feeds":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}}}}}}}}},"404":{"description":"Network or GBFS version not found for the given network_id/major combination.","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Too many requests — rate limit exceeded.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/gbfs/{major}/{network_id}/gbfs_versions.json":{"get":{"operationId":"getGbfsVersions","summary":"List available GBFS versions for a network (gbfs_versions.json)","description":"Returns the GBFS versions available for a given network (example response contains entries like 2.3 and 3.0).","parameters":[{"name":"major","in":"path","description":"GBFS major version.","required":true,"style":"simple","explode":false,"schema":{"type":"integer","enum":[2,3],"example":2}},{"name":"network_id","in":"path","description":"CityBikes network id.","required":true,"style":"simple","explode":false,"schema":{"type":"string","example":"bicing"}}],"responses":{"200":{"description":"GBFS versions for the network.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found."}}}},"/gbfs/{major}/{network_id}/system_information.json":{"get":{"operationId":"getGbfsSystemInformation","summary":"GBFS system_information.json - general info about the system","description":"Returns system-level information such as system_id, language, name, short_name, operator, feed_contact_email and timezone. Timestamps are UTC and timezone is set to `Etc/UTC` by CityBikes.","parameters":[{"name":"major","in":"path","required":true,"style":"simple","explode":false,"schema":{"type":"integer","example":2}},{"name":"network_id","in":"path","required":true,"style":"simple","explode":false,"schema":{"type":"string","example":"bicing"}}],"responses":{"200":{"description":"System information returned.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found."}}}},"/gbfs/{major}/{network_id}/vehicle_types.json":{"get":{"operationId":"getGbfsVehicleTypes","summary":"GBFS vehicle_types.json - vehicle types supported by a network","description":"Returns the vehicle types supported by the network (custom CityBikes extension).","parameters":[{"name":"major","in":"path","required":true,"style":"simple","explode":false,"schema":{"type":"integer","example":2}},{"name":"network_id","in":"path","required":true,"style":"simple","explode":false,"schema":{"type":"string","example":"bicing"}}],"responses":{"200":{"description":"Vehicle types returned.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found."}}}},"/gbfs/{major}/{network_id}/station_information.json":{"get":{"operationId":"getGbfsStationInformation","summary":"GBFS station_information.json - static station information","description":"Returns station metadata (id, name, lat, lon, etc.) without status. Use station_status.json for dynamic availability.","parameters":[{"name":"major","in":"path","required":true,"style":"simple","explode":false,"schema":{"type":"integer","example":2}},{"name":"network_id","in":"path","required":true,"style":"simple","explode":false,"schema":{"type":"string","example":"bicing"}}],"responses":{"200":{"description":"Station information returned.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found."}}}},"/gbfs/{major}/{network_id}/station_status.json":{"get":{"operationId":"getGbfsStationStatus","summary":"GBFS station_status.json - dynamic station availability","description":"Returns dynamic availability for stations: num_bikes_available, num_docks_available, vehicle_types_available, is_installed, is_renting, is_returning, last_reported (UNIX timestamp).","parameters":[{"name":"major","in":"path","required":true,"style":"simple","explode":false,"schema":{"type":"integer","example":2}},{"name":"network_id","in":"path","required":true,"style":"simple","explode":false,"schema":{"type":"string","example":"bicing"}}],"responses":{"200":{"description":"Station status returned.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found."}}}},"/gbfs/{major}/{network_id}/free_bike_status.json":{"get":{"operationId":"getGbfsFreeBikeStatus","summary":"GBFS free_bike_status.json - free roaming vehicles","description":"Returns free-roaming bikes / vehicles not associated with stations. Contains an array of bikes with location and id. Useful for dockless systems.","parameters":[{"name":"major","in":"path","required":true,"style":"simple","explode":false,"schema":{"type":"integer","example":2}},{"name":"network_id","in":"path","required":true,"style":"simple","explode":false,"schema":{"type":"string","example":"divvy"}}],"responses":{"200":{"description":"Free bike status returned.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found."}}}}}}