Cab Ride Booking


POST /v1.5/bookings/create

Allow users on your app to book an Ola ride of their choice. Just ensure their Ola account is linked through OAuth authentication. Once ride is booked and cab is allotted to the booking, the below information is made available:

  • Driver name, number and other details
  • Vehicle details
  • Estimated time of arrival to pick-up location
  • OTP to start the trip
  • Link to share ride details with friends/family

Request Parameters

Name Data Type Description Type Remark
pickup_lat float Latitude of the pickup location Payload Mandatory
pickup_lng float Longitude of the pickup location Payload Mandatory
category string

Ride category

  • micro
  • mini
  • share
  • prime
  • suv
  • prime_play
  • lux
  • rental
  • outstation
  • sedan
Payload

Mandatory

drop_lat float Latitude of the drop location Payload Optional (Mandatory if upfront pricing applicable)
drop_lng float Longitude of the drop location Payload Optional (Mandatory if upfront pricing applicable)
pickup_mode string Time of pickup [now, later] Payload Mandatory
payment_instrument_type string Mode of payment [cash, ola_money] Payload Optional (Ola Money balance will be default)
fare_id string Reference ID sent in ride estimate to lock upfront price Payload Optional (Mandatory if upfront pricing applicable)
affiliate_uid string User-ID on your platform Payload Optional
coupon_code string Partner-specific offer code Payload Optional
X-APP-TOKEN string Unique key for the partner Header Mandatory
Authorization string Unique key for the user (to be passed as Bearer token) Header Mandatory
  • Create Booking

    Once user selects category of choice and confirms for the ride to be booked, the API for booking creation can be called. If the request is correct, a booking id is first generated and sent in the response. The system then starts searching for nearby cabs to be allotted to the booking. There are two possibilities:

    • Successful allotment of cab and driver
    • Stockout due to non-availability of cabs

    Example Request

    POST

    https://devapi.olacabs.com/v1.5/bookings/create

    
    {
    "drop_lat":"12.9592",
    "drop_lng":"77.6974",
    "pickup_lat":"12.9523",
    "pickup_lng":"77.6432",
    "category": "mini",
    "pickup_mode":"now"
    "payment_instrument_type":"cash",
    "fare_id": "1:000008:50002738-7242-4728-9644-0ae0d6fceb01",
    "coupon_code": "DISC50"
    "affiliate_uid": "shfjh3342"
    }
    
    Headers: {
    authorization: Bearer 9b16121212f12ff12f12f1f12f1f12f2
    x-app-token: fd5d4d3726121212f12ff12f12f1f12f1f12fa
    }
    

    Example Response (Success)

    
    {
     "status": "SUCCESS",
     "booking_id": "CRN123456789",
     "message": "Searching for a cab.",
     "booking_timeout": 70,   // time post which driver allocation will no longer happen
     "booking_timeout_unit": "SECONDS"
    }
    

    Once success is received in the response, keep polling Track Ride API (Link) to get driver allotment status. The response will show ‘booking_status’ as one of the following:

    • ALLOTMENT_PENDING: System is still searching for cabs to be allotted
    • CALL_DRIVER: System has allotted a cab (Response will also contain cab/driver details)
    • ALLOTMENT_FAILED: System could not locate any cab nearby

    When the status is allotment pending, the users on your app can be shown a loading screen. On successful allotment, the cab/driver/otp details can be displayed on the screen. In case of no allotment, the same can be conveyed to the users asking them to try booking again.

    Example Responses (Failures)

    • Car category parameter sent is not valid

      
      {
          "message": "BOOKING_FAILED",
          "code": "INVALID_CAR_CATEGORY"
      }
      
      
    • Pickup lat-lng are in a city where Ola is not available

      
      {
          "message": "BOOKING_FAILED",
          "code": "INVALID_CITY"
      }
      
    • Pickup and Drop lat-lng sent are the same

      
      {
          "status": "FAILURE",
          "code": "SAME_PICKUP_DROP",
          "message": "Pickup and drop locations cannot be the same."
      }
      
    • User’s Ola account is in banned or deactivated state

      
      {
         "status": "FAILURE",
         "code": "BANNED USER",
         "message": "Your account has been suspended due to violation of Ola policies. Please contact our customer care."
      }
      
    • User’s Ola account is in banned or deactivated state

      
      {
          "status": "FAILURE",
          "code": "OUTSTANDING_DUE" or “PAYMENT_PENDING” or “OLA_CREDIT_DUE”
          "message": "Please clear the amount due for previous ride(s). Update your app if you don't see your payment options."
      }
      
    • Pickup and Drop lat-lng are in different cities

      
      {
        "status": "FAILURE",
        "code": "INVALID_DROP_LOCATION",
        "message": "Please enter a drop location within your city"
      }
      

  • Abort Booking

    When the system is searching for cabs, user can choose to abort the process of driver allotment. In that case, the abort booking API can be called by sending the ‘booking_id’ provided in the create booking API response. If a driver has already been allotted, abort will not work and it will throw a failure.


    Example Request

    POST

    https://devapi.olacabs.com/v1/bookings/abort

    
     {
    "booking_id":"CRN123456789"
    }
                
    Headers: {
    Authorization: Bearer 9b6121212f12ff12f12f1f12f1f12f2
    x-app-token: fd6121212f12ff12f12f1f12f1f12fa
    }

    Example Request(Success)

    
    {
     "status": "SUCCESS",
     "message": "Booking Cancelled Successfully",
     "code": "SUCCESS"
    }
    

    Example Request(Failure)

    
    {
      "status": "FAILURE",
      "message": "You can track your ride in a moment.",
      "code": "BOOKING_ALLOTED"
    }
    

    Once success is received in Abort Booking API, calling Track Ride API sends booking_status as ‘BOOKING_CANCELLED’ in the response.

  • Important Guidelines

    • You can send booking create request even for categories which are not available as per ride availability response. It is possible that a cab becomes available during the time system is searching for a cab to allotted to the booking
    • Receiving ‘success’ in booking create response and generation of booking_id does not guarantee that user will receive a cab. You need to display booking information to the user only when the cab/driver details are available in the Track Ride API (Link) response
    • If booking request is made and response is not received due to timeouts or network failures, call My Rides API (Link) to check if any booking is in active state after few seconds
    • Drop location is mandatory for Micro and Auto bookings





Update Drop Location


POST /v1/bookings/drop_location

Update drop location after a booking has been created.


Request Parameters

Name Data Type Description Type
drop_lat float The latitude of the drop location. Payload
drop_lng float The longitude of the drop location. Payload
booking_id string Booking ID for the ride Payload
Authorization string OAuth token(OAuth access token must be passed as Authorization header with Bearer token.) Header
X-APP-TOKEN string Key which identifies the partner Header
Content-Type string "application/json" to be passed Header

Example Request

POST

https://devapi.olacabs.com/v1/bookings/drop_location


  "body": {
    "drop_lat": 12.972934,
    "drop_lng": 77.722302,
    "booking_id": "CRN123456789"
  }

  "headers": {
    "Authorization": "Bearer b6121212f12ff12f12f1f12f1f12fbf",
    "X-APP-TOKEN": "6a56121212f12ff12f12f1f12f1f12fc",
    "Content-Type": "application/json"
  }

Example Response


{
  "status": "SUCCESS",
  "request_type": "Update User Booking Drop Location"
  "header": "SUCCESS",
  "text": "Drop Location Updated"
}

Failure Responses


Failure response in case of updating the drop location to a different city.


{
  "status": "FAILURE",
  "request_type": "Update User Booking Drop Location",
  "header": "Invalid Drop Location",
  "text": "Please enter a drop location within your city"
} 

Failure response in case of updating drop location of a completed ride.


{
  "status": "FAILURE",
  "request_type": "Update User Booking Drop Location",
  "header": "Oops!",
  "text": "Sorry, the ride is already completed or cancelled!"
}