You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: agency/README.md
+36-28Lines changed: 36 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,18 +10,21 @@ This specification contains a collection of RESTful APIs used to specify the dig
10
10
11
11
*[General Information](#general-information)
12
12
*[Versioning](#versioning)
13
+
*[Modes](#modes)
13
14
*[Responses and Error Messages](#responses-and-error-messages)
14
15
*[Authorization](#authorization)
15
16
*[GBFS](#gbfs)
16
17
*[Vehicles](#vehicles)
17
18
*[Vehicle - Register](#vehicle---register)
18
19
*[Vehicle - Update](#vehicle---update)
19
-
*[Vehicle - Events](#vehicle---event)
20
-
*[Vehicle - Telemetry](#vehicle---telemetry)
20
+
*[Vehicles - Events](#vehicles---events)
21
+
*[Vehicles - Telemetry](#vehicles---telemetry)
22
+
*[Trips](#trips)
21
23
*[Stops](#stops)
22
24
*[Stops - Register](#stops---register)
23
25
*[Stops - Update](#stops---update)
24
26
*[Stops - Readback](#stops---readback)
27
+
*[Reports](#Reports)
25
28
26
29
## General information
27
30
@@ -108,6 +111,8 @@ The `/vehicles` registration endpoint is used to register vehicles for use in th
108
111
109
112
See [Bulk Responses](#bulk-responses)
110
113
114
+
[Top][toc]
115
+
111
116
### Vehicle Register Error Codes:
112
117
113
118
|`error`|`error_description`|`error_details`[]|
@@ -185,6 +190,31 @@ See [Bulk Responses](#bulk-responses)
185
190
186
191
[Top][toc]
187
192
193
+
## Trips
194
+
195
+
The Trips endpoint serves two purposes:
196
+
197
+
* 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.
198
+
* 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.
|`bad_param`| A validation error occurred | Array of parameters with errors |
213
+
|`missing_param`| A required parameter is missing | Array of missing parameters |
214
+
|`unregistered`| This `device_id` is unregistered ||
215
+
216
+
[Top][toc]
217
+
188
218
## Stops
189
219
190
220
### Stops - Register
@@ -209,6 +239,8 @@ See [Bulk Responses](#bulk-responses)
209
239
210
240
403 Unauthorized Response:
211
241
242
+
**None**
243
+
212
244
[Top][toc]
213
245
214
246
### Stops - Update
@@ -235,6 +267,8 @@ See [Bulk Responses](#bulk-responses)
235
267
|`missing_param`| A required parameter is missing | Array of missing parameters |
236
268
|`unregistered`| No stop with `stop_id` is already registered ||
237
269
270
+
[Top][toc]
271
+
238
272
### Stops - Readback
239
273
240
274
**Endpoint:**`/stops/:stop_id`
@@ -251,32 +285,6 @@ Path Params:
251
285
252
286
If `stop_id` is specified, `GET` will return an array with a single stop record, otherwise it will be a list of all stop records.
253
287
254
-
[Top][toc]
255
-
256
-
## Trips
257
-
258
-
The Trips endpoint serves two purposes:
259
-
260
-
* 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.
261
-
* 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.
@@ -52,6 +49,8 @@ This specification uses data types including timestamps, UUIDs, and vehicle stat
52
49
53
50
Versioning must be implemented as specified in the [Versioning section][versioning].
54
51
52
+
[Top][toc]
53
+
55
54
### Modes
56
55
57
56
MDS is intended to be used for multiple transportation modes, including its original micromobility (e-scooters, bikes, etc.) as well as additional modes such as taxis and delivery bots. A given `provider_id` shall be associated with a single mobility [mode], so that the mode does not have to be specified in each data structure and API call. A provider implementing more than one mode shall [register](/README.md#providers-using-mds) a `provider_id` for each mode.
@@ -160,6 +159,33 @@ For Timestamps, Vehicle Types, Propulsion Types, UUIDs, Costs, and Currencies, r
160
159
161
160
[Top][toc]
162
161
162
+
## Vehicles
163
+
164
+
The `/vehicles` is a near-realtime endpoint and returns the current status of vehicles in an agency's [Jurisdiction](/general-information.md#definitions) and/or area of agency responsibility. All vehicles that are currently in any [`vehicle_state`][vehicle-states] should be returned in this payload. Since all states are returned, care should be taken to filter out states not in the [PROW](/general-information.md#definitions) if doing vehicle counts. For the states `elsewhere` and `removed` which include vehicles not in the [PROW](/general-information.md#definitions) but provide some operational clarity for agencies, these must only persist in the feed for 90 minutes before being removed.
165
+
166
+
As with other MDS APIs, `/vehicles` is intended for use by regulators, not by the general public. `/vehicles` can be deployed by providers as a standalone MDS endpoint for agencies without requiring the use of other endpoints, due to the [modularity](/README.md#modularity) of MDS. See our [MDS Vehicles Guide](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Vehicles) for how this compares to GBFS `/free_bike_status`. Note that using authenticated `/vehicles` does not replace the role of a public [GBFS][gbfs] feed in enabling consumer-facing applications. If a provider is using both `/vehicles` and GBFS endpoints, the `/vehicles` endpoint should be considered source of truth regarding an agency's compliance checks.
167
+
168
+
In addition to the standard [Provider payload wrapper](#response-format), responses from this endpoint should contain the last update timestamp and amount of time until the next update in accordance with the [Data Latency Requirements][data-latency]:
169
+
170
+
```json
171
+
{
172
+
"version": "x.y.z",
173
+
"data": {
174
+
"vehicles": []
175
+
},
176
+
"last_updated": "12345",
177
+
"ttl": "12345"
178
+
}
179
+
```
180
+
181
+
**Endpoint:**`/vehicles`
182
+
**Method:**`GET`
183
+
**[Beta feature][beta]:** No (as of 1.2.0)
184
+
**Schema:**[`vehicles` schema][vehicles-schema]
185
+
**`data` Payload:**`{ "vehicles": [] }`, an array of [Vehicle](vehicle) objects
186
+
187
+
[Top][toc]
188
+
163
189
## Trips
164
190
165
191
A [trip][trips-general-info] represents a journey taken by a *mobility as a service* customer with
@@ -186,6 +212,8 @@ The `/trips` API should allow querying trips with the following query parameters
186
212
187
213
Without an `end_time` query parameter, `/trips` shall return a `400 Bad Request` error.
188
214
215
+
[Top][toc]
216
+
189
217
### Trips - Responses
190
218
191
219
The API's response will depend on the hour queried and the status of data
@@ -274,6 +302,8 @@ Unless stated otherwise by the municipality, this endpoint must return only thos
274
302
**Schema:**[`telemetry` schema][telemetry-schema]
275
303
**`data` Payload:**`{ "telemetry": [] }`, an array of `telemetry` objects
276
304
305
+
[Top][toc]
306
+
277
307
### Telemetry - Query Parameters
278
308
279
309
| Parameter | Format | Expected Output |
@@ -364,33 +394,6 @@ Should either side of the requested time range be greater than 2 weeks before th
364
394
365
395
[Top][toc]
366
396
367
-
## Vehicles
368
-
369
-
The `/vehicles` is a near-realtime endpoint and returns the current status of vehicles in an agency's [Jurisdiction](/general-information.md#definitions) and/or area of agency responsibility. All vehicles that are currently in any [`vehicle_state`][vehicle-states] should be returned in this payload. Since all states are returned, care should be taken to filter out states not in the [PROW](/general-information.md#definitions) if doing vehicle counts. For the states `elsewhere` and `removed` which include vehicles not in the [PROW](/general-information.md#definitions) but provide some operational clarity for agencies, these must only persist in the feed for 90 minutes before being removed.
370
-
371
-
As with other MDS APIs, `/vehicles` is intended for use by regulators, not by the general public. `/vehicles` can be deployed by providers as a standalone MDS endpoint for agencies without requiring the use of other endpoints, due to the [modularity](/README.md#modularity) of MDS. See our [MDS Vehicles Guide](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Vehicles) for how this compares to GBFS `/free_bike_status`. Note that using authenticated `/vehicles` does not replace the role of a public [GBFS][gbfs] feed in enabling consumer-facing applications. If a provider is using both `/vehicles` and GBFS endpoints, the `/vehicles` endpoint should be considered source of truth regarding an agency's compliance checks.
372
-
373
-
In addition to the standard [Provider payload wrapper](#response-format), responses from this endpoint should contain the last update timestamp and amount of time until the next update in accordance with the [Data Latency Requirements][data-latency]:
374
-
375
-
```json
376
-
{
377
-
"version": "x.y.z",
378
-
"data": {
379
-
"vehicles": []
380
-
},
381
-
"last_updated": "12345",
382
-
"ttl": "12345"
383
-
}
384
-
```
385
-
386
-
**Endpoint:**`/vehicles`
387
-
**Method:**`GET`
388
-
**[Beta feature][beta]:** No (as of 1.2.0)
389
-
**Schema:**[`vehicles` schema][vehicles-schema]
390
-
**`data` Payload:**`{ "vehicles": [] }`, an array of [Vehicle](vehicle) objects
391
-
392
-
[Top][toc]
393
-
394
397
## Stops
395
398
396
399
Stop information should be updated on a near-realtime basis by providers who operate _docked_ mobility devices in a given municipality.
@@ -424,6 +427,8 @@ Reports are information that providers can send back to agencies containing aggr
424
427
425
428
The authenticated reports are monthly, historic flat files that may be pre-generated by the provider.
0 commit comments