Trip updates

Getting started
Quotes
Bookings
Trip updates
Settlements
Testing

Trip updates

Endpoint: GET https://supply-partner.com/trip

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

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