Skip to content

Commit e4367d0

Browse files
marie-xmarie-x
committed
WIP
1 parent 11092c7 commit e4367d0

2 files changed

Lines changed: 43 additions & 54 deletions

File tree

‎agency/README.md‎

Lines changed: 21 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ Body Params:
162162

163163
| Field | Type | Required/Optional | Field Description |
164164
|-----------------|------------------------------|------------------------|------------------------------------------------------------------------------------------------------------|
165-
| `data` | [EventData](#vehicle-event-data)[] | Required | An array of [Vehicle Event Data](#vehicle-event-data) objects. |
165+
| `events` | [EventData](#vehicle-event-data)[] | Required | An array of [Vehicle Event Data](#vehicle-event-data) objects. |
166166

167167
200 Success Response:
168168

@@ -195,7 +195,7 @@ Body Params:
195195

196196
| Field | Type | Required/Optional | Field Description |
197197
| ------------- | ------------------------------ | ----------------- | -------------------------------------------------------------------------------------- |
198-
| `data` | [Telemetry](#telemetry-data)[] | Required | Array of telemetry for one or more vehicles. |
198+
| `telemetries` | [Telemetry](#telemetry-data)[] | Required | Array of telemetry for one or more vehicles. |
199199

200200
200 Success Response:
201201

@@ -216,32 +216,6 @@ Body Params:
216216

217217
[Top][toc]
218218

219-
<<<<<<< HEAD
220-
=======
221-
## Telemetry Data
222-
223-
A standard point of vehicle telemetry. References to latitude and longitude imply coordinates encoded in the [WGS 84 (EPSG:4326)](https://en.wikipedia.org/wiki/World_Geodetic_System) standard GPS or GNSS projection expressed as [Decimal Degrees](https://en.wikipedia.org/wiki/Decimal_degrees).
224-
225-
| Field | Type | Required/Optional | Field Description |
226-
| -------------- | -------------- | --------------------- | ------------------------------------------------------------ |
227-
| `device_id` | UUID | Required | ID used in [Register](#vehicle---register) |
228-
| `timestamp` | [timestamp][ts]| Required | Date/time that event occurred. Based on GPS or GNSS clock |
229-
| `gps` | Object | Required | Telemetry position data |
230-
| `gps.lat` | Double | Required | Latitude of the location |
231-
| `gps.lng` | Double | Required | Longitude of the location |
232-
| `gps.altitude` | Double | Required if Available | Altitude above mean sea level in meters |
233-
| `gps.heading` | Double | Required if Available | Degrees - clockwise starting at 0 degrees at true North |
234-
| `gps.speed` | Float | Required if Available | Estimated speed in meters / sec as reported by the GPS chipset |
235-
| `gps.accuracy` | Float | Required if Available | Horizontal accuracy, in meters |
236-
| `gps.hdop` | Float | Required if Available | Horizontal GPS or GNSS accuracy value (see [hdop][hdop]) |
237-
| `gps.satellites` | Integer | Required if Available | Number of GPS or GNSS satellites
238-
| `battery_percent` | Integer | Required if Applicable | Percent battery charge of vehicle, expressed between 0 and 100 |
239-
| `fuel_percent` | Integer | Required if Applicable | Percent fuel in vehicle, expressed between 0 and 100 |
240-
| `stop_id` | UUID | Required if Applicable | Stop that the vehicle is currently located at. Only applicable for _docked_ Micromobility. See [Stops][stops] |
241-
242-
[Top][toc]
243-
244-
>>>>>>> dev
245219
## Stops
246220

247221
The `/stops` endpoint allows an agency to register city-managed Stops, or a provider to register self-managed Stops.
@@ -311,41 +285,32 @@ If `stop_id` is specified, `GET` will return an array with a single stop record,
311285

312286
[Top][toc]
313287

314-
## Trip Metadata
288+
## Trips
315289

316290
The Trips endpoint serves two purposes:
317291

318292
* Definitively indicating that a Trip (a sequence of events linked by a trip_id) has been completed. For example, from analyzing only the raw Vehicle Events feed, if a trip crosses an Agency's jurisdictional boundaries but does not end within the jurisdiction (last event_type seen is a `leave_jurisdiction`), this can result in a 'dangling trip'. The Trips endpoint satisfies this concern, by acting as a final indication that a trip has been finished, even if it ends outside of jurisdictional boundaries; if a trip has intersected an Agency's jurisdictional boundaries at all during a trip, it is expected that a Provider will send a Trip payload to the Agency following the trip's completion.
319293
* Providing information to an Agency regarding an entire trip, without extending any of the Vehicle Event payloads, or changing any requirements on when Vehicle Events should be sent.
320294

321-
WORK IN PROGRESS - THIS WILL BE UNIFIED WITH TRIP DATA IN `general_information`
322-
323-
| Field | Type | Required/Optional | Field Description |
324-
|-------------------------------|--------------------------------|------------------------| ----------------- |
325-
| trip_id | UUID | Required | UUID for the trip this payload pertains to |
326-
| trip_type | Enum | Optional | The type of the trip |
327-
| trip_attributes | `{ [String]: String}` | Optional | Trip attributes, given as mode-specific key-value pairs |
328-
| provider_id | UUID | Required | Provider which managed this trip |
329-
| reservation_method | Enum | Required | Way the customer created their reservation, see [reservation-method](#reservation-method) |
330-
| reservation_time | Timestamp | Required | Time the customer *requested* a reservation |
331-
| reservation_type | Enum | Required | Type of reservation, see [reservation-type](#reservation-type) |
332-
| quoted_trip_start_time | Timestamp | Required | Time the trip was estimated or scheduled to start, that was provided to the passenger |
333-
| requested_trip_start_location | `{ lat: number, lng: number }` | Conditionally Required | Location where the customer requested the trip to start (required if this is within jurisdictional boundaries) |
334-
| dispatch_time | Timestamp | Conditionally Required | Time the vehicle was dispatched to the customer (required if trip was dispatched) |
335-
| trip_start_time | Timestamp | Conditionally Required | Time the trip started (required if trip started) |
336-
| trip_end_time | Timestamp | Conditionally Required | Time the trip ended (required if trip was completed) |
337-
| distance | Float | Conditionally Required | Total distance of the trip in meters (required if trip was completed) |
338-
| cancellation_reason | string | Conditionally Required | The reason why a *driver* cancelled a reservation. (required if a driver cancelled a trip, and a `driver_cancellation` event_type was part of the trip) |
339-
| fare | [Fare](#fare) | Conditionally Required | Fare for the trip (required if trip was completed) |
340-
| accessibility_options | Enum[] | Optional | The **union** of any accessibility options requested, and used. E.g. if the passenger requests a vehicle with `wheelchair_accessible`, but doesn’t utilize the features during the trip, the trip payload will include `accessibility_options: ['wheelchair_accessible']`. See [accessibility-options][accessibility-options] |
341-
342-
**Endpoint:** `/trip_metadata`
295+
**Endpoint:** `/trips`
343296
**Method:** `POST`
344297
**[Beta feature][beta]:** Yes (as of 2.0.0)
345-
**Request Body**: A [Trip Metadata](#trip_metadata) object
298+
**Payload:** `{ "trips": [] }`, an array of [Trips](#trip-data)
299+
300+
Body Params:
301+
302+
| Field | Type | Required/Optional | Field Description |
303+
| ------------- | ------------------------------ | ----------------- | -------------------------------------------------------------------------------------- |
304+
| `trips` | [Trip](#trip-data)[] | Required | Array of trips for one or more vehicles. |
305+
306+
200 Success Response:
307+
308+
| Field | Type | Field Description |
309+
| ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
310+
| `success` | Integer | Number of successfully written telemetry data points. |
311+
| `total` | Integer | Total number of provided points. |
312+
| `failures` | [Telemetry](#telemetry-data)[] | Array of failed telemetry for zero or more vehicles (empty if all successful). |
346313

347-
201 Success Response:
348-
Payload which was POST'd
349314

350315
400 Failure Response:
351316
| `error` | `error_description` | `error_details`[] |
@@ -365,6 +330,8 @@ Payload which was POST'd
365330
[propulsion-types]: /general-information.md#propulsion-types
366331
[responses]: /general-information.md#responses
367332
[stops]: /general-information.md#stops
333+
[telemetry-data]: /general-information.md#telemetry-data
334+
[trip-data]: /general-information.md#trips
368335
[toc]: #table-of-contents
369336
[ts]: /general-information.md#timestamps
370337
[vehicle-types]: /general-information.md#vehicle-types

‎general-information.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -241,6 +241,28 @@ A Trip is defined by the following structure:
241241
| `reservation_time` | Timestamp | Required | Time the customer *requested* a reservation |
242242
| `reservation_type` | Enum | Required | Type of reservation, see [reservation-type](#reservation-type) |
243243

244+
WORK IN PROGRESS - THIS WAS FROM THE AGENCY PROPOSAL
245+
246+
| Field | Type | Required/Optional | Field Description |
247+
|-------------------------------|--------------------------------|------------------------| ----------------- |
248+
| trip_id | UUID | Required | UUID for the trip this payload pertains to |
249+
| trip_type | Enum | Optional | The type of the trip |
250+
| trip_attributes | `{ [String]: String}` | Optional | Trip attributes, given as mode-specific key-value pairs |
251+
| provider_id | UUID | Required | Provider which managed this trip |
252+
| reservation_method | Enum | Required | Way the customer created their reservation, see [reservation-method](#reservation-method) |
253+
| reservation_time | Timestamp | Required | Time the customer *requested* a reservation |
254+
| reservation_type | Enum | Required | Type of reservation, see [reservation-type](#reservation-type) |
255+
| quoted_trip_start_time | Timestamp | Required | Time the trip was estimated or scheduled to start, that was provided to the passenger |
256+
| requested_trip_start_location | `{ lat: number, lng: number }` | Conditionally Required | Location where the customer requested the trip to start (required if this is within jurisdictional boundaries) |
257+
| dispatch_time | Timestamp | Conditionally Required | Time the vehicle was dispatched to the customer (required if trip was dispatched) |
258+
| trip_start_time | Timestamp | Conditionally Required | Time the trip started (required if trip started) |
259+
| trip_end_time | Timestamp | Conditionally Required | Time the trip ended (required if trip was completed) |
260+
| distance | Float | Conditionally Required | Total distance of the trip in meters (required if trip was completed) |
261+
| cancellation_reason | string | Conditionally Required | The reason why a *driver* cancelled a reservation. (required if a driver cancelled a trip, and a `driver_cancellation` event_type was part of the trip) |
262+
| fare | [Fare](#fare) | Conditionally Required | Fare for the trip (required if trip was completed) |
263+
| accessibility_options | Enum[] | Optional | The **union** of any accessibility options requested, and used. E.g. if the passenger requests a vehicle with `wheelchair_accessible`, but doesn’t utilize the features during the trip, the trip payload will include `accessibility_options: ['wheelchair_accessible']`. See [accessibility-options][accessibility-options] |
264+
265+
244266
[Top][toc]
245267

246268
## Reservation Type

0 commit comments

Comments
 (0)