{ "openapi": "3.1.0", "info": { "title": "RideWave Public API", "version": "1.2.0", "summary": "Read-only service, coverage and fare information for RideWave, a Denver black car service.", "description": "Public, unauthenticated, read-only endpoints describing where RideWave goes, what it drives and what it charges. No personal data is exposed and there is no booking endpoint: to book, send the rider to https://app.blackcarservice4u.com/book or to dispatch on (720) 877-4273. Every response is application/json, including every error. A client that sends Accept: application/problem+json receives the same error body with the RFC 9457 media type instead; the body always carries the RFC 9457 members (type, title, status, detail) alongside a nested error object with a machine-readable code, a human-readable message and a hint containing a working example URL. Fare figures returned by /quote are estimates from the published fare model; the exact fare is quoted on the booking page.\n\nVERSIONING. Integrate against the pinned base https://app.blackcarservice4u.com/api/v1. The unversioned base https://app.blackcarservice4u.com/api is an alias that always points at the newest stable version and returns identical responses today. Every response carries X-API-Version. Additive changes (a new endpoint, a new field) can land in v1 at any time; a change that removes or renames a field, or changes what a value means, gets a new version path. A version scheduled for retirement is announced with Deprecation and Sunset response headers (RFC 9745 and RFC 8594) at least 180 days ahead, and on https://app.blackcarservice4u.com/docs#versioning. No version is currently deprecated.\n\nRATE LIMITS. Two policies, both reported on every response via the RateLimit and RateLimit-Policy headers (the legacy RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset fields are sent alongside them): \"static\", 600 requests per 300 seconds, covers every endpoint except /fuel-nearby; \"fuel\", 30 requests per 600 seconds, covers /fuel-nearby and mirrors the limit of the upstream service it calls. A 429 carries Retry-After. Read the headers and self-throttle rather than retrying blind.", "termsOfService": "https://app.blackcarservice4u.com/terms", "contact": { "name": "RideWave dispatch", "url": "https://app.blackcarservice4u.com/docs", "email": "dispatch@blackcarservice4u.com" }, "license": { "name": "Data may be used to answer questions about RideWave and to refer riders to it.", "identifier": "LicenseRef-RideWave-Referral" } }, "servers": [ { "url": "https://app.blackcarservice4u.com/api/v1", "description": "Version 1. Pinned - integrate against this." }, { "url": "https://app.blackcarservice4u.com/api", "description": "Unversioned alias. Always the newest stable version." } ], "externalDocs": { "description": "Agent and developer docs", "url": "https://app.blackcarservice4u.com/docs" }, "security": [], "tags": [ { "name": "service", "description": "What RideWave offers and where." }, { "name": "pricing", "description": "The published fare model and estimates from it." }, { "name": "tools", "description": "Public tools RideWave operates." } ], "paths": { "/": { "get": { "operationId": "getApiIndex", "tags": [ "service" ], "summary": "API index", "description": "Lists every endpoint, the company record and a link to this specification.", "responses": { "200": { "description": "The API index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" } } }, "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/service-areas": { "get": { "operationId": "listServiceAreas", "tags": [ "service" ], "summary": "List every area RideWave serves", "responses": { "200": { "description": "The service areas.", "content": { "application/json": { "schema": { "type": "object", "required": [ "areas", "count" ], "properties": { "areas": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceArea" } }, "count": { "type": "integer" }, "booking_url": { "type": "string", "format": "uri" } } } } }, "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/fleet": { "get": { "operationId": "listFleet", "tags": [ "service" ], "summary": "List bookable vehicles", "responses": { "200": { "description": "The fleet.", "content": { "application/json": { "schema": { "type": "object", "required": [ "vehicles", "count" ], "properties": { "vehicles": { "type": "array", "items": { "$ref": "#/components/schemas/Vehicle" } }, "count": { "type": "integer" }, "booking_url": { "type": "string", "format": "uri" } } } } }, "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/fares": { "get": { "operationId": "getFares", "tags": [ "pricing" ], "summary": "The published fare model", "description": "Flat fares with no surge pricing. Returns the base fare, per-mile rate, airport surcharge, long-distance surcharge and hourly charter rates.", "responses": { "200": { "description": "The fare model.", "content": { "application/json": { "schema": { "type": "object", "required": [ "fares" ], "properties": { "fares": { "$ref": "#/components/schemas/Fares" }, "notes": { "type": "array", "items": { "type": "string" } }, "booking_url": { "type": "string", "format": "uri" } } } } }, "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/quote": { "get": { "operationId": "getQuote", "tags": [ "pricing" ], "summary": "Estimate a fare", "description": "Pass `miles` (with optional `airport=true`) for a point-to-point estimate, or `hours` for an hourly charter estimate. The result is an estimate from the published fare model, not a booking, and not a binding price.", "parameters": [ { "name": "miles", "in": "query", "required": false, "description": "Trip distance in miles. Required unless `hours` is given.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "example": 24.5 }, { "name": "airport", "in": "query", "required": false, "description": "Set true when the trip starts or ends at Denver International Airport, which adds the airport surcharge.", "schema": { "type": "boolean", "default": false } }, { "name": "hours", "in": "query", "required": false, "description": "Whole hours for an hourly charter, 1 to 12. Mutually exclusive with `miles`; when present it wins.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 3 } ], "responses": { "200": { "description": "A fare estimate.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PointToPointQuote" }, { "$ref": "#/components/schemas/HourlyQuote" } ] } } }, "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" } } }, "400": { "$ref": "#/components/responses/InvalidParameter" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/coverage": { "get": { "operationId": "checkCoverage", "tags": [ "service" ], "summary": "Check whether a place is in the service area", "description": "Matches a place name against the named service areas. `covered` is null when the place is not recognised, which is not a refusal: RideWave also takes custom and long-distance trips by request.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "A place name, neighbourhood or landmark. Up to 200 characters.", "schema": { "type": "string", "maxLength": 200 }, "example": "Boulder" } ], "responses": { "200": { "description": "The coverage answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coverage" } } }, "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" } } }, "400": { "$ref": "#/components/responses/InvalidParameter" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/fuel-nearby": { "get": { "operationId": "getFuelNearby", "tags": [ "tools" ], "summary": "Denver-area fuel prices near a point", "description": "RideWave operates a free public fuel-price finder. Results are cached and community-reported; repeated identical lookups return the same cached answer and are rate limited per address.", "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 39.8367 }, { "name": "lng", "in": "query", "required": true, "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": -105.0372 }, { "name": "miles", "in": "query", "required": false, "description": "Search radius, 1 to 25. Defaults to 7.", "schema": { "type": "number", "minimum": 1, "maximum": 25, "default": 7 } } ], "responses": { "200": { "description": "Fuel prices near the point.", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "miles": { "type": "number" } } }, "source": { "type": "string" }, "human_url": { "type": "string", "format": "uri" }, "result": { "type": "object", "description": "The upstream fuel finder payload." } } } } }, "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" } } }, "400": { "$ref": "#/components/responses/InvalidParameter" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } } }, "components": { "schemas": { "Error": { "type": "object", "description": "Every failure on this API returns this shape as application/json. It carries both a nested `error` object and the RFC 9457 problem-details members, so either style of client can read it.", "required": [ "error", "status", "title", "detail" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "status" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code.", "enum": [ "invalid_parameter", "not_found", "method_not_allowed", "not_acceptable", "rate_limited", "internal_error", "upstream_error" ] }, "message": { "type": "string", "description": "What went wrong, in one sentence." }, "hint": { "type": [ "string", "null" ], "description": "How to fix it, usually with a working example URL." }, "status": { "type": "integer" }, "documentation_url": { "type": "string", "format": "uri" } } }, "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "examples": [ { "error": { "code": "invalid_parameter", "message": "miles must be a positive number no greater than 1000, or pass hours for an hourly charter.", "hint": "Example: https://app.blackcarservice4u.com/api/v1/quote?miles=24.5&airport=true", "status": 400, "documentation_url": "https://app.blackcarservice4u.com/docs" }, "type": "https://app.blackcarservice4u.com/docs#errors", "title": "invalid_parameter", "status": 400, "detail": "miles must be a positive number no greater than 1000, or pass hours for an hourly charter." } ] }, "ApiIndex": { "type": "object", "properties": { "service": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "openapi": { "type": "string", "format": "uri" }, "documentation": { "type": "string", "format": "uri" }, "company": { "$ref": "#/components/schemas/Company" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "summary": { "type": "string" } } } } } }, "Company": { "type": "object", "properties": { "name": { "type": "string" }, "legal_name": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "country": { "type": "string" }, "license": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email" }, "booking_url": { "type": "string", "format": "uri" }, "website": { "type": "string", "format": "uri" } } }, "ServiceArea": { "type": "object", "required": [ "id", "name", "includes" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "includes": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" } } }, "Vehicle": { "type": "object", "required": [ "id", "name", "max_passengers" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "max_passengers": { "type": "integer" }, "luggage": { "type": "string" }, "image": { "type": "string", "format": "uri" } } }, "Fares": { "type": "object", "properties": { "currency": { "type": "string", "examples": [ "USD" ] }, "surge_pricing": { "type": "boolean", "examples": [ false ] }, "point_to_point": { "type": "object", "properties": { "base_fare": { "type": "number" }, "per_mile": { "type": "number" }, "airport_surcharge": { "type": "number" }, "long_distance": { "type": "object", "properties": { "applies_after_miles": { "type": "number" }, "per_additional_mile": { "type": "number" } } } } }, "hourly": { "type": "object", "properties": { "first_hour": { "type": "number" }, "each_additional_hour": { "type": "number" }, "min_hours": { "type": "integer" }, "max_hours": { "type": "integer" } } } } }, "PointToPointQuote": { "type": "object", "required": [ "mode", "miles", "breakdown", "estimate" ], "properties": { "mode": { "type": "string", "const": "point_to_point" }, "miles": { "type": "number" }, "airport": { "type": "boolean" }, "currency": { "type": "string" }, "vehicle": { "type": "string" }, "breakdown": { "type": "object", "properties": { "base_fare": { "type": "number" }, "distance_charge": { "type": "number" }, "airport_surcharge": { "type": "number" }, "long_distance_surcharge": { "type": "number" }, "total": { "type": "number" } } }, "estimate": { "type": "boolean", "const": true }, "disclaimer": { "type": "string" }, "booking_url": { "type": "string", "format": "uri" } } }, "HourlyQuote": { "type": "object", "required": [ "mode", "hours", "breakdown", "estimate" ], "properties": { "mode": { "type": "string", "const": "hourly" }, "hours": { "type": "integer" }, "currency": { "type": "string" }, "breakdown": { "type": "object", "properties": { "first_hour": { "type": "number" }, "additional_hours": { "type": "integer" }, "additional_hours_charge": { "type": "number" }, "total": { "type": "number" } } }, "estimate": { "type": "boolean", "const": true }, "disclaimer": { "type": "string" }, "booking_url": { "type": "string", "format": "uri" } } }, "Coverage": { "type": "object", "required": [ "query", "covered", "confidence" ], "properties": { "query": { "type": "string" }, "covered": { "type": [ "boolean", "null" ], "description": "true when the place matches a named service area; null when unrecognised, which is not a refusal." }, "match": { "type": [ "string", "null" ] }, "area": { "type": [ "string", "null" ] }, "confidence": { "type": "string", "enum": [ "high", "unknown" ] }, "note": { "type": "string" }, "booking_url": { "type": "string", "format": "uri" }, "dispatch_phone": { "type": "string" } } } }, "responses": { "InvalidParameter": { "description": "A query parameter was missing or out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MethodNotAllowed": { "description": "The API is read-only; only GET, HEAD and OPTIONS are supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotAcceptable": { "description": "The Accept header excluded application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests from this address. Retry-After gives the wait in seconds; the RateLimit headers give the policy and remaining quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" }, "example": 287 } } }, "InternalError": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UpstreamError": { "description": "A service this endpoint depends on failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "headers": { "RateLimit": { "description": "Current standing under the policy that applies to this endpoint.", "schema": { "type": "string" }, "example": "\"static\";r=598;t=287" }, "RateLimit-Policy": { "description": "The policy in force: quota per window in seconds.", "schema": { "type": "string" }, "example": "\"static\";q=600;w=300" }, "RateLimit-Limit": { "description": "Legacy quota field.", "schema": { "type": "integer" }, "example": 600 }, "RateLimit-Remaining": { "description": "Legacy remaining field.", "schema": { "type": "integer" }, "example": 598 }, "RateLimit-Reset": { "description": "Legacy reset field: seconds until the window rolls over.", "schema": { "type": "integer" }, "example": 287 }, "X-API-Version": { "description": "The API version that served this response.", "schema": { "type": "string" }, "example": "1" } } } }