Skip to content

Commit 8651484

Browse files
marie-xmarie-x
committed
Agency refactoring, WIP
1 parent 85930ae commit 8651484

2 files changed

Lines changed: 62 additions & 62 deletions

File tree

‎agency/README.md‎

Lines changed: 19 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -148,47 +148,41 @@ _No content returned if no vehicle matching `device_id` is found._
148148

149149
[Top][toc]
150150

151-
## Vehicle - Event
151+
## Vehicles - Events
152152

153-
The vehicle `/event` endpoint allows the Provider to control the state of the vehicle.
153+
The vehicle `/events` endpoint allows the Provider to submit events describing the state changes of multiple vehicles.
154154

155-
Endpoint: `/vehicles/{device_id}/event`
156-
Method: `POST`
157-
158-
Path Params:
155+
Endpoint: `/vehicles/events`
159156

160-
| Field | Type | Required/Optional | Field Description |
161-
| ------------ | ---- | ----------------- | ---------------------------------------- |
162-
| `device_id` | UUID | Required | ID used in [Register](#vehicle---register) |
157+
Method: `POST`
163158

164159
Body Params:
165160

166161
| Field | Type | Required/Optional | Field Description |
167162
|-----------------|------------------------------|------------------------|------------------------------------------------------------------------------------------------------------|
168-
| `vehicle_state` | Enum | Required | see [Vehicle States][vehicle-states] |
169-
| `event_types` | Enum[] | Required | see [Vehicle Events][vehicle-events] |
170-
| `timestamp` | [timestamp][ts] | Required | Date of last event update |
171-
| `telemetry` | [Telemetry](#telemetry-data) | Required | Single point of telemetry |
172-
| `event_geographies` | UUID[] | Optional | **[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.0)*. Array of Geography UUIDs consisting of every Geography that contains the location of the event. See [Geography Driven Events][geography-driven-events]. Required if `telemetry` is not present. |
173-
| `trip_id` | UUID | Conditionally required | UUID provided by Operator to uniquely identify the trip. See `trip_id` requirements for each [mode][modes]. |
163+
| `data` | [EventData](#vehicle-event-data)[] | Required | An array of [Vehicle Event Data](#vehicle-event-data) objects. |
174164

175-
201 Success Response:
165+
200 Success Response:
176166

177-
| Field | Type | Field Description |
178-
| ------------ | ---- | ----------------------------------------------------------------------------- |
179-
| `device_id` | UUID | UUID provided by Operator to uniquely identify a vehicle |
167+
| Field | Type | Field Description |
168+
| ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
169+
| `success` | Integer | Number of successfully written events. |
170+
| `total` | Integer | Total number of provided events. |
171+
| `failures` | [Event](#vehicle-event-data)[] | Array of invalid events (empty if all successful). |
172+
173+
(?) Should we have a description/error-code for each failure in the `failures`?
180174

181175
400 Failure Response:
182176

183177
| `error` | `error_description` | `error_details`[] |
184178
| ------------------- | ------------------------------- | ------------------------------- |
185179
| `bad_param` | A validation error occurred | Array of parameters with errors |
186180
| `missing_param` | A required parameter is missing | Array of missing parameters |
187-
| `unregistered` | Vehicle is not registered | |
181+
| `unregistered` | Some of the devices are not registered | |
188182

189183
[Top][toc]
190184

191-
## Vehicle - Telemetry
185+
## Vehicles - Telemetry
192186

193187
The vehicle `/telemetry` endpoint allows a Provider to send vehicle telemetry data in a batch for any number of vehicles in the fleet.
194188

@@ -289,50 +283,15 @@ If `stop_id` is specified, `GET` will return an array with a single stop record,
289283

290284
[Top][toc]
291285

292-
## Reservation Type
293-
294-
The reservation type enum expresses the urgency of a given reservation. This can be useful when attempting to quantify metrics around trips: for example, computing passenger wait-time. In the `on_demand` case, passenger wait-time may be quantified by the delta between the `reservation_time`, and the pick-up time; however, in the `scheduled` case, the wait time may be quantified based on the delta between the `scheduled_trip_start_time` found in the Trips payload, and the actual `trip_start_time`.
295-
296-
| `reservation_type` | Description |
297-
|--------------------|------------------------------------------------------------------------|
298-
| `on_demand` | The passenger requested the vehicle as soon as possible |
299-
| `scheduled` | The passenger requested the vehicle for a scheduled time in the future |
300-
301-
[Top][toc]
302-
303-
## Reservation Method
304-
305-
The reservation method enum describes the different ways in which a passenger can create their reservation.
306-
307-
| `reservation_method` | Description |
308-
|----------------------|-----------------------------------------------------------|
309-
| `app` | Reservation was made through an application (mobile/web) |
310-
| `street_hail` | Reservation was made by the passenger hailing the vehicle |
311-
| `phone_dispatch` | Reservation was made by calling the dispatch operator |
312-
313-
[Top][toc]
314-
315-
## Fare
316-
317-
The Fare object describes a fare for a Trip.
318-
319-
| Field | Type | Required/Optional | Field Description |
320-
|-----------------|-----------------------|-------------------|-----------------------------------------------------------------------------------------|
321-
| quoted_cost | Float | Required | Cost quoted to the customer at the time of booking |
322-
| actual_cost | Float | Required | Actual cost after a trip was completed |
323-
| components | `{ [string]: float }` | Optional | Breakdown of the different fees that composed a fare, e.g. tolls |
324-
| currency | string | Required | ISO 4217 currency code |
325-
| payment_methods | `string[]` | Optional | Breakdown of different payment methods used for a trip, e.g. cash, card, equity_program |
326-
327-
[Top][toc]
328-
329286
## Trip Metadata
330287

331288
The Trips endpoint serves two purposes:
332289

333290
* 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.
334291
* 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.
335292

293+
WORK IN PROGRESS - THIS WILL BE UNIFIED WITH TRIP DATA IN `general_information`
294+
336295
| Field | Type | Required/Optional | Field Description |
337296
|-------------------------------|--------------------------------|------------------------| ----------------- |
338297
| trip_id | UUID | Required | UUID for the trip this payload pertains to |
@@ -382,5 +341,6 @@ Payload which was POST'd
382341
[ts]: /general-information.md#timestamps
383342
[vehicle-types]: /general-information.md#vehicle-types
384343
[vehicle-states]: /modes/vehicle_states.md
385-
[vehicle-events]: /modes/event_types.md
344+
[vehicle-event-types]: /modes/event_types.md
345+
[vehicle-event-data]: /general-information.md#event-data
386346
[versioning]: /general-information.md#versioning

‎general-information.md‎

Lines changed: 43 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -236,9 +236,47 @@ A Trip is defined by the following structure:
236236
| `accuracy` | Integer | Required | The approximate level of accuracy, in meters, of `Points` within `route` |
237237
| `publication_time` | [timestamp][ts] | Optional | Date/time that trip became available through the trips endpoint |
238238
| `parking_verification_url` | String | Optional | A URL to a photo (or other evidence) of proper vehicle parking |
239-
| `standard_cost` | Integer | Optional | The cost, in the currency defined in `currency`, that it would cost to perform that trip in the standard operation of the System (see [Costs & Currencies][costs-and-currencies]) |
240-
| `actual_cost` | Integer | Optional | The actual cost, in the currency defined in `currency`, paid by the customer of the *mobility as a service* provider (see [Costs & Currencies][costs-and-currencies]) |
241-
| `currency` | String | Optional, USD cents is implied if null.| An [ISO 4217 Alphabetic Currency Code][iso4217] representing the currency of the payee (see [Costs & Currencies][costs-and-currencies]) |
239+
| `fare` | [Fare](#fare) | Conditionally Required | Fare for the trip (required if trip was completed) |
240+
| `reservation_method` | Enum | Required | Way the customer created their reservation, see [reservation-method](#reservation-method) |
241+
| `reservation_time` | Timestamp | Required | Time the customer *requested* a reservation |
242+
| `reservation_type` | Enum | Required | Type of reservation, see [reservation-type](#reservation-type) |
243+
244+
[Top][toc]
245+
246+
## Reservation Type
247+
248+
The reservation type enum expresses the urgency of a given reservation. This can be useful when attempting to quantify metrics around trips: for example, computing passenger wait-time. In the `on_demand` case, passenger wait-time may be quantified by the delta between the `reservation_time`, and the pick-up time; however, in the `scheduled` case, the wait time may be quantified based on the delta between the `scheduled_trip_start_time` found in the Trips payload, and the actual `trip_start_time`.
249+
250+
| `reservation_type` | Description |
251+
|--------------------|------------------------------------------------------------------------|
252+
| `on_demand` | The passenger requested the vehicle as soon as possible |
253+
| `scheduled` | The passenger requested the vehicle for a scheduled time in the future |
254+
255+
[Top][toc]
256+
257+
## Reservation Method
258+
259+
The reservation method enum describes the different ways in which a passenger can create their reservation.
260+
261+
| `reservation_method` | Description |
262+
|----------------------|-----------------------------------------------------------|
263+
| `app` | Reservation was made through an application (mobile/web) |
264+
| `street_hail` | Reservation was made by the passenger hailing the vehicle |
265+
| `phone_dispatch` | Reservation was made by calling the dispatch operator |
266+
267+
[Top][toc]
268+
269+
## Fare
270+
271+
The Fare object describes a fare for a Trip.
272+
273+
| Field | Type | Required/Optional | Field Description |
274+
|-----------------|-----------------------|-------------------|-----------------------------------------------------------------------------------------|
275+
| quoted_cost | Float | Optional | Cost quoted to the customer at the time of booking, if available |
276+
| actual_cost | Float | Required | Actual cost after a trip was completed |
277+
| components | `{ [string]: float }` | Optional | Breakdown of the different fees that composed a fare, e.g. tolls |
278+
| currency | string | Required | ISO 4217 currency code |
279+
| payment_methods | `string[]` | Optional | Breakdown of different payment methods used for a trip, e.g. cash, card, equity_program |
242280

243281
[Top][toc]
244282

@@ -265,6 +303,8 @@ Events represent changes in vehicle status.
265303

266304
(?) Do we still want `event_geographies`?
267305

306+
(?) Add `journey_id`(s)?
307+
268308
### Event Times
269309

270310
Because of the unreliability of device clocks, the Provider is unlikely to know with total confidence what time an event occurred at. However, Providers are responsible for constructing as accurate a timeline as possible. Most importantly, the order of the timestamps for a particular device's events must reflect the Provider's best understanding of the order in which those events occurred.

0 commit comments

Comments
 (0)