Skip to content

Commit 345f145

Browse files
schnuerleschnuerle
authored
Merge branch 'dev' into feature-agency-provider-api-alignment
2 parents 503a5b2 + 43a9986 commit 345f145

9 files changed

Lines changed: 129 additions & 103 deletions

File tree

‎agency/README.md‎

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@ This specification contains a collection of RESTful APIs used to specify the dig
1717
* [Vehicle - Update](#vehicle---update)
1818
* [Vehicle - Events](#vehicle---event)
1919
* [Vehicle - Telemetry](#vehicle---telemetry)
20-
* [Telemetry Data](#telemetry-data)
2120
* [Stops](#stops)
2221

2322
## General information
@@ -164,16 +163,9 @@ Body Params:
164163
| ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
165164
| `success` | Integer | Number of successfully written telemetry data points. |
166165
| `total` | Integer | Total number of provided points. |
167-
| `failures` | [Telemetry](#telemetry-data)[] | Array of failed telemetry for zero or more vehicles (empty if all successful). |
166+
| `failures` | [Telemetry Error](#telemetry-error)[] | Array of errors including the failed telemetry data and error details (empty if all successful). |
168167

169-
400 Failure Response:
170-
171-
| `error` | `error_description` | `error_details`[] |
172-
| --------------- | ------------------------------------ | --------------------------------- |
173-
| `bad_param` | A validation error occurred. | Array of parameters with errors |
174-
| `invalid_data` | None of the provided data was valid. | |
175-
| `missing_param` | A required parameter is missing. | Array of missing parameters |
176-
| `unregistered` | Some of the devices are unregistered | Array of unregistered `device_id` |
168+
Alway returns 200. Any failed data is detailed in the `failures` array of the response.
177169

178170
[Top][toc]
179171

@@ -302,3 +294,4 @@ Body Params:
302294
[vehicle-event-types]: /modes/event_types.md
303295
[vehicle-event-data]: /general-information.md#event-data
304296
[versioning]: /general-information.md#versioning
297+
[error-message]: /general-information.md#error-messages

‎general-information.md‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ For the purposes of this specification, the intersection of two geographic datat
8484

8585
## Geography-Driven Events
8686

87-
**[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.0)*. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/670)
87+
**[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.0)*. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/670)
8888

8989
Geography-Driven Events (GDE) is an MDS feature for Agencies to perform complete Policy compliance monitoring without precise location data. Geography-Driven Events describe individual vehicles in realtime – not just aggregate data. However, rather than receiving the exact location of a vehicle, Agencies receive information about the vehicle's current geographic region. The regions used for Geography-Driven Events correspond to the Geographies in an Agency's current Policy. In this way, the data-shared using Geography-Driven Events is matched to an Agency's particular regulatory needs.
9090

@@ -104,7 +104,7 @@ Here's how it works in practice:
104104

105105
*Agency adds rule disallowing parking on waterfront path, begins receiving data on events within area.*
106106

107-
Agencies that wish to use Geography-Driven Events do so by requiring a new `event_geographies` field in status events. When an Agency is using Geography-Driven Events, Providers must emit a new `changed_geographies` status event whenever a vehicle in a trip enters or leaves a Geography managed by a Policy.
107+
Agencies that wish to use Geography-Driven Events do so by requiring a new `event_geographies` field in status events. When an Agency is using Geography-Driven Events, Providers must emit a new `changed_geographies` status event whenever a vehicle in a trip enters or leaves a Geography managed by a Policy.
108108

109109
During the Beta period for this feature, location and telemetry data remain required fields. This allows Agencies to test Geography-Driven Events, measuring its accuracy and efficacy against regulatory systems based on precise location data. After the beta period, if Geography-Driven Events is deemed by the OMF to be accurate and effective, the specification will evolve to allow cities to use Geography-Driven Events in lieu of location or telemetry data.
110110

@@ -172,6 +172,23 @@ MDS uses Version 1 UUIDs by default. Version 4 UUIDs may be used where noted.
172172

173173
[Top][toc]
174174

175+
## Trips
176+
177+
Counting trips is a common analysis with MDS data, but in some instances when
178+
a user rents a vehicle the rental may end up being very short because the
179+
vehicle is unusable or because the customer changes their mind.
180+
To facilitate a common definition of trips for analysis, MDS defines a trip
181+
as a user taking control of a vehicle for 60 seconds or more.
182+
If a user reserves a vehicle and cancels before taking control of the vehicle
183+
that reservation does not count as a trip, nor does a user taking control of
184+
the vehicle and canceling or ending the trip in under 60 seconds.
185+
186+
Providers are still expected to report all trips and trip related events in
187+
all MDS endpoints, but parties may use this definition as a shared reference
188+
at the recommendation of the MDS community when analysing trips.
189+
190+
[Top][toc]
191+
175192
## Vehicle States
176193

177194
See new location within [vehicle states](/modes/vehicle_states.md) in [modes](/modes#vehicle-states).

‎modes/car-share.md‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -165,8 +165,8 @@ Valid car share vehicle states are
165165
- `reserved`
166166
- `on_trip`
167167
- `stopped`
168+
- `non_contactable`
168169
- `elsewhere`
169-
- `unknown`
170170

171171
See [Vehicle States][vehicle-states] for descriptions.
172172

@@ -217,29 +217,29 @@ This is the list of `vehicle_state` and `event_type` pairings that constitute th
217217
| `available` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left jurisdictional boundaries while available for-hire |
218218
| `available` | `non_operational` | N/A | `service_end` | The vehicle has went out of service (is unavailable for-hire) |
219219
| `available` | `reserved` | `reserved` | `reserve` | The vehicle was reserved by a passenger |
220-
| `available` | `unknown` | N/A | `comms_lost` | The vehicle has went out of comms while available for-use |
220+
| `available` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while available for-use |
221221
| `elsewhere` | `available` | N/A | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while available for-hire |
222222
| `elsewhere` | `non_operational` | N/A | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while not operating commercially |
223223
| `elsewhere` | `on_trip` | `on_trip` | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while on a trip |
224224
| `elsewhere` | `reserved` | N/A | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while reserved by a customer |
225-
| `elsewhere` | `unknown` | N/A | `comms_lost` | The vehicle has went out of comms while outside of jurisdictional boundaries |
225+
| `elsewhere` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while outside of jurisdictional boundaries |
226226
| `non_operational` | `available` | N/A | `service_start` | The vehicle has went into service (is available for-hire) |
227227
| `non_operational` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left jurisdictional boundaries while not operating commercially |
228228
| `non_operational` | `removed` | N/A | `decommissioned` | The vehicle has been removed from the Provider's fleet |
229229
| `non_operational` | `removed` | N/A | `maintenance_start` | The vehicle has entered the depot for maintenance |
230-
| `non_operational` | `unknown` | N/A | `comms_lost` | The vehicle has went out of comms while not operating commercially |
230+
| `non_operational` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while not operating commercially |
231231
| `on_trip` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left jurisdictional boundaries while on a trip |
232232
| `on_trip` | `stopped` | `stopped` | `trip_stop` | The vehicle has stopped while on a trip |
233-
| `on_trip` | `unknown` | N/A | `comms_lost` | The vehicle has gone out of comms while on a trip |
233+
| `on_trip` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while on a trip |
234234
| `removed` | `non_operational` | N/A | `maintenance_end` | The vehicle has left the depot |
235235
| `removed` | `non_operational` | N/A | `recommissioned` | The vehicle has been re-added to the Provider's fleet after being previously `decommissioned` |
236-
| `removed` | `unknown` | N/A | `comms_lost` | The vehicle has gone out of comms while removed |
236+
| `removed` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while removed |
237237
| `reserved` | `available` | N/A | `driver_cancellation` | The driver has canceled the reservation |
238238
| `reserved` | `available` | N/A | `passenger_cancellation` | The passenger has canceled the reservation |
239239
| `reserved` | `available` | N/A | `provider_cancellation` | The provider has canceled the reservation |
240240
| `reserved` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left the jurisdiction while in a reservation |
241241
| `reserved` | `stopped` | `stopped` | `reserve_stop` | The vehicle has stopped to pick up the passenger |
242-
| `reserved` | `unknown` | N/A | `comms_lost` | The vehicle went out of comms while being reserved by a passenger |
242+
| `reserved` | `non_contactable` | N/A | `comms_lost` | The vehicle went out of comms while being reserved by a passenger |
243243
| `stopped` | `available` | N/A | `driver_cancellation` | The driver has canceled the trip while either waiting for the passenger, or dropping them off |
244244
| `stopped` | `available` | N/A | `passenger_cancellation` | The passenger has canceled the trip while the vehicle is waiting to pick them up, or they are being dropped off |
245245
| `stopped` | `available` | N/A | `provider_cancellation` | The provider has canceled the trip while the vehicle is waiting for a passenger, or dropping them off |
@@ -252,14 +252,14 @@ This is the list of `vehicle_state` and `event_type` pairings that constitute th
252252
| `stopped` | `stopped` | `stopped` | `fueling_end` | End fueling the device with physical fuel |
253253
| `stopped` | `stopped` | `stopped` | `remote_start` | Remotely start the engine while vehicle is stopped, usually to charge battery or warm up |
254254
| `stopped` | `stopped` | `stopped` | `remote_end` | Remotely stop the engine while vehicle is already stopped |
255-
| `stopped` | `unknown` | N/A | `comms_lost` | The vehicle has went out of comms while stopped |
256-
| `unknown` | `available` | N/A | `comms_restored` | The vehicle has come back into comms while available for-hire |
257-
| `unknown` | `elsewhere` | N/A | `comms_restored` | The vehicle has come back into comms while outside of jurisdictional boundaries |
258-
| `unknown` | `non_operational` | N/A | `comms_restored` | The vehicle has come back into comms while not operating commercially |
259-
| `unknown` | `on_trip` | `on_trip` | `comms_restored` | The vehicle has come back into comms while on a trip |
260-
| `unknown` | `removed` | N/A | `comms_restored` | The vehicle has come back into comms while removed |
261-
| `unknown` | `reserved` | `reserved` | `comms_restored` | The vehicle has come back into comms while reserved by a passenger |
262-
| `unknown` | `stopped` | `stopped` | `comms_restored` | The vehicle has come back into comms while stopped |
255+
| `stopped` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while stopped |
256+
| `non_contactable` | `available` | N/A | `comms_restored` | The vehicle has come back into comms while available for-hire |
257+
| `non_contactable` | `elsewhere` | N/A | `comms_restored` | The vehicle has come back into comms while outside of jurisdictional boundaries |
258+
| `non_contactable` | `non_operational` | N/A | `comms_restored` | The vehicle has come back into comms while not operating commercially |
259+
| `non_contactable` | `on_trip` | `on_trip` | `comms_restored` | The vehicle has come back into comms while on a trip |
260+
| `non_contactable` | `removed` | N/A | `comms_restored` | The vehicle has come back into comms while removed |
261+
| `non_contactable` | `reserved` | `reserved` | `comms_restored` | The vehicle has come back into comms while reserved by a passenger |
262+
| `non_contactable` | `stopped` | `stopped` | `comms_restored` | The vehicle has come back into comms while stopped |
263263

264264
[Top][toc]
265265

0 commit comments

Comments
 (0)