The Lyft Ride-Sharing API provides developers with programmatic access to Lyft's rideshare platform. It includes endpoints for retrieving cost estimates between locations, estimating pickup ETAs, listing available ride types in a given area, and checking nearby driver availability. The API uses OAuth 2.0 for user-authenticated requests and client tokens for public endpoints.
openapi: 3.1.0
info:
title: Lyft Ride-Sharing API
description: >-
The Lyft Ride-Sharing API provides developers with programmatic access to
Lyft's rideshare platform. It includes endpoints for retrieving cost
estimates between locations, estimating pickup ETAs, listing available ride
types in a given area, and checking nearby driver availability. The API
uses OAuth 2.0 for user-authenticated requests and client tokens for
public endpoints. Developers can use it to integrate ride-hailing
functionality directly into their applications, enabling users to request,
track, and manage Lyft rides.
version: '1.0'
contact:
name: Lyft Developer Support
url: https://www.lyft.com/developers
termsOfService: https://www.lyft.com/terms
externalDocs:
description: Lyft API Documentation
url: https://developer.lyft.com/docs
servers:
- url: https://api.lyft.com/v1
description: Production Server
tags:
- name: Cost Estimates
description: >-
Endpoints for estimating the cost, distance, and duration of a ride
between two locations.
- name: Drivers
description: >-
Endpoints for checking the availability and proximity of nearby Lyft
drivers.
- name: ETA
description: >-
Endpoints for estimating the time for the nearest driver to reach a
specified pickup location.
- name: Profile
description: >-
Endpoints for retrieving profile information for the authenticated Lyft
user.
- name: Ride Types
description: >-
Endpoints for retrieving information about available Lyft ride types at a
given location, including pricing details and seat capacity.
- name: Rides
description: >-
Endpoints for requesting, tracking, canceling, and managing Lyft rides
on behalf of an authenticated user.
security:
- bearerAuth: []
paths:
/ridetypes:
get:
operationId: listRideTypes
summary: List ride types
description: >-
Returns information about what kinds of Lyft rides are available at a
given location. The response includes ride type identifiers, display
names, pricing details, image URLs, and passenger seat capacity.
tags:
- Ride Types
parameters:
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lng'
- name: ride_type
in: query
description: >-
A specific ride type to filter by. If provided, only the specified
ride type is returned.
required: false
schema:
$ref: '#/components/schemas/RideTypeEnum'
responses:
'200':
description: Successful response with available ride types
content:
application/json:
schema:
type: object
properties:
ride_types:
type: array
description: >-
List of available ride types at the specified location.
items:
$ref: '#/components/schemas/RideType'
'400':
description: Bad request - invalid or missing parameters
'401':
description: Unauthorized - invalid or missing access token
/eta:
get:
operationId: listETAs
summary: List pickup ETAs
description: >-
Returns the estimated time in seconds for the nearest driver to reach
the specified pickup location. ETAs can be filtered by ride type and
optionally account for a destination location to improve accuracy.
tags:
- ETA
parameters:
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lng'
- name: destination_lat
in: query
description: >-
Latitude of the destination location for improved ETA accuracy.
required: false
schema:
type: number
format: double
- name: destination_lng
in: query
description: >-
Longitude of the destination location for improved ETA accuracy.
required: false
schema:
type: number
format: double
- name: ride_type
in: query
description: >-
A specific ride type to filter ETA results by.
required: false
schema:
$ref: '#/components/schemas/RideTypeEnum'
responses:
'200':
description: Successful response with ETA estimates
content:
application/json:
schema:
type: object
properties:
eta_estimates:
type: array
description: >-
List of ETA estimates for each available ride type.
items:
$ref: '#/components/schemas/ETAEstimate'
'400':
description: Bad request - invalid or missing parameters
'401':
description: Unauthorized - invalid or missing access token
/cost:
get:
operationId: listCostEstimates
summary: List cost estimates
description: >-
Returns the estimated cost, distance, and duration of a ride between
a start and end location. Cost estimates are returned for all available
ride types unless a specific ride type filter is applied. Amounts are
returned in the smallest denomination of the applicable currency.
tags:
- Cost Estimates
parameters:
- name: start_lat
in: query
description: >-
Latitude of the starting location.
required: true
schema:
type: number
format: double
- name: start_lng
in: query
description: >-
Longitude of the starting location.
required: true
schema:
type: number
format: double
- name: end_lat
in: query
description: >-
Latitude of the destination location.
required: true
schema:
type: number
format: double
- name: end_lng
in: query
description: >-
Longitude of the destination location.
required: true
schema:
type: number
format: double
- name: ride_type
in: query
description: >-
A specific ride type to filter cost estimates by.
required: false
schema:
$ref: '#/components/schemas/RideTypeEnum'
responses:
'200':
description: Successful response with cost estimates
content:
application/json:
schema:
type: object
properties:
cost_estimates:
type: array
description: >-
List of cost estimates for each available ride type.
items:
$ref: '#/components/schemas/CostEstimate'
'400':
description: Bad request - invalid or missing parameters
'401':
description: Unauthorized - invalid or missing access token
/drivers:
get:
operationId: listNearbyDrivers
summary: List nearby drivers
description: >-
Returns the positions of nearby drivers for each ride type at the
specified location. This endpoint is useful for displaying driver
availability on a map.
tags:
- Drivers
parameters:
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lng'
responses:
'200':
description: Successful response with nearby driver locations
content:
application/json:
schema:
type: object
properties:
nearby_drivers:
type: array
description: >-
List of nearby driver groups organized by ride type.
items:
$ref: '#/components/schemas/NearbyDriversByRideType'
'400':
description: Bad request - invalid or missing parameters
'401':
description: Unauthorized - invalid or missing access token
/profile:
get:
operationId: getProfile
summary: Get user profile
description: >-
Returns the authenticated user's profile information including their
first name, last name, and whether the profile has been verified.
tags:
- Profile
parameters: []
responses:
'200':
description: Successful response with user profile information
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
'401':
description: Unauthorized - invalid or missing access token
/rides:
get:
operationId: listRides
summary: List rides
description: >-
Returns a list of past and current rides for the authenticated user.
Results can be filtered by start and end time.
tags:
- Rides
parameters:
- name: start_time
in: query
description: >-
Restrict results to rides starting after this point in time. The
value should be in ISO 8601 format.
required: true
schema:
type: string
format: date-time
- name: end_time
in: query
description: >-
Restrict results to rides starting before this point in time. The
value should be in ISO 8601 format.
required: false
schema:
type: string
format: date-time
- name: limit
in: query
description: >-
Maximum number of rides to return. Default is 10.
required: false
schema:
type: integer
minimum: 1
maximum: 50
default: 10
responses:
'200':
description: Successful response with ride history
content:
application/json:
schema:
type: object
properties:
ride_history:
type: array
description: >-
List of ride details for the authenticated user.
items:
$ref: '#/components/schemas/RideDetail'
'400':
description: Bad request - invalid or missing parameters
'401':
description: Unauthorized - invalid or missing access token
post:
operationId: createRide
summary: Request a ride
description: >-
Requests a new Lyft ride on behalf of the authenticated user. The
request must include a ride type and origin location. A destination
may optionally be specified at the time of request.
tags:
- Rides
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRideRequest'
responses:
'200':
description: Ride requested successfully
content:
application/json:
schema:
$ref: '#/components/schemas/RideDetail'
'400':
description: Bad request - invalid parameters
'401':
description: Unauthorized - invalid or missing access token
'404':
description: No drivers available
/rides/{id}:
get:
operationId: getRide
summary: Get ride detail
description: >-
Returns the details of a specific ride identified by its ride ID,
including status, origin, destination, driver information, and vehicle
details.
tags:
- Rides
parameters:
- $ref: '#/components/parameters/rideId'
responses:
'200':
description: Successful response with ride details
content:
application/json:
schema:
$ref: '#/components/schemas/RideDetail'
'401':
description: Unauthorized - invalid or missing access token
'404':
description: Ride not found
/rides/{id}/cancel:
post:
operationId: cancelRide
summary: Cancel a ride
description: >-
Cancels an ongoing or requested ride. If the ride has already been
matched with a driver, a cancellation fee may apply depending on how
long the driver has been en route.
tags:
- Rides
parameters:
- $ref: '#/components/parameters/rideId'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
cancel_confirmation_token:
type: string
description: >-
A token required to confirm the cancellation when a
cancellation fee applies.
responses:
'204':
description: Ride canceled successfully
'400':
description: Bad request - ride cannot be canceled
'401':
description: Unauthorized - invalid or missing access token
'404':
description: Ride not found
/rides/{id}/destination:
put:
operationId: updateRideDestination
summary: Update ride destination
description: >-
Updates the destination of an active ride. This can be used to change
or set the drop-off location while a ride is in progress.
tags:
- Rides
parameters:
- $ref: '#/components/parameters/rideId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- lat
- lng
properties:
lat:
type: number
format: double
description: >-
Latitude of the new destination location.
lng:
type: number
format: double
description: >-
Longitude of the new destination location.
address:
type: string
description: >-
Human-readable address of the new destination.
responses:
'200':
description: Destination updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Location'
'400':
description: Bad request - invalid parameters
'401':
description: Unauthorized - invalid or missing access token
'404':
description: Ride not found
/rides/{id}/rating:
put:
operationId: rateRide
summary: Rate a ride
description: >-
Submits the passenger's rating for a completed ride. The rating
includes a star score and optionally a tip amount and text feedback.
tags:
- Rides
parameters:
- $ref: '#/components/parameters/rideId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RideRatingRequest'
responses:
'200':
description: Rating submitted successfully
'400':
description: Bad request - invalid parameters
'401':
description: Unauthorized - invalid or missing access token
'404':
description: Ride not found
/rides/{id}/receipt:
get:
operationId: getRideReceipt
summary: Get ride receipt
description: >-
Returns the receipt for a completed ride, including fare breakdown,
charges, credits applied, and total cost.
tags:
- Rides
parameters:
- $ref: '#/components/parameters/rideId'
responses:
'200':
description: Successful response with ride receipt
content:
application/json:
schema:
$ref: '#/components/schemas/RideReceipt'
'401':
description: Unauthorized - invalid or missing access token
'404':
description: Ride not found
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
OAuth 2.0 access token. Use the 2-legged client credentials flow for
public endpoints (ETA, cost, ride types) or the 3-legged authorization
code flow for user-specific endpoints (rides, profile).
clientToken:
type: apiKey
in: header
name: Authorization
description: >-
Client token for accessing public endpoints without user
authorization. Passed as a Bearer token in the Authorization header.
parameters:
lat:
name: lat
in: query
description: >-
Latitude of the location.
required: true
schema:
type: number
format: double
lng:
name: lng
in: query
description: >-
Longitude of the location.
required: true
schema:
type: number
format: double
rideId:
name: id
in: path
description: >-
The unique identifier of the ride.
required: true
schema:
type: string
schemas:
RideTypeEnum:
type: string
description: >-
Identifier for the type of Lyft ride.
enum:
- lyft
- lyft_line
- lyft_plus
- lyft_premier
- lyft_lux
- lyft_luxsuv
RideType:
type: object
description: >-
Details about an available ride type at a given location, including
its name, pricing, and capacity.
properties:
ride_type:
$ref: '#/components/schemas/RideTypeEnum'
display_name:
type: string
description: >-
Human-readable name for the ride type.
seats:
type: integer
description: >-
Maximum number of passenger seats available for this ride type.
image_url:
type: string
format: uri
description: >-
URL to an image representing the ride type.
pricing_details:
$ref: '#/components/schemas/PricingDetails'
PricingDetails:
type: object
description: >-
Pricing breakdown for a ride type, including base charge, per-mile and
per-minute rates, minimum cost, and cancellation penalty. All monetary
amounts are in the smallest denomination of the currency (e.g., cents
for USD).
properties:
base_charge:
type: integer
description: >-
Base fare amount in the smallest currency denomination.
cost_per_mile:
type: integer
description: >-
Per-mile charge in the smallest currency denomination.
cost_per_minute:
type: integer
description: >-
Per-minute charge in the smallest currency denomination.
cost_minimum:
type: integer
description: >-
Minimum fare amount in the smallest currency denomination.
trust_and_service:
type: integer
description: >-
Trust and service fee in the smallest currency denomination.
cancel_penalty_amount:
type: integer
description: >-
Cancellation penalty amount in the smallest currency denomination.
currency:
type: string
description: >-
ISO 4217 currency code.
pattern: '^[A-Z]{3}$'
ETAEstimate:
type: object
description: >-
Estimated time of arrival for the nearest driver of a given ride type.
properties:
ride_type:
$ref: '#/components/schemas/RideTypeEnum'
display_name:
type: string
description: >-
Human-readable name for the ride type.
eta_seconds:
type: integer
description: >-
Estimated time of arrival in seconds for the nearest driver.
is_valid_estimate:
type: boolean
description: >-
Whether the estimate is considered valid based on current driver
availability.
CostEstimate:
type: object
description: >-
Estimated cost, distance, and duration for a ride between two
locations for a specific ride type.
properties:
ride_type:
$ref: '#/components/schemas/RideTypeEnum'
display_name:
type: string
description: >-
Human-readable name for the ride type.
currency:
type: string
description: >-
ISO 4217 currency code.
pattern: '^[A-Z]{3}$'
estimated_cost_cents_min:
type: integer
description: >-
Lower bound of the estimated cost in cents.
estimated_cost_cents_max:
type: integer
description: >-
Upper bound of the estimated cost in cents.
estimated_distance_miles:
type: number
format: double
description: >-
Estimated distance of the ride in miles.
estimated_duration_seconds:
type: integer
description: >-
Estimated duration of the ride in seconds.
primetime_percentage:
type: string
description: >-
Current Prime Time percentage applied to the cost estimate.
Formatted as a percentage string such as 25%.
primetime_confirmation_token:
type: string
description: >-
A token that must be included when requesting a ride during
Prime Time pricing.
NearbyDriversByRideType:
type: object
description: >-
Collection of nearby driver positions for a specific ride type.
properties:
ride_type:
$ref: '#/components/schemas/RideTypeEnum'
drivers:
type: array
description: >-
List of nearby drivers with their locations.
items:
$ref: '#/components/schemas/DriverLocation'
DriverLocation:
type: object
description: >-
Geographic location of a nearby driver.
properties:
locations:
type: array
description: >-
Recent location waypoints for the driver.
items:
type: object
properties:
lat:
type: number
format: double
description: >-
Latitude of the driver's position.
lng:
type: number
format: double
description: >-
Longitude of the driver's position.
Profile:
type: object
description: >-
Profile information for the authenticated Lyft user.
properties:
id:
type: string
description: >-
Unique identifier for the user.
first_name:
type: string
description: >-
The user's first name.
last_name:
type: string
description: >-
The user's last name.
has_taken_a_ride:
type: boolean
description: >-
Whether the user has completed at least one Lyft ride.
Location:
type: object
description: >-
A geographic location with optional address information.
properties:
lat:
type: number
format: double
description: >-
Latitude of the location.
lng:
type: number
format: double
description: >-
Longitude of the location.
address:
type: string
description: >-
Human-readable address of the location.
CreateRideRequest:
type: object
description: >-
Request body for creating a new Lyft ride.
required:
- ride_type
- origin
properties:
ride_type:
$ref: '#/components/schemas/RideTypeEnum'
origin:
$ref: '#/components/schemas/Location'
destination:
$ref: '#/components/schemas/Location'
primetime_confirmation_token:
type: string
description: >-
A token confirming the user has accepted Prime Time pricing.
Required when Prime Time is in effect.
RideDetail:
type: object
description: >-
Detailed information about a Lyft ride including its status, route,
driver, and vehicle information.
properties:
ride_id:
type: string
description: >-
Unique identifier for the ride.
ride_type:
$ref: '#/components/schemas/RideTypeEnum'
status:
type: string
description: >-
Current status of the ride.
enum:
- pending
- accepted
- arrived
- pickedUp
- droppedOff
- canceled
- unknown
origin:
$ref: '#/components/schemas/Location'
destination:
$ref: '#/components/schemas/Location'
pickup:
$ref: '#/components/schemas/Location'
dropoff:
$ref: '#/components/schemas/Location'
driver:
$ref: '#/components/schemas/Driver'
vehicle:
$ref: '#/components/schemas/Vehicle'
requested_at:
type: string
format: date-time
description: >-
Timestamp when the ride was requested.
generated_at:
type: string
format: date-time
description: >-
Timestamp when this ride detail object was generated.
price:
$ref: '#/components/schemas/Price'
Driver:
type: object
description: >-
Information about the driver assigned to a ride.
properties:
first_name:
type: string
description: >-
The driver's first name.
phone_number:
type: string
description: >-
The driver's contact phone number.
rating:
type: string
description: >-
The driver's average rating.
image_url:
type: string
format: uri
description: >-
URL to the driver's profile photo.
Vehicle:
type: object
description: >-
Information about the vehicle assigned to a ride.
properties:
make:
type: string
description: >-
Vehicle manufacturer name.
model:
type: string
description: >-
Vehicle model name.
year:
type: integer
description: >-
Vehicle model year.
license_plate:
type: string
description: >-
Vehicle license plate number.
license_plate_state:
type: string
description: >-
State where the vehicle is registered.
color:
type: string
description: >-
Color of the vehicle.
image_url:
type: string
format: uri
description: >-
URL to an image of the vehicle.
Price:
type: object
description: >-
Price information for a ride, including the total amount and currency.
properties:
amount:
type: integer
description: >-
Total price in the smallest denomination of the currency.
currency:
type: string
description: >-
ISO 4217 currency code.
pattern: '^[A-Z]{3}$'
description:
type: string
description: >-
Human-readable description of the price.
RideRatingRequest:
type: object
description: >-
Request body for rating a completed ride.
required:
- rating
properties:
rating:
type: integer
description: >-
Star rating for the ride, from 1 to 5.
minimum: 1
maximum: 5
tip:
type: object
description: >-
Optional tip for the driver.
properties:
amount:
type: integer
description: >-
Tip amount in the smallest denomination of the currency.
currency:
type: string
description: >-
ISO 4217 currency code for the tip.
pattern: '^[A-Z]{3}$'
feedback:
type: string
description: >-
Optional text feedback about the ride experience.
RideReceipt:
type: object
description: >-
Receipt for a completed ride, including fare breakdown and total
charges.
properties:
ride_id:
type: string
description: >-
Unique identifier for the ride.
price:
$ref: '#/components/schemas/Price'
line_items:
type: array
description: >-
Itemized list of charges that make up the total fare.
items:
$ref: '#/components/schemas/LineItem'
charges:
type: array
description: >-
List of payment charges applied to this ride.
items:
$ref: '#/components/schemas/Charge'
requested_at:
type: string
format: date-time
description: >-
Timestamp when the ride was requested.
LineItem:
type: object
description: >-
A single line item on a ride receipt representing a specific charge
or credit.
properties:
type:
type: string
description: >-
Type of the line item such as base fare, distance, time, or fees.
amount:
type: integer
description: >-
Amount of the line item in the smallest currency denomination.
currency:
type: string
description: >-
ISO 4217 currency code.
pattern: '^[A-Z]{3}$'
Charge:
type: object
description: >-
A payment charge applied to a ride.
properties:
amount:
type: integer
description: >-
Amount charged in the smallest currency denomination.
currency:
type: string
description: >-
ISO 4217 currency code.
pattern: '^[A-Z]{3}$'
payment_method:
type: string
description: >-
Description of the payment method used for this charge.