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
+82-44Lines changed: 82 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,11 +15,12 @@ This specification contains a collection of RESTful APIs used to specify the dig
15
15
*[Authorization](#authorization)
16
16
*[GBFS](#gbfs)
17
17
*[Vehicles](#vehicles)
18
+
*[Vehicle - Status](#vehicle---status)
18
19
*[Vehicle - Register](#vehicle---register)
19
20
*[Vehicle - Update](#vehicle---update)
20
-
*[Vehicles - Events](#vehicles---events)
21
-
*[Vehicles - Telemetry](#vehicles---telemetry)
22
21
*[Trips](#trips)
22
+
*[Telemetry](#telemetry)
23
+
*[Events](#events)
23
24
*[Stops](#stops)
24
25
*[Stops - Register](#stops---register)
25
26
*[Stops - Update](#stops---update)
@@ -67,10 +68,11 @@ See the [GBFS Requirement](/README.md#gbfs-requirement) language for more detail
67
68
68
69
## Vehicles
69
70
70
-
The `/vehicles` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles. Providers can only retrieve data for vehicles in their registered fleet.
71
+
The `/vehicles` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles. Providers can only retrieve data for vehicles in their registered fleet. Contains vehicle properties that do not change often.
71
72
72
-
Endpoint: `/vehicles/{device_id}`
73
-
Method: `GET`
73
+
**Endpoint**: `/vehicles/{device_id}`
74
+
**Method:**`POST`
75
+
**Payload:** An array of [Vehicles](/data-types.md#vehicles)
74
76
75
77
Path Params:
76
78
@@ -100,17 +102,53 @@ _No content returned on vehicle not found._
100
102
101
103
[Top][toc]
102
104
103
-
## Vehicle - Register
105
+
### Vehicle - Status
106
+
107
+
The `/vehicles/status` endpoint returns information about the specified vehicle (if a device_id is provided) or a list of known vehicles current state. Providers can only retrieve data for vehicles in their registered fleet. Contains specific vehicle properties that are updated frequently.
108
+
109
+
**Endpoint**: `/vehicles/status/{device_id}`
110
+
**Method:**`POST`
111
+
**Payload:** An array of [Vehicles](/data-types.md#vehicle-status) objects
112
+
113
+
Path Params:
114
+
115
+
| Param | Type | Required/Optional | Description |
|`device_id`| UUID | Optional | If provided, retrieve the specified vehicle |
118
+
119
+
200 Success Response:
120
+
121
+
If `device_id` is specified, `GET` will return an array with a vehicle status record, otherwise it will be a list of vehicle records with pagination details per the [JSON API](https://jsonapi.org/format/#fetching-pagination) spec:
122
+
123
+
```json
124
+
{
125
+
"vehicles_status": [ ... ]
126
+
"links": {
127
+
"first": "https://...",
128
+
"last": "https://...",
129
+
"prev": "https://...",
130
+
"next": "https://..."
131
+
}
132
+
}
133
+
```
134
+
135
+
404 Failure Response:
136
+
137
+
_No content returned on vehicle not found._
138
+
139
+
[Top][toc]
140
+
141
+
### Vehicle - Register
104
142
105
143
The `/vehicles` registration endpoint is used to register vehicles for use in the Agency's jurisdiction.
106
144
107
145
**Endpoint**: `/vehicles`
108
146
**Method:**`POST`
109
-
**Payload:** An array of [Vehicles](#vehicle)
147
+
**Payload:** An array of [Vehicles](/data-types.md#vehicles)
110
148
111
149
200 Success Response:
112
150
113
-
See [Bulk Responses](#bulk-responses)
151
+
See [Bulk Responses][bulk-responses]
114
152
115
153
[Top][toc]
116
154
@@ -126,17 +164,17 @@ See [Bulk Responses](#bulk-responses)
126
164
127
165
**None**
128
166
129
-
## Vehicle - Update
167
+
###Vehicle - Update
130
168
131
169
The `/vehicles` update endpoint is used to change vehicle information, should some aspect of the vehicle change, such as the `vehicle_id`. Each vehicle must already be registered.
132
170
133
171
**Endpoint**: `/vehicles`
134
172
**Method:**`PUT`
135
-
**Payload:** An array of [Vehicles](#vehicle)
173
+
**Payload:** An array of [Vehicles](/data-types.md#vehicles)
136
174
137
175
200 Success Response:
138
176
139
-
See [Bulk Responses](#bulk-responses)
177
+
See [Bulk Responses][bulk-responses]
140
178
141
179
### Vehicle Update Error Codes:
142
180
@@ -147,39 +185,42 @@ See [Bulk Responses](#bulk-responses)
147
185
148
186
[Top][toc]
149
187
150
-
## Vehicles - Events
188
+
## Trips
151
189
152
-
The vehicle `/events`endpoint allows the Provider to submit events describing the state changes of multiple vehicles.
190
+
The Trips endpoint serves two purposes:
153
191
154
-
**Endpoint:**`/vehicles/events`
192
+
* 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.
193
+
* 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.
194
+
195
+
**Endpoint:**`/trips`
155
196
**Method:**`POST`
156
-
**Payload:**An array of [Vehicle Events](#vehicle-event)
197
+
**Payload:**Array of [Trips](/data-types.md#trips)
|`bad_param`| A validation error occurred| Array of parameters with errors |
208
+
|`missing_param`| A required parameter is missing| Array of missing parameters |
209
+
|`unregistered`| This `device_id` is unregistered||
169
210
170
211
[Top][toc]
171
212
172
-
## Vehicles - Telemetry
213
+
## Telemetry
173
214
174
215
The vehicle `/telemetry` endpoint allows a Provider to send vehicle telemetry data in a batch for any number of vehicles in the fleet.
175
216
176
-
**Endpoint**: `/vehicles/telemetry`
217
+
**Endpoint**: `/telemetry`
177
218
**Method**: `POST`
178
-
**Payload**: An array of [Vehicle Telemetry][vehicle-telemetry]
219
+
**Payload**: An array of vehicle [Telemetry][vehicle-telemetry]
179
220
180
221
200 Success Response:
181
222
182
-
See [Bulk Responses](#bulk-responses)
223
+
See [Bulk Responses][bulk-responses]
183
224
184
225
### Telemetry Errors:
185
226
@@ -191,28 +232,25 @@ See [Bulk Responses](#bulk-responses)
191
232
192
233
[Top][toc]
193
234
194
-
## Trips
195
-
196
-
The Trips endpoint serves two purposes:
235
+
## Events
197
236
198
-
* 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.
199
-
* 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.
237
+
The vehicle `/events` endpoint allows the Provider to submit events describing the state changes of multiple vehicles.
200
238
201
-
**Endpoint:**`/trips`
239
+
**Endpoint:**`/events`
202
240
**Method:**`POST`
203
-
**Payload:**Array of [Trips](#trip-data)
241
+
**Payload:**An array of vehicle [Events](/data-types.md#events)
|`device_id`| UUID | Required |ID used in [Register](#vehicle---register)|
116
+
|`device_id`| UUID | Required |A unique device ID in UUID format|
117
117
|`provider_id`| UUID | Required | A UUID for the Provider, unique within MDS. See MDS [provider list](/providers.csv). |
118
118
|`data_provider_id`| UUID | Optional | If different than `provider_id`, a UUID for the data solution provider managing the data feed in this endpoint. See MDS [provider list](/providers.csv) which includes both service operators and data solution providers. |
119
119
|`telemetry_id`| UUID | Required | ID used for uniquely-identifying a Telemetry entry |
120
120
|`timestamp`|[Timestamp][ts]| Required | Date/time that event occurred. Based on GPS or GNSS clock |
121
121
| `trip_ids` | UUID[] | Required | If telemetry occurred during a trip, the ID of the trip(s). If not in a trip, `null`.
122
122
| `journey_id` | UUID | Required | If telemetry occurred during a trip, the ID of the journey. If not in a trip, `null`.
123
-
|`stop_id`| UUID | Required if Applicable | Stop that the vehicle is currently located at. Only applicable for _docked_ Micromobility. See [Stops][stops]|
123
+
|`stop_id`| UUID | Required if Applicable | Stop that the vehicle is currently located at. See [Stops][stops]|
124
124
|`location`|[GPS][gps]| Required | Telemetry position data |
125
125
|`location_type`| Enum | Required if Known | If detectable and known, what type of location the device is on or in. One of `street`, `sidewalk`, `crosswalk`, `garage`, `bike_lane`. |
126
126
|`battery_percent`| Integer | Required if Applicable | Percent battery charge of vehicle, expressed between 0 and 100 |
@@ -144,7 +144,7 @@ A standard point of vehicle telemetry. References to latitude and longitude impl
144
144
145
145
## Stops
146
146
147
-
Stops describe vehicle trip start and end locations in a pre-designated physical place. They can vary from docking stations with or without charging, corrals with lock-to railings, or suggested parking areas marked with spray paint. Stops are used in both [Provider](/provider#stops)(including routes and event locations) and [Agency](/agency#stops)(including telemetry data).
147
+
Stops describe vehicle trip start and end locations in a pre-designated physical place. They can vary from docking stations with or without charging, corrals with lock-to railings, or suggested parking areas marked with spray paint. Stops are used in both [Provider](/provider#stops) and [Agency](/agency#stops) telemetry data.
148
148
149
149
| Field | Type | Required/Optional | Description |
@@ -42,7 +45,7 @@ Working Groups and their Steering Committees are expected to review beta designa
42
45
43
46
[Top][toc]
44
47
45
-
## Costs and currencies
48
+
## Costs and Currencies
46
49
47
50
Fields specifying a monetary cost use a currency as specified in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of `100` (100 cents).
48
51
@@ -76,6 +79,12 @@ Additionally, `device_id` must remain constant for the device's lifetime of serv
76
79
77
80
[Top][toc]
78
81
82
+
## GBFS Compatibility
83
+
84
+
Some of the fields in the `Stops` definition are using notions which are currently not in MDS, such as `rental_methods`. These fields are included for compatibility with GBFS.
85
+
86
+
[Top][toc]
87
+
79
88
## Geographic Data
80
89
81
90
References to geographic datatypes (Point, MultiPolygon, etc.) imply coordinates encoded in the [WGS 84 (EPSG:4326)][wgs84] standard GPS or GNSS projection expressed as [Decimal Degrees][decimal-degrees]. When points are used, you may assume a 20 meter buffer around the point when needed.
@@ -169,7 +178,7 @@ For multi-record POST and PUT calls, e.g. sending Events using the Agency API, t
169
178
|`total`| Integer | Total number of provided points |
170
179
|`failures`|[Trip](#trip-data)[]| Array of failed trip records (empty if all successful) |
171
180
172
-
### Failure Details:
181
+
### Failure Details
173
182
174
183
| Field | Type | Field Description |
175
184
| ----- | ---- | ----------------- |
@@ -186,26 +195,12 @@ All String fields, such as `vehicle_id`, are limited to a maximum of 255 charact
186
195
187
196
[Top][toc]
188
197
189
-
### GBFS Compatibility
190
-
191
-
Some of the fields in the `Stops` definition are using notions which are currently not in MDS, such as `rental_methods`. These fields are included for compatibility with GBFS.
192
-
193
-
[Top][toc]
194
-
195
198
## Timestamps
196
199
197
200
A `timestamp` refers to integer milliseconds since Unix epoch.
198
201
199
202
[Top][toc]
200
203
201
-
## UUIDs
202
-
203
-
Object identifiers are described via Universally Unique Identifiers [(UUIDs)](https://en.wikipedia.org/wiki/Universally_unique_identifier). For example, the `device_id` field used to uniquely identify a vehicle is a UUID.
204
-
205
-
MDS uses Version 1 UUIDs by default. Version 4 UUIDs may be used where noted.
206
-
207
-
[Top][toc]
208
-
209
204
## Trips
210
205
211
206
Counting trips is a common analysis with MDS data, but in some instances when
@@ -223,6 +218,14 @@ at the recommendation of the MDS community when analyzing trips.
223
218
224
219
[Top][toc]
225
220
221
+
## UUIDs
222
+
223
+
Object identifiers are described via Universally Unique Identifiers [(UUIDs)](https://en.wikipedia.org/wiki/Universally_unique_identifier). For example, the `device_id` field used to uniquely identify a vehicle is a UUID.
224
+
225
+
MDS uses Version 1 UUIDs by default. Version 4 UUIDs may be used where noted.
226
+
227
+
[Top][toc]
228
+
226
229
## Vehicle States
227
230
228
231
See new location within [vehicle states](/modes/vehicle_states.md) in [modes](/modes#vehicle-states).
@@ -253,12 +256,12 @@ MDS APIs must handle requests for specific versions of the specification from cl
253
256
254
257
Versioning must be implemented through the use of a custom media-type, `application/vnd.mds+json`, combined with a required `version` parameter. The one exception is the `/reports` endpoint, which returns CSV files instead of JSON, and so uses `text/vnd.mds+csv` as its media-type.
255
258
256
-
The version parameter specifies the dot-separated combination of major and minor versions from a published version of the specification. For example, the media-type for version `1.0.1` would be specified as `application/vnd.mds+json;version=1.0`
259
+
The version parameter specifies the dot-separated combination of major and minor versions from a published version of the specification. For example, the media-type for version `1.0.1` would be specified as `application/vnd.mds+json;version=1.0`. Only major and minor versions are allowed and required in the media-type version string (not [patch](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md#versioning) releases).
257
260
258
261
Clients must specify the version they are targeting through the `Accept` header. For example:
259
262
260
263
```http
261
-
Accept: application/vnd.mds+json;version=1.2.0
264
+
Accept: application/vnd.mds+json;version=2.0
262
265
```
263
266
264
267
Since versioning was not available from the start, the following APIs provide a fallback version if the `Accept` header is not set as specified above:
0 commit comments