Drivr API

The Drivr API provides the ability to create and retrieve required information in order to book taxis globally.

Introduction

Every URL is in the format https://api.drivr.com/:resource[/:action[?:params]] such as https://api.drivr.com/places/nearby to get a list of nearby places.

Every request must include a User-Agent header with your application name and an url or email address. We need this for tracking purposes and we might contact you in case this information isn't probably filled out. An example of a good header would be FooBooking-Version5 (http://foo-bookings.com/). Requests without this header might get a 400 Bad Request in future versions of the API.

The Accept header specifies which format to return. Only application/json is supported.

Returned format may be overridden by appending a format parameter to a request e.g. https://api.drivr.com/companies?format=json.

Clients must include an Accept header with a custom Drivr mime type to specify which version of the API to use e.g.

application/vnd.drivr[.version]+[type]

If this header isn't specified the latest API version is used but it's highly recommended to specific a specific version since future revisions might not be fully backward compatible.

Currently supported is v1, v2 and latest for version and json for type.

Responses will be compressed if request includes an Accept-Encoding header with a gzip value.

All timestamps are represented as ISO 8601 format YYYY-MM-DDTHH:MM:SSZ.

All IDs are represented as strings and should be stored and treated as strings. The format might change across API versions without notice.

Example requests are constructed using cURL commands.

Suggested booking flow

As as minimum requirement to book a taxi, one must first acquire an access token with provided credentials to get an access token. This access token must be used for all future requests.

Second step is to create a client and finally create a booking.

Usually one would also like to display which companies operate in a given area and check if that company requires a dropoff address and allows automated bookings. To check if company supports automated bookings the automatedBooking attribute on a company should be checked. If this is false our API cannot automatically book a taxi on i.e. trying to place a booking will fail but you may use returned phone number to display this as a fallback in your application flow. Most companies on our platform allows automatic booking, though.

Checking if a company requires a dropoff address is done by looking at destinationRequired boolean attribute. When true both a pickup and dropoff structure must be sent in booking request.

Authentication

You authenticate each request by sending a token either as an Authorization header:

curl https://api.drivr.com \
    -H "Authorization: Token token=\"OAUTH-TOKEN\""

Or by appending it as an access_token parameter:

curl https://api.drivr.com?access_token=OAUTH-TOKEN

Tokens can be initially acquired programmatically using basic authentication through /authorizations.

JSON-P callbacks

You may send a ?callback parameter to any GET operations to have results wrapped in a JSON callback function. This is typically used when browsers want to embed content in web pages by getting around cross domain issues. The response includes the same data output as the regular API, plus the relevant HTTP Header information.

Operations

POST /authorizations

Requests an authorization token by posting via basic authentication. Upon successful authentication a 256-bit token will be returned which should be used for future requests. These access tokens doesn't by default expire but it might become invalid over time. Using an invalid token in requests will result in 401 Unauthorized responses and you should in that case re-issue a request for a new token.

Example request

curl https://api.drivr.com/authorizations \
    -u john:doe -d '' \
    -H 'Accept: application/vnd.drivr.v2+json' \
    -H 'Content-type: application/json'

Example response

HTTP/1.0 201 Created
Content-Type: application/json; charset=utf-8

{
    "token": "1111a3bb8d4a40f08100e640621fee10"
}

GET /places/nearby

Returns list of nearby Point Of Interests (POIs). This could include airports, metro- or bus stations, restaurants and others. One POI doesn't necessarily have a category or it might have more than one category.

Request parameters

All parameters are optional unless specified otherwise.

latlng required Latitude and longitude of users current location separated with comma (example 55.10,12.13)

radius Radius (in meters) for nearby places. Fallbacks to a sensible default (example 25000)

language ISO 639-1 language code for getting localized names for returned places (example da)

Response attributes

ref Unique identifier for this POI and may be used as placeRef attribute when creating a booking.

name A localized name for a POI using requested language. An English name is returned in case none exists in requested language.

distance Calculated distance to this POI in meters.

radius Radius in meters of this POI.

categories[type] A type for this POI

Type Description
airport Place is an airport
restaurant Place is a restaurant
busStation Place is a bus station
trainStation Place is a train station
shopping Place is a shop
other Place is uncategories

Example request

curl https://api.drivr.com/places/nearby?latlng=55.68%2C12.59&radius=1000&language=da \
    -H 'Authorization: Token token="1111a3bb8d4a40f08065e640621fee63"' \
    -H 'Accept: application/vnd.drivr.v2+json'

Example response

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "id": "1",
        "ref": "COPENHAGEN AIRPORT",
        "name": "KĂžbenhavns Lufthavn",
        "location": {
            "houseNumber": "6",
            "streetName": "Lufthavnsboulevarden",
            "zipCode": "2770",
            "city": "Copenhagen",
            "country": "DK",
            "distance": 3241,
            "radius": 750,
            "lng": 12.638780000000001,
            "lat": 55.629640000000002
        },
        "categories": [
            {
                "type": "airport",
                "iconUrl": "http://resource.drivr.com/icons/place_type_airport@2x.png"
            }
        ]
    }
]

GET /places/:placeRef

Returns a place based on a reference.

Request parameters

All parameters are optional unless specified otherwise.

ref required String with reference of place to fetch

language ISO 639-1 language code for getting localized names for returned place (example da)

type Type of place to retrieve e.g. google if place is a Google type. The

Example request

curl https://api.drivr.com/places/CmRYAAAAciqGsTRX1mXRvuXSH2ErwW-jCINE1aLiwP64MCWDN5vkXvXoQGPKldMfmdGyqWSpm7BEYCgDm-iv7Kc2PF7QA7brMAwBbAcqMr5i1f4PwTpaovIZjysCEZTry8Ez30wpEhCNCXpynextCld2EBsDkRKsGhSLayuRyFsex6JA6NPh9dyupoTH3g&language=en&type=google \
    -H 'Authorization: Token token="1111a3bb8d4a40f08065e640621fee63"' \
    -H 'Accept: application/vnd.drivr.v2+json'

Example response

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

{
    "ref": "CmRYAAAAciqGsTRX1mXRvuXSH2ErwW-jCINE1aLiwP64MCWDN5vkXvXoQGPKldMfmdGyqWSpm7BEYCgDm-iv7Kc2PF7QA7brMAwBbAcqMr5i1f4PwTpaovIZjysCEZTry8Ez30wpEhCNCXpynextCld2EBsDkRKsGhSLayuRyFsex6JA6NPh9dyupoTH3g",
    "location": {
        "streetName": "Pirrama Road",
        "houseNumber": "48",
        "zipCode": "2009",
        "city": "Pyrmont",
        "country": "AU",
        "lat": -33.866975,
        "lng": 151.195677
    },
    "type": "google"
}

GET /companies/:companyId

Returns details about a specific company. Use this operation to a high-level details such as name, phone number and rating for a company. Operation will not return vehicle types, destination required details, etc since these are based on region and could be requested by using /companies/spot instead.

Request parameters

id required Id of company

Response attributes

name Name of taxi company

phone Number for taxi company using the E.164 format

automatedBooking True if company supports fully automated bookings through API; false otherwise

destinationRequired True if company requires a dropoff address for handling orders; false otherwise

minimumPreBooking & maximumPreBooking Define an interval for pre-booking, value in seconds (both can be empty)

Example request

curl https://api.drivr.com/companies/1081132172 \
    -H 'Authorization: Token token="11113a3bb8d4a40f08065e640621fee63"'
    -H 'Accept: application/vnd.drivr.v2+json'

Example response

{
    "id": "1081132172",
    "name": "Taxi4x35",
    "logoUrl": "http://resource.drivr.com/logos/taxi4x35.png",
    "phone": "+4535309184",
    "rating": 4.0
}

GET /companies/spot (obsolete)

This operation is now obsolete. Use /companies/lookup instead.

Returns a list of taxi companies operating in specified area. List is ordered by priority and if list is empty, no taxi companies were found to operate in specified area.

Request parameters

latlng required* Latitude and longitude separated with comma where taxi is requested (example 55.10,12.13)

language ISO 639-1 language code for getting localized names for returned address and description (example da for Danish). Defaults to en (for English).

country required* ISO 3166 country code where taxi is requested (example DK)

zipCode required* Zip code where taxi is requested (example 2200)

(*) required should be understood as (latlng OR (zipCode AND country))

Response attributes

rating Average rating of company as a floating point value. The rating is between 1 and 5. If no rating is returned that company doesn't have enough user ratings yet.

eta An estimated time of arrival for a taxi within this area at requested time.

properties.name[vehicleTypes] A list of available vehicle types offered by company. The ref attribute should be used as vehicleType attribute when ordering a taxi. List vary from company to company but may be cached by company. Recheck this attribute regularly since taxi companies might start to support more vehicle types. The list below shows some of the available types but this list will vary and thus you should not hardcode or limit bookings to only these types. Display them all and allow your users to select one of them.

Ref Description
taxi Standard taxi
fourSeaterStationCar Four seater station car
fiveSeater Five seater car
sixSeater Six seater car
sevenSeater Seven seater car
executive Executive car
premium Premium car

properties.name[services] Additional services offered by company.

Ref Description
childSeat Child seats are available upon request
bike Bikes may be brought with you
animal Animals may be brought onboard
wheelchair Wheelchairs may be brought onboard

Example request

curl https://api.drivr.com/companies/spot?zipCode=2200&country=dk \
    -H 'Authorization: Token token="11113a3bb8d4a40f08065e640621fee63"'
    -H 'Accept: application/vnd.drivr.v2+json'

Example response

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "id": "42345",
        "phone": "+4535359001",
        "name": "Taxi 4x35",
        "properties": [
            {
                "name": "vehicleTypes",
                "values": [
                    {
                        "ref": "fourSeaterAny",
                        "iconUrl": "http://resource.drivr.com/icons/four-seater-any@2x.png"
                    },
                    {
                        "ref": "sixSeater",
                        "iconUrl": "http://resource.drivr.com/icons/six-seater@2x.png"
                    }
                ],
                "mutuallyExclusive": true
            },
            {
                "name": "services",
                "values": [
                    {
                        "ref": "childSeat",
                        "iconUrl": "http://resource.drivr.com/icons/child_seat@2x.png"
                    },
                    {
                        "ref": "animals",
                        "iconUrl": "http://resource.drivr.com/icons/animals@2x.png"
                    },
                    {
                        "ref": "bike",
                        "iconUrl": "http://resource.drivr.com/icons/bike@2x.png"
                    }
                ],
                "mutuallyExclusive": false
            }
        ],
        "destinationRequired": false,
        "automatedBooking": true,
        "rating": 4.2,
        "eta": 8
    }
]

GET /companies/lookup

Requests address, company and address formats for a given location.

Request parameters

language ISO 639-1 language code of client (example da for Danish). This value is used to determine in which language addresses should be delivered.

latlng required* Latitude and longitude of location for reverse geocoding (example 55.10,12.13)

Response attributes

place A Place structure with address details about specified location.

company A Company structure with details about company operating in specified location.

addressFormat An AddressFormat structure with address formatting rules. This is an optional attribute which might not be available in all locations.

Example request

curl https://api.staging.drivr.com/companies/lookup?language=en-GB&latlng=51%2E509205,-0%2E146690 \
    -H 'Authorization: Token token="1111a3bb8d4a40f08065e640621fee63"' \
    -H 'Accept: application/vnd.drivr.v2+json' 

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "place": {
        "location": {
            "streetName": "Berkeley Square",
            "houseNumber": "45",
            "zipCode": "W1J 5AS",
            "city": "London",
            "country": "GB",
            "lat": 51.509208299999997,
            "lng": -0.14658589999999999,
            "formattedAddress": "Berkeley Square 45\nW1J 5AS London"
        }
    },
    "company": {
        "id": "1580030126",
        "name": "greentomatocars",
        "destinationRequired": true,
        "automatedBooking": true,
        "rating": 4.0,
        "phone": "+442083808900",
        "vehicleTypes": [
          {
            "id": "taxi",
            "name": "4 x",
            "description": "Licensed taxi vehicle",
            "extendedDescription": "Metered and regulated taxi service. Rates depend on day/time according to the taxi regulation.",
            "iconUrl": "https://resource-staging-drivr-com.s3.amazonaws.com/properties/vehicle-types_four-seater-any_logo.png",
            "seats": 4,
            "mapIconUrl": "https://resource-staging-drivr-com.s3.amazonaws.com/api/v2/vehicleTypes/ico_vehicle_taxi_top@2x.png"
          },
          {
            "id": "drivrExecutive",
            "name": "Executive",
            "description": "Mercedes S-class or similar",
            "extendedDescription": "High-end car, suited driver. Daytime / nighttime rates apply. Final price, all-inclusive, is reflected in the rates above. All vehicles and drivers are licensed.",
            "iconUrl": "https://resource-staging-drivr-com.s3.amazonaws.com/api/v2/vehicleTypes/ico_vehicle_drivrexecutive_side@2x.png",
            "seats": 4,
            "mapIconUrl": "https://resource-staging-drivr-com.s3.amazonaws.com/api/v2/vehicleTypes/ico_vehicle_drivrexecutive_top@2x.png"
          },
          {
            "id": "grande",
            "name": "Executive XL",
            "description": "6 Seater SUV or VAN",
            "extendedDescription": "Classy MPV, suited driver. Daytime / nighttime rates apply. Final price, all-inclusive, is reflected in the rates above. All vehicles and drivers are licensed.",
            "iconUrl": "https://resource-staging-drivr-com.s3.amazonaws.com/api/v2/vehicleTypes/ico_vehicle_grande_side@2x.png",
            "seats": 6,
            "mapIconUrl": "https://resource-staging-drivr-com.s3.amazonaws.com/api/v2/vehicleTypes/ico_vehicle_grande_top@2x.png"
          }
        ],
        "eta": 14
    },
    "addressFormat": {
        "titleTemplate": "streetName houseNumber",
        "subtitleTemplate": "zipCode city",
        "requiredFields": ["streetName", "houseNumber", "zipCode"]
    }
}

GET /clients/:clientId/bookings

Returns list of all bookings created by client with specified id. Only bookings for clients you have created can be requested. Requesting bookings for a client you haven't created will return a 404 error message.

Request parameters

All parameters are optional unless specified otherwise.

since Only return bookings after this timestamp (example 2012-03-24T11:00:00Z). If not specified all bookings are returned.

completed A boolean value indicating if only completed bookings should be returned. If not specified all bookings are returned.

Response attributes

company Full Company object with taxi company which handled booking

pickup Full Location object with pickup details

dropoff Full Location object with dropoff details (only returned if available).

vehicleType Type of car which is picking up client. Valid values are returned in companies/lookup operations (vehicleTypes attribute)

arrivalAt Date and time taxi will arrive/arrived.

statuses List of statuses associated with booking. Statuses are localized based on clients language. See clients/:clientId/bookings/:bookingId for details about these statuses.

state Current state of booking as active, successful or unsuccessful.

Example request

curl https://api.drivr.com/clients/61241/bookings?since=2012-01-01 \
    -H 'Authorization: Token token="1111a3bb8d4a40f08065e640621fee63"' \
    -H 'Accept: application/vnd.drivr.v2+json' \
    -H 'Content-Type: application/json' 

Example response

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "id": "1",
        "company": {
            "id": "1",
            "name": "Taxa 4x35",
            "destinationRequired": false
        },
        "pickup": {
            "streetName": "Amaliegade",
            "houseNumber": "36",
            "city": "Copenhagen K",
            "country": "DK",
            "distance": 0,
            "lat": 55.68,
            "lng": 12.59,
            "zipCode": "1256"
        },
        "dropoff": {
            "streetName": "Jagtvej",
            "houseNumber": "111",
            "city": "Copenhagen N",
            "country": "DK",
            "distance": 0,
            "lat": 54.310000000000002,
            "lng": 12.199999999999999,
            "zipCode": "2200"
        },
        "vehicleType": "fourSeaterAny",
        "statuses": [
            {
                "createdAt": "2012-08-28T13:43:03.4005202Z",
                "type": "executed",
                "header": "Booking is received",
                "body": "Your taxi will pick you up at the selected time",
                "cancelable": true,
                "completed": false
            },
            {
                "createdAt": "2012-08-28T13:42:59.5315289Z",
                "type": "processing",
                "header": "Processing",
                "body": "We are processing thebooking request.",
                "cancelable": true,
                "completed": false
            },
            {
                "createdAt": "2012-08-28T13:42:48.9221817Z",
                "type": "registered",
                "header": "Booking is received",
                "body": "Your taxi will pick you up at the selected time",
                "cancelable": true,
                "completed": false
            }
        ],
        "createdAt": "2012-03-19T06:30:01.0000000Z",
        "arrivalAt": "2012-03-20T08:00:00.0000000Z"
    },
    {
        "id": "2",
        "company": {
            "id": "1",
            "name": "Taxa 4x35",
            "destinationRequired": false
        },
        "pickup": {
            "streetName": "Jagtvej",
            "houseNumber": "111",
            "city": "Copenhagen N",
            "country": "DK",
            "distance": 0,
            "lat": 54.310000000000002,
            "lng": 12.199999999999999,
            "zipCode": "2200"
        },
        "vehicleType": "fourSeaterStationCar",
        "statuses": [
            {
                "createdAt": "2012-08-28T13:24:38.7074821Z",
                "type": "paid",
                "header": "Trip finished",
                "body": "Thank you for your business",
                "cancelable": true,
                "completed": true
            },
            {
                "createdAt": "2012-08-28T13:24:30.6422698Z",
                "type": "ongoing",
                "header": "Trip in progress",
                "body": "Enjoy the ride",
                "cancelable": false,
                "completed": false
            },
            {
                "createdAt": "2012-08-28T13:24:22.5826582Z",
                "type": "arrived",
                "header": "Arrived",
                "body": "Taxa 4 x 35 has arrived!",
                "cancelable": false,
                "completed": false
            },
            {
                "createdAt": "2012-08-28T13:24:14.5090438Z",
                "type": "arrival_time",
                "header": "Status update",
                "body": "Updated arrival time is approx: 5 min.",
                "cancelable": false,
                "completed": false
            },
            {
                "createdAt": "2012-08-28T13:24:07.0955614Z",
                "type": "accepted",
                "header": "Booking is received",
                "body": "Your taxi will pick you up at the selected time",
                "cancelable": false,
                "completed": false
            },
            {
                "createdAt": "2012-08-28T13:24:06.9895402Z",
                "type": "cancel_disabled",
                "header": "Booking is received",
                "body": "Your taxi will pick you up at the selected time",
                "cancelable": false,
                "completed": false
            },
            {
                "createdAt": "2012-08-28T13:24:00.0468327Z",
                "type": "executed",
                "header": "Booking is received",
                "body": "Your taxi will pick you up at the selected time",
                "cancelable": true,
                "completed": false
            },
            {
                "createdAt": "2012-08-28T13:23:56.3048576Z",
                "type": "processing",
                "header": "Processing",
                "body": "We are processing the booking request.",
                "cancelable": true,
                "completed": false
            },
            {
                "createdAt": "2012-08-28T13:23:44.7758936Z",
                "type": "registered",
                "header": "Booking is received",
                "body": "Your taxi will pick you up at the selected time",
                "cancelable": true,
                "completed": false
            }
        ],
        "createdAt": "2012-03-12T19:05:32.0000000Z",
        "arrivalAt": "2012-03-12T19:05:32.0000000Z"
    }
]

POST /clients

Creates a new client which is necessary before a booking can be created. A client must have at least a name and phone number. Both name and phone number might be forwarded to a taxi company in order to book taxis, so make sure your privacy policy tells your users about it. An SMS might be sent to client for verification purposes.

Request attributes

name Name of client which could be forwarded to taxi company. This is usually a last name but could be a full name too.

phone Number of client formatted as a E.164 number.

language ISO 639-1 language code of client (example da for Danish). This value is used to determine in which language status messages should be delivered. Supported values are ["en", "es", "de", "it", "fr", "pt", "da", "sv", "nb"].

os Type of OS used by client, if applicable. Types can be either 'ios', 'android' or 'windowsPhone'.

guid Optional. A unique identifier for client which you may use internally since it will never change. If not specified you should read the returned guid attribute in response payload and store that when updating clients.

pushToken A string with a token used for sending push notifications to clients. This parameter is optional.

Example request

curl https://api.drivr.com/clients \
    -H 'Authorization: Token token="1993a3bb8d4a40f08065e640621fee63"' \
    -H 'Accept: application/vnd.drivr.v2+json' \
    -H 'Content-type: application/json' \
    -d '{ "name": "Doe", "phone": "+4561616161", "os": "android" }'

Example response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "createdAt": "2012-09-05T12:11:01.9744265Z",
    "id": "61449",
    "name": "Doe",
    "phone": "+4561616161",
    "language": "en",
    "os": "android",
    "guid": "1003a3bb8d4a40f08065e640621fee63"
}

GET /clients/:clientId

Get details about an existing client. Only clients created by you can be fetched. Requesting other clients will return in a 404 Not Found response.

Example request

curl https://api.drivr.com/clients/61449
    -H 'Authorization: Token token="1111a3bb8d4a40f08065e640621fee63"'
    -H 'Accept: application/vnd.drivr.v2+json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "createdAt": "2012-09-05T12:11:01.9744265Z",
    "id": "61449",
    "name": "Doe",
    "phone": "+4561616161",
    "language": "en",
    "email": "john@doe.com",
    "guid": "1003a3bb8d4a40f08065e640621fee63"
}

PUT /clients/:clientId

Updates an existing client. Only clients created by you can be updated.

Example request

curl https://api.drivr.com/clients/61449
    -H 'Authorization: Token token="1111a3bb8d4a40f08065e640621fee63"'
    -H 'Accept: application/vnd.drivr.v2+json'
    -H 'Content-type: application/json'
    -d '{ "name": "Jobs", "phone": "+4561715099" }'
    -X PUT

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "createdAt": "2012-09-05T12:11:01.9744265Z",
    "id": "61449",
    "name": "Jobs",
    "phone": "+4561715099",
    "language": "en",
    "email": "john@doe.com",
    "guid": "1003a3bb8d4a40f08065e640621fee63",
    "pushToken": "07a50578c0c94d0da276aab1a9c9166b"
}

POST /clients/:clientId/bookings

Requests a new taxi booking for an existing client. An immediate booking is requested by excluding arrivalAt attribute from body. A pre-booking should always have an arrivalAt in its body. Notice, some taxi companies require a destination address so a call to /companies/spot should be made before booking in a new area. Check destinationRequired attribute on response to find out if a destination address is required in that area.

A success response means our system has accepted your request for a taxi but not necessarily that this taxi will be booked. Since we are connecting to real taxi companies around the globe it sometimes will not be possible to fulfill the order. You should check the order status by calling /clients/:clientId/bookings/:bookingsId regularly.

Request attributes

pickup Pickup details

dropoff Dropoff details

vehicleType Type of car which is requested. Valid values are returned in companies/spot operations (vehicleTypes attribute)

arrivalAt Optional date and time for when taxi is requested. If not specified a taxi is immediately requested.

comment An optional comment for driver to see.

Example request

Creates a pre-booking of a medium sized taxi for Christmas Eve. A pickup structure may include a placeRef attribute instead of a full address in case you want to book at a Point Of Interest. Client is bringing a child so a child seat is requested as a service too.

curl https://api.drivr.com/clients/9535253/bookings \
    -H 'Authorization: Token token="1111a3bb8d4a40f08065e640621fee63"' \
    -H 'Accept: application/vnd.drivr.v2+json' \
    -H 'Content-type: application/json' \
    -d '{ "arrivalAt": "2012-12-24T20:00:00.0000000Z", "pickup":{"streetName":"Amaliegade","houseNumber":"36","zipCode":"1256","city":"Copenhagen K","country":"DK","lat":55.68,"lng":12.59}, "vehicleType": "fourSeaterAny", "services": "childSeat" }'

Example response

HTTP/1.0 201 Created
Location: https://api.drivr.com/clients/9535253/bookings/483233
Content-Type: application/json; charset=utf-8

{
    "id": "483233",
    "clientId": "9535253",
    "vehicleType": "fourSeaterAny",
    "arrivalAt": "2012-12-24T20:00:00.0000000Z",
    "company": {
        "id": "1",
        "name": "Taxa 4x35",
        "destinationRequired": false,
        "phone": "+4535309184"
    },
    "pickup": {
        "lng": 12.59,
        "country": "DK",
        "zipCode": "1256",
        "city": "Copenhagen K",
        "lat": 55.68,
        "streetName": "Amaliegade",
        "houseNumber": "36",
    },
    "services": [
        "childSeat"
    ]
    "createdAt": "2012-04-09T20:17:16.1958490Z"
}

GET /clients/:clientId/bookings/:id

Returns full details about an existing booking created by client.

Response attributes

completed True if booking may be considered as completed i.e. a client has completed trip or trip has failed.

state Current state of booking as active, successful or unsuccessful.

statuses List of statuses associated with booking. Statuses are localized based on client language.

statuses[id] Unique id of booking status returned. May be used by you to check if a given status has been handled/displayed for users.

statuses[createdAt] Timestamp of when booking status has been created.

statuses[type] Type of status returned. Might be one of the below mentioned.

Type Description
registered Order has been registered
dispatched Taxi has been dispatched
arrived Taxi has arrived
passengerOnBoard Taxi is driving with passenger
cancelled Order has been cancelled
noShow Taxi driver reported customer did not show up
completed Order has been completed
delayed Taxi is delayed and will arrive later than originally estimated
failed Order failed and no taxi will arrive. This might happen for a number of reasons but primarly if a booking is tried to be placed automatically but fails because of invalid address or external system error.
processing Order is being processed by external systems
arrivalTime Taxi has responded with an updated arrival time
executed Order has been dispatched to external systems
unfulfilled Order was not successfully completed and no taxi will arrive. This might happen when taxi company doesn't pick up their phone, they are too busy to process more orders at the moment or address/area is illegal for some reason. If you are certain on address you could retry request within a couple of minutes.
assigned Order is being manually assigned
lookOut Taxi is about to arrive and customer should get ready for it
callAssist Order requires additional information and customer should call taxi company

statuses[header] Short description of status. Localized in clients language.

statuses[body] Longer description including details of status. Localized in clients language.

statuses[cancelable] True if a booking is still valid to cancel; false otherwise. Is true initially and changes to false once a car has been dispatched or if isn't possible to cancel a placed booking.

Example request

curl https://api.drivr.com/clients/61241/bookings/923880 \
    -H 'Authorization: Token token="1111a3bb8d4a40f08065e640621fee63"' \
    -H 'Accept: application/vnd.drivr.v2+json' \
    -H 'Content-type: application/json'

Example response

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": "923880",
    "clientId": "61241",
    "company": {
        "id": "2",
        "name": "Taxa4 x 35",
        "properties": [
            {
                "name": "vehicleTypes",
                "values": [
                    {
                        "ref": "fourSeaterAny",
                        "iconUrl": "http://resource.staging.drivr.com/properties/vehicle-types_four-seater-any_logo.png"
                    },
                    {
                        "ref": "fourSeaterStationCar",
                        "iconUrl": "http://resource.staging.drivr.com/properties/vehicle-types_four-seater-station-car_logo.png"
                    }
                ],
                "mutuallyExclusive": true
            }
        ],
        "rating": 4.0,
        "phone": "+4535309184"
    },
    "pickup": {
        "streetName": "Amaliegade",
        "houseNumber": "36",
        "city": "Copenhagen K",
        "country": "DK",
        "distance": 0,
        "lat": 55.68,
        "lng": 12.59,
        "zipCode": "1256"
    },
    "vehicleType": "fourSeaterAny",
    "statuses": [
        {
            "createdAt": "2012-03-19T13:24:00.0468327Z",
            "type": "executed",
            "header": "Booking is received",
            "body": "Your taxi will pick you up at the selected time",
            "cancelable": true
        },
        {
            "createdAt": "2012-03-19T13:23:56.3048576Z",
            "type": "processing",
            "header": "Processing",
            "body": "We are processing the booking request.",
            "cancelable": true
        },
        {
            "createdAt": "2012-03-19T13:23:44.7758936Z",
            "type": "registered",
            "header": "Booking is received",
            "body": "Your taxi will pick you up at the selected time",
            "cancelable": true
        }
    ],
    "createdAt": "2012-03-19T06:30:01.0000000Z",
    "arrivalAt": "2012-03-20T08:00:00.0000000Z",
    "state": "active"
}

DELETE /clients/:clientId/bookings/:bookingId

Cancels a booking. The method might fail with a 400 Bad Request response in case a booking can't be canceled e.g. if taxi is already on its way or at the pickup address. A 422 Unprocessed Entity response is returned in case specified clientId or bookingId isn't valid.

Example request

curl https://api.drivr.com/clients/61241/bookings/923878 \
    -H 'Authorization: Token token="1111a3bb8d4a40f08065e640621fee63"' \
    -H 'Accept: application/vnd.drivr.v2+json' \
    -X DELETE

Example response

When booking has been canceled successfully

HTTP/1.1 200 OK

POST /ratings

Rates a current booking. The clientId, bookingId and stars attributes are required. Attribute stars must be a valid integer between 1 and 5 (both inclusive).

Example request

curl https://api.drivr.com/ratings \
    -H 'Authorization: Token token="1111a3bb8d4a40f08065e640621fee63"' \
    -H 'Accept: application/vnd.drivr.v2+json' \
    -H 'Content-type: application/json' \
    -d '{ "clientId": "1543263", "bookingId": "5436443", "stars": 4, "review": "Funny driver" }'

Example response

HTTP/1.1 201 Created
Location: https://api.drivr.com/ratings/9dc8bb819c2a4cc4990a9f93be78669e
Content-Type: application/json; charset=utf-8

{
    "id": "9dc8bb819c2a4cc4990a9f93be78669e",
    "clientId": "1543263",
    "bookingId": "5436443",
    "stars": 4,
    "review": "Funny driver"
}

GET /places/search

Searches for addresses or POIs within a given radius. More details can be fetched for a specific result using /places.

Request parameters

query required* String with value to be searched (example jagtvej)

language ISO 639-1 language code for getting localized names for returned results (example da). Defaults to en

latlng Latitude and longitude of origin (example 55.10,12.13)

radius Radius of results to be returned. Only used if latlng is specified. Defaults to 5000 (meters)

Response parameters

ref Unique reference of Place.

categories Array of categories.

type Type of place. Currently supports internal and google.

Example request

curl https://api.drivr.com/places/search?latlng=55.10,12.13&keyword=jagtvej \
    -H 'Authorization: Token token="1111a3bb8d4a40f08065e640621fee63"' \
    -H 'Accept: application/vnd.drivr.v2+json' 

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "ref": "ClRKAAAABUa0QH9RPJ4TyqNrPHPPRXcL1Yn9VBGJKFoJzvB0FC2vym_qmQwPQmytzxAXeZtFapkP9VjJ0tK0aRJByGYXCLWLU8mCPxMNF-KdWHDZTK0SEFWe8MTDCECOZD4pvlLoP8UaFAcj8JzkrZUqBXD5tZ6zX9a3pda7",
        "name": "Jagtvej, Copenhagen, Denmark",
        "categories": [
            {
                "type": "route"
            },
            {
                "type": "geocode"
            }
        ],
        "type": "google"
    },
    {
        "ref": "ClRIAAAAUj6yruZLNXb-3_Qh8RBpnI574KGYfuPCGFFFkBit0Bztz8HcJQziEjSUU6bS4NseS16F2-mzHqkoEM-5Bw7HOUEo3amrS9HIXcK0alu4ooISEMP5GwkWAxDjWM61fxXHIgcaFPIC1p6JqjC46AEujAQjeF5MjopQ",
        "name": "Jagtvej, Naestved, Denmark",
        "categories": [
            {
                "type": "route"
            },
            {
                "type": "geocode"
            }
        ],
        "type": "google"
    }
]

POST /quotes

Requests a price quote from pickup to dropoff.

Request parameters

pickup required* Location structure with pickup details

dropoff required* Location structure with dropoff details

vehicleType required* Type of car which is picking up client. Valid values are returned in companies/spot operations (vehicleTypes attribute)

quotingAt Optional time of price quote. Prices might vary over time e.g. it might be more expensive to order a car friday evening than wednesday at noon

Response parameters

ref Unique reference of Place.

categories Array of categories.

type Type of place. Currently supports internal and google.

Example request

Requesting a price quote from Amaliegade to Jagtvej on Christmas Eve.

curl https://api.drivr.com/quotes \
    -H 'Authorization: Token token="1111a3bb8d4a40f08065e640621fee63"' \
    -H 'Accept: application/vnd.drivr.v2+json' \
    -H 'Content-type: application/json' \
    -d '{ "quotingAt": "2012-12-24T20:00:00.0000000Z", "pickup":{"streetName":"Amaliegade","houseNumber":"36","zipCode":"1256","city":"Copenhagen K","country":"DK","lat":55.68,"lng":12.59}, "dropoff":{"streetName":"Jagtvej","houseNumber":"111","zipCode":"2200","city":"Copenhagen N","country":"DK","lat":55.696406,"lng":12.550911}, "vehicleType": "taxi" }'

Example response

{
  "pickup": {
    "streetName": "Amaliegade",
    "houseNumber": "36",
    "zipCode": "1256",
    "city": "Copenhagen K",
    "country": "DK",
    "lat": 55.68,
    "lng": 12.59
  },
  "dropoff": {
    "streetName": "Jagtvej",
    "houseNumber": "111",
    "zipCode": "2200",
    "city": "Copenhagen N",
    "country": "DK",
    "lat": 55.696406,
    "lng": 12.550911
  },
  "vehicleType": "taxi",
  "price": {
    "value": 179.0,
    "currency": "Kr."
  },
  "quotingAt": "2012-12-24T20:00:00Z",
  "language": "en"
}