Trip updates

  1. Getting started
  2. Quotes
  3. Bookings
  4. Trip updates
  5. Settlements
  6. Testing

Trip updates

Endpoint: GET https://supply-partner.com/trip?trip_id=a96f4513-7846-4f9b-bb23-1d2f5247b493&external_trip_id=325486921

Supported URI Parameters

Description

trip_id

Karhoo's trip id

external_trip_id

The trip id you use to identify a booking. This is also visible to the passenger

external_fleet_id

The fleet id you use to identify a fleet on your platform

external_account_id

Used to specify an account with special SLAs or pricing

This is a DMS endpoint the Karhoo Platform polls for trip updates to track the driver, trip status and final fare.

The following example represents the bare minimum of trip tracking but does not offer the best passenger experience and can result in more passengers calling your main office for updates.

{
    "trip_id": "a96f4513-7846-4f9b-bb23-1d2f5247b493",
    "external_info": {
        "trip_id": "55555"
        "fleet_id": "12333"
    },
    "state": {
        "state": 3
    }
}

States Mapping

In the trip object above you see the state object with the state field. Here is a human-readable form of the states mappings:

  • "STATE_NOT_SET"
  • "NEW"
  • "REQUESTED"
  • "CONFIRMED"
  • "ALLOCATED"
  • "DRIVER_EN_ROUTE”
  • "APPROACHING"
  • "ARRIVED"
  • "PASSENGER_ON_BOARD"
  • "COMPLETED"
  • "CANCELLED_BY_USER"
  • "CANCELLED_BY_DISPATCH"
  • "CANCELLED_BY_KARHOO"

For cancelled trips we would like to also receive the cancellation reason as part of the state object:

"state": {
        "state": "CANCELLED_BY_DISPATCH",
        "cancellation_reason": "OTHER_DISPATCH_REASON",
    }

Cancellation reasons in human readable form:

  • "REASON_NOT_SET"
  • "OTHER_DISPATCH_REASON"
  • "REQUESTED_BY_PASSENGER"
  • "PASSENGER_DIDNT_SHOW_UP"
  • "DRIVER_CANCELED"
  • "FLEET_CANCELLED"
  • "DISPATCH_CANCELLED"
  • "NO_AVAILABILITY_IN_THE_AREA"
  • "NO_FEE"

Vehicle & Driver

Let’s say that trip time is coming and you already have a vehicle assigned. Minimal acceptable payload in this case is:

{
    "trip_id": "a96f4513-7846-4f9b-bb23-1d2f5247b493",
    "external_info": {
        "trip_id": "55555"
        "fleet_id": "12333"
    },
    "state": {
        "state":"ALLOCATED"
    },
    "vehicle": {
        "description": "BMW 5-series",
        "driver": {
           "first_name": "Aliaksandr",
           "phone_number": "+12121231234",
        },
    }
}

🚧

E.164 Formatted Phone Number

Please note that the driver phone number should adhere to the E.164 standard of formatting.

Default polling intervals

Karhoo will poll for updates on trip details with the following frequencies. These frequencies are a platform configuration option that can be discussed more by contacting the Karhoo team.

Conditions

Polling frequency

PRE-BOOK

greater than 3 hours before pickup time

1 hour

1 hour before pickup time

5 minutes

10 minutes before pickup time

30 seconds

Up to 5 minutes after pickup time

30 seconds

Up to 30 minutes after pickup time

1 minute

Up to 1 hour after pickup time

5 minutes

After 1 hour after pickup time

1 hour

ASAP

Default

5 seconds

ONCE COMPLETED

Less than 2 hours since polling started

15 hours

More than 28 hours since polling started

1 minute

Default

12 hours

Example response

{
  "trip_id": "a96f4513-7846-4f9b-bb23-1d2f5247b493",
  "external_info": {
    "fleet_id": "64",
    "fleet_phone_number": "+12121231234",
    "trip_id": "325486921",
    "quote_id": "99864597614",
    "vehicle_type": "R4",
    "fare_id": "2184XVYT23"
  },
  "date_scheduled": "2017-09-14T12:45:54.000Z",
  "date_scheduled_utc": 1505393154,
  "origin": {
    "position": {
      "latitude": 40.6413111,
      "longitude": -73.7781391
    },
    "address": {
      "display_address": "John F. Kennedy International Airport, New York, US",
      "building_number": "",
      "street_name": "",
      "city": "Queens",
      "region": "NY",
      "postal_code": "11430",
      "country_code": "US"
    },
    ,
    "airport": {
      "airport_code": "JFK",
      "flight_number": "B67015",
      "pickup_type": "MEET_AND_GREET"
    }
  },
  "destination": {
    "position": {
      "latitude": 40.7587711,
      "longitude": -73.9952016
    },
    "address": {
      "display_address": "407 W 42nd St New York, NY, 10036",
      "building_number": "407",
      "street_name": "W 42nd St",
      "city": "New York",
      "region": "NY",
      "postal_code": "10036",
      "country_code": "US"
    }
  },
  "state": {
    "state_change_details": "Driver 25 allocated 2 hours prior to pickup",
    "state": "ALLOCATED"
  },
  "vehicle": {
    "vehicle_class": "MPV",
    "vehicle_registration": "EVY2323",
    "position": {
      "latitude": 51.5086692,
      "longitude": -0.1375291
    },
    "direction": {
      "kph": 23,
      "heading": 45
    },
    "eta": {
      "distance": 160,
      "minutes": 5
    },
    "description": "Black Lincoln Town Car",
    "driver": {
      "first_name": "Kurt",
      "last_name": "Godel",
      "phone_number": "+12121231234",
      "photo_url": "https://raw.githubusercontent.com/encharm/Font-Awesome-SVG-PNG/master/black/png/22/user.png",
      "photo_content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAABlBMVEXMzMyWlpYU2uzLAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAACklEQVQImWNgAAAAAgAB9HFkpgAAAABJRU5ErkJggg==",
      "license_number": "E892321567"
    },
    "external_info": {
      "vehicle_type": "R4",
      "driver_id": "25",
      "vehicle_id": "404"
    }
  },
  "comment": "do not beep car horn please",
  "passenger_count": 1,
  "passengers": [
    {
      "first_name": "Kurt",
      "last_name": "Godel",
      "phone_number": "+12121231234"
    }
  ],
  "fare": {
    "id": "string",
    "type": "FIXED",
    "total": 3530,
    "currency": "USD",
    "breakdown": [
      {
        "name": "BASE_RATE",
        "value": 2330,
        "vat_percent": 10
      },
      {
        "name": "WAITING_TIME",
        "value": 500,
        "vat_percent": 10
      },
      {
        "name": "TOLLS",
        "value": 700,
        "vat_percent": 10
      }
    ]
  }
}

Trip cancellation

Endpoint: DELETE https://supply-partner.com/trip?trip_id=3413241&external_trip_id=2WEKaVNO

Karhoo’s trip_id and your trip id external_trip_id are passed in as query parameters.

If there are any cancellation charges, please respond with a fare object and its breakdown with the cancellation confirmation. The trip state should also be set as cancelled.

"fare": {
    "id": "string",
    "type": "FIXED",
    "total": 3530,
    "currency": "USD",
    "breakdown": [
        {
        "name": "BASE_RATE",
        "value": 2330,
        "vat_percent": 10
        },
        {
        "name": "WAITING_TIME",
        "value": 500,
        "vat_percent": 10
        },
        {
        "name": "CANCELLATION_FEE",
        "value": 700,
        "vat_percent": 10
        }
    ]
}

Reference

Service

API reference

Errors reference

Update Trips

Update Trip

Integration Errors

Trip Detaills

Provide Trip Details

Integration Errors

Troubleshooting

Some potential errors you might encounter are:

Error

Solution


What’s Next