Skip to content

Instantly share code, notes, and snippets.

@nicolasiensen

nicolasiensen/drt-server-openapi.yml

Last active December 13, 2018 18:56
Show Gist options
  • Save nicolasiensen/0389e66d760565e76298c84423320612 to your computer and use it in GitHub Desktop.
Save nicolasiensen/0389e66d760565e76298c84423320612 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
drt-server-openapi.yml
openapi: 3.0.2
info:
version: 0.0.1
title: Rideshare API
description: |
The Rideshare API provides access to the rideshare service runned by [door2door](https://www.door2door.io/).
# Environments
This API can be consumed in two different environments, staging and production.
The staging environment provides a safe playground to test a new integration, and it is available in:
`https://d2d-api.staging.d2di.net/rideshare/v0`
The production environment is used for live rideshare operations, and it should not be used for testing purposes.
`https://api.door2door.io/rideshare/v0`
# Authentication
An API key is required across all the endpoints for authentication, it can be provided in the header of the requests as `X-Api-Key`.
# Language
Requests with the parameter `Accept-Language` in the header will have the response localized accordingly, and in the absence of it, the languange will be set to English by default.
The following languages are supported:
<table>
<thead>
<tr>
<th>Language</th>
<th><code>Accept-Language</code></th>
</tr>
</thead>
<tbody>
<tr>
<td>English</td>
<td><code>en</code></td>
</tr>
<tr>
<td>German</td>
<td><code>de</code></td>
</tr>
<tr>
<td>Spanish</td>
<td><code>es</code></td>
</tr>
<tr>
<td>Catalan</td>
<td><code>ca</code></td>
</tr>
</tbody>
</table>
# Errors
When an error occurs, there is a standard format in which they are returned.
Whilst we strive to use relevant HTTP status codes in the responses, the error code property is more informative and less ambiguous in meaning.
Some endpoints might return a successful response code (200 OK) with an error in the response body.
servers:
- url: https://api.door2door.io/rideshare/v0
security:
- api_key: []
tags:
- name: Availability
paths:
/availability:
get:
summary: Retrieve availability for a ride
description: |
This endpoint allows you to query if a specific ride can be served at the current time, how long it would take, and how much it will cost.
No booking results from calling this endpoint, no driver is re-routed, and a successful response does not represent a commitment to a successful subsequent booking.
## Error responses
<table>
<thead>
<tr>
<th>Error code</th>
<th>Possible cause(s)</th>
</tr>
</thead>
<tbody>
<tr>
<td>DRT005</td>
<td>You made an invalid request; check it conforms with the above specification.</td>
</tr>
<tr>
<td>DRT010</td>
<td>The system cannot accommodate the requested ride at this time.</td>
</tr>
<tr>
<td>DRT011</td>
<td>One or both of the locations falls outside of the operating area of any of the regions.</td>
</tr>
<tr>
<td>DRT014</td>
<td>The pickup and dropoff locations are too close together.</td>
</tr>
<tr>
<td>DRT017</td>
<td>The region that ride falls within is not operating at this time.</td>
</tr>
<tr>
<td>DRT032</td>
<td>The number of passengers in the ride exceeds the maximum for this region.</td>
</tr>
<tr>
<td>SERVERERR</td>
<td>An unexpected error occurred in the server.</td>
</tr>
</tbody>
</table>
parameters:
- name: from
in: query
description: Coordinates of the pickup location in the format `lat,lng`
required: true
schema:
type: "string"
- name: to
in: query
description: Coordinates of the dropoff location in the format `lat,lng`
required: true
schema:
type: "string"
- name: from_address
in: query
description: Address of the pickup location, it is going to be used as a human-readable address for the driver
required: true
schema:
type: "string"
- name: to_address
in: query
description: Address of the dropoff location, it is going to be used as a human-readable address for the driver
required: true
schema:
type: "string"
- name: passenger_count
in: query
description: Total number of passengers for the ride.
required: true
schema:
type: "integer"
- name: from_name
in: query
description: Name of the pickup location
schema:
type: "string"
- name: to_name
in: query
description: Name of the dropoff location
schema:
type: "string"
- name: passenger_reference
in: query
description: An arbitrary string that identifies a unique passenger, this information is used to generate reports and retrieve entities associated with a specific passenger
schema:
type: "string"
responses:
'200':
description: Retrieve availability for a ride
content:
'application/json':
schema:
type: object
properties:
region_id:
type: string
example: bdef254a-da12-4bc6-b0d5-0e282b3c6afe
availability:
type: object
properties:
price:
$ref: "#/components/schemas/Price"
tariffs:
type: array
items:
$ref: "#/components/schemas/Tariff"
tasks:
type: array
items:
$ref: "#/components/schemas/Task"
segments:
type: array
items:
$ref: "#/components/schemas/Segment"
examples:
success:
summary: Retrieve availability for a ride
value:
region_id: bdef254a-da12-4bc6-b0d5-0e282b3c6afe
availability:
price:
amount: 0
currency: EUR
tariffs:
- id: 5abdf020-bea9-4158-a861-f8bf0d85eaf6
name: Free
description: "€0.00 / passenger"
disclaimer:
passenger_count: 1
price:
amount: 0
currency: EUR
tasks:
- estimated_time: '2018-11-23T16:32:21Z'
latest_time: '2018-11-23T16:37:21Z'
location:
lat: 52.5298679
lng: 13.4030611
address: U Rosenthaler Platz (Berlin), 10119 Berlin, Germany
name: U Rosenthaler Platz (Berlin), 10119 Berlin, Germany
type: pickup
- estimated_time: '2018-11-23T16:44:12Z'
latest_time: '2018-11-23T16:50:12Z'
location:
lat: 52.5258184
lng: 13.3694125
address: Europaplatz 2, 10557 Berlin, Germany
name: Europaplatz 2, 10557 Berlin, Germany
type: dropoff
segments:
- type: walking
name:
short_name:
description:
color: "#b1becc"
polyline: "{xr_I_xxpAdAC"
stops:
- location:
lat: 52.530221
lng: 13.403038
name: door2door HQ
address: Torstraße 109, 10119 Berlin
scheduled_time: '2018-11-23T16:31:51+00:00'
estimated_time: '2018-11-23T16:31:51+00:00'
latest_time: '2018-11-23T16:36:51+00:00'
- location:
lat: 52.5298679
lng: 13.4030611
name: U Rosenthaler Platz (Berlin), 10119 Berlin, Germany
address: U Rosenthaler Platz (Berlin), 10119 Berlin, Germany
scheduled_time: '2018-11-23T16:32:21+00:00'
estimated_time: '2018-11-23T16:32:21+00:00'
latest_time: '2018-11-23T16:37:21+00:00'
- type: rideshare
name: aroundBerlin
short_name: aroundBerlin
description:
color: "#F78F77"
polyline: uvr_IcxxpAhXhqE
stops:
- location:
lat: 52.5298679
lng: 13.4030611
name: U Rosenthaler Platz (Berlin), 10119 Berlin, Germany
address: U Rosenthaler Platz (Berlin), 10119 Berlin, Germany
scheduled_time: '2018-11-23T16:32:21+00:00'
estimated_time: '2018-11-23T16:32:21+00:00'
latest_time: '2018-11-23T16:37:21+00:00'
- location:
lat: 52.5258184
lng: 13.3694125
name: Europaplatz 2, 10557 Berlin, Germany
address: Europaplatz 2, 10557 Berlin, Germany
scheduled_time: '2018-11-23T16:44:12+00:00'
estimated_time: '2018-11-23T16:44:12+00:00'
latest_time: '2018-11-23T16:50:12+00:00'
operator:
name: door2door GmbH
- type: walking
name:
short_name:
description:
color: "#b1becc"
polyline: k}q_IyerpArB?
stops:
- location:
lat: 52.5258184
lng: 13.3694125
name: Europaplatz 2, 10557 Berlin, Germany
address: Europaplatz 2, 10557 Berlin, Germany
scheduled_time: '2018-11-23T16:44:12+00:00'
estimated_time: '2018-11-23T16:44:12+00:00'
latest_time: '2018-11-23T16:50:12+00:00'
- location:
lat: 52.525241
lng: 13.369413
name: Berlin Central Station
address: Hauptbahnhof, Europaplatz 1, 10557 Berlin
scheduled_time: '2018-11-23T16:45:01+00:00'
estimated_time: '2018-11-23T16:45:01+00:00'
latest_time: '2018-11-23T16:51:01+00:00'
error:
summary: Retrieve availability for a ride that can not be accepted
value:
error:
code: DRT010
message: The ride request couldn't be accepted.
details: It is not possible to assign a DRT vehicle to accept the ride request.
user_friendly:
title: Hey, please try again later!
description: Unfortunately, there are no vehicles available at the moment. Please try again later.
tags:
- Availability
components:
securitySchemes:
"X-Api-Key":
type: apiKey
name: "X-Api-Key"
in: header
schemas:
Error:
type: object
properties:
code:
type: string
example: DRT010
message:
type: string
example: The ride request couldn't be accepted.
details:
type: string
example: It is not possible to assign a DRT vehicle to accept the ride request.
user_friendly:
type: object
properties:
title:
type: string
example: Hey, please try again later!
description:
type: string
example: Unfortunately, there are no vehicles available at the moment. Please try again later.
extra_data:
type: object
description: The extra_data property is not always present, but certain errors will include it. This will be noted in the documentation of the endpoint that emits the error.
The schema may depend on the specific error.
Location:
type: object
properties:
lat:
type: number
example: 52.5298679
lng:
type: number
example: 13.4030611
address:
type: string
example: Torstraße 109, 10119 Berlin
name:
type: string
example: door2door HQ
Price:
type: object
properties:
amount:
type: integer
example: 0
description: Number in cents
currency:
type: string
example: EUR
description: Code of the currency
Segment:
type: object
properties:
type:
type: string
enum:
- walking
- rideshare
example: walking
name:
type: string
description: Only present if it is a <code>rideshare</code> segment, and it will contain the name of the service operator
short_name:
type: string
description:
type: string
color:
type: string
example: "#b1becc"
polyline:
type: string
example: "{xr_I_xxpAdAC"
description: <a href="https://developers.google.com/maps/documentation/utilities/polylinealgorithm">Encoded</a> visual representation of the segment that can be rendered on a map
stops:
type: array
description: List containing the origin and the destination of the segment
items:
properties:
location:
$ref: "#/components/schemas/Location"
scheduled_time:
type: string
format: date-time
example: '2018-11-23T16:31:51+00:00'
description: Time when the stop is meant to be reached by the rideshare vehicle
estimated_time:
type: string
format: date-time
example: '2018-11-23T16:31:51+00:00'
description: Time when the stop is expected to be reached by the rideshare vehicle given the currently available realtime information. A difference between this time and the <code>scheduled_time</code> reflects a delay
latest_time:
type: string
format: date-time
example: '2018-11-23T16:36:51+00:00'
description: Maximum time when the stop should be reached by the rideshare vehicle
Tariff:
type: object
properties:
id:
type: string
example: 5abdf020-bea9-4158-a861-f8bf0d85eaf6
description: Unique tariff identifier
name:
type: string
example: Free
description: Localized human-readable name of the tariff
description:
type: string
example: "€0.00 / passenger"
description: Localized human-readable description of the tariff
passenger_count:
type: integer
example: 1
minimum: 1
description: Number of passengers using the tariff
price:
$ref: "#/components/schemas/Price"
Task:
type: object
properties:
estimated_time:
type: string
format: date-time
example: '2018-11-23T16:32:21Z'
latest_time:
type: string
format: date-time
example: '2018-11-23T16:37:21Z'
location:
$ref: "#/components/schemas/Location"
type:
type: string
enum:
- pickup
- dropoff
example: pickup
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment