{"openapi":"3.1.0","info":{"title":"Bike Beacon Public Mobility API","version":"1.0.0-beta","description":"Read-only, coordinate-first D.C. e-bike availability and recommendation data. No rider, Calendar, phone, reminder, consent, or analytics data is exposed."},"servers":[{"url":"https://bikebeacon.app"}],"paths":{"/api/v1/nearby-ebikes":{"get":{"operationId":"findNearbyEbikes","summary":"Find fresh e-bike options near D.C. coordinates","description":"Returns fresh Capital Bikeshare station options and a deterministic recommendation. A missing recommendation is intentional when usable data cannot support one.","parameters":[{"name":"latitude","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"Starting-point latitude."},{"name":"longitude","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180},"description":"Starting-point longitude."},{"name":"label","in":"query","required":false,"schema":{"type":"string","maxLength":180},"description":"Optional transient display label. Do not send private addresses unless the user explicitly requests that lookup."},{"name":"radius","in":"query","required":false,"schema":{"type":"number","minimum":0.2,"maximum":3,"default":1.25},"description":"Search radius in miles."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":12,"default":8},"description":"Maximum station results."}],"responses":{"200":{"description":"A fresh or explicitly partial mobility result.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Short public freshness policy."},"X-Bike-Beacon-API-Version":{"schema":{"type":"string","const":"1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MobilityResult"}}}},"400":{"description":"Invalid coordinates or bounds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Current mobility data is unavailable or unusable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"options":{"operationId":"nearbyEbikesCors","responses":{"204":{"description":"CORS preflight."}}}}},"components":{"schemas":{"Station":{"type":"object","required":["kind","stationId","name","latitude","longitude","distanceMiles","ebikes","classicBikes","docks","lastReportedAt"],"properties":{"kind":{"type":"string","const":"station"},"stationId":{"type":"string"},"name":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"distanceMiles":{"type":"number"},"ebikes":{"type":["integer","null"],"minimum":0},"classicBikes":{"type":["integer","null"],"minimum":0},"docks":{"type":["integer","null"],"minimum":0},"lastReportedAt":{"type":"string","format":"date-time"}}},"Warning":{"type":"object","additionalProperties":true,"description":"Structured upstream-data warning. Consumers must not reinterpret a warning or missing count as zero."},"MobilityResult":{"type":"object","required":["location","radiusMiles","systemId","quality","observedAt","expiresAt","stations","parkedEbikeCount","parkedVehicles","recommendation","recommendationConfidence","warnings","parkedBikeStatus"],"properties":{"location":{"type":"object","required":["label","latitude","longitude"],"properties":{"label":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"}}},"radiusMiles":{"type":"number"},"systemId":{"type":"string","const":"dca-cabi"},"quality":{"type":"string","enum":["complete","station_partial","vehicle_partial"]},"observedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"stations":{"type":"array","items":{"$ref":"#/components/schemas/Station"}},"parkedEbikeCount":{"type":"integer","minimum":0},"parkedVehicles":{"type":"array","items":{"type":"object","additionalProperties":true}},"recommendation":{"type":"object","required":["bestStationId","closestParkedVehicleId"],"properties":{"bestStationId":{"type":["string","null"]},"closestParkedVehicleId":{"type":["string","null"]}}},"bestStationReason":{"type":["string","null"]},"recommendationConfidence":{"type":"object","required":["level","label","detail"],"properties":{"level":{"type":"string","enum":["strong","moderate","fragile","none","unknown"]},"label":{"type":"string"},"detail":{"type":"string"}}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Warning"}},"parkedBikeStatus":{"type":"string","enum":["available","shadow"]}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"externalDocs":{"description":"Bike Beacon developer notes","url":"https://bikebeacon.app/developers"}}