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
+32-1Lines changed: 32 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,6 +14,7 @@ This specification contains a collection of RESTful APIs used to specify the dig
14
14
*[Vehicle Events](#vehicle---event)
15
15
*[Vehicles Telemetry](#vehicles---telemetry)
16
16
*[Telemetry Data](#telemetry-data)
17
+
*[Stops](#stops)
17
18
18
19
## General information
19
20
@@ -231,17 +232,47 @@ A standard point of vehicle telemetry. References to latitude and longitude impl
231
232
|`gps.hdop`| Float | Required if Available | Horizontal GPS or GNSS accuracy value (see [hdop][hdop]) |
232
233
| `gps.satellites` | Integer | Required if Available | Number of GPS or GNSS satellites
233
234
|`charge`| Float | Required if Applicable | Percent battery charge of vehicle, expressed between 0 and 1 |
235
+
|`stop_id`| UUID | Required if Applicable | Stop that the vehicle is currently located at. Only applicable for _docked_ Micromobility. See [Stops][stops]|
236
+
237
+
## Stops
238
+
239
+
The `/stops` endpoint allows an agency to register Stops.
240
+
241
+
**Endpoint:**`/stops`
242
+
**Method:**`POST`
243
+
**[Beta feature][beta]:** Yes (as of 1.0.0)
244
+
**Request Body**: An array of [Stops][stops]
245
+
246
+
**Endpoint:**`/stops`
247
+
**Method:**`PUT`
248
+
**[Beta feature][beta]:** Yes (as of 1.0.0)
249
+
**Request Body**: An array of subsets of [Stop][stops] information, where the permitted subset fields are defined as:
**`data` Payload:**`{ "stops": [] }`, an array of [Stops][stops]
261
+
262
+
In the case that a `stop_id` query parameter is specified, the `stops` array returned will only have one entry. In the case that no `stop_id` query parameter is specified, all stops will be returned.
Copy file name to clipboardExpand all lines: general-information.md
+46-5Lines changed: 46 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,6 +12,7 @@ This document contains specifications that are shared between the various MDS AP
12
12
*[Responses](#responses)
13
13
*[Error Messages](#error-messages)
14
14
*[Strings](#strings)
15
+
*[Stops](#stops)
15
16
*[Timestamps](#timestamps)
16
17
*[UUIDs](#uuids)
17
18
*[Vehicle States](#vehicle-states)
@@ -43,10 +44,10 @@ If the currency field is null, USD cents is implied.
43
44
44
45
Defining terminology and abbreviations used throughout MDS.
45
46
46
-
-**API** - Application Programming Interface - A function or set of functions that allow one software application to access or communicate with features of a different software application or service.
47
-
-**API Endpoint** - A point at which an API connects with a software application or service.
48
-
-**DOT** - Department of Transportation, usually a city-run agency.
49
-
-**PROW** - Public Right of Way - the physical infrastructure reserved for transportation purposes, examples include sidewalks, curbs, bike lanes, transit lanes and stations, traffic lanes and signals, and public parking.
47
+
***API** - Application Programming Interface - A function or set of functions that allow one software application to access or communicate with features of a different software application or service.
48
+
***API Endpoint** - A point at which an API connects with a software application or service.
49
+
***DOT** - Department of Transportation, usually a city-run agency.
50
+
***PROW** - Public Right of Way - the physical infrastructure reserved for transportation purposes, examples include sidewalks, curbs, bike lanes, transit lanes and stations, traffic lanes and signals, and public parking.
50
51
51
52
[Top][toc]
52
53
@@ -105,6 +106,45 @@ All String fields, such as `vehicle_id`, are limited to a maximum of 255 charact
105
106
106
107
[Top][toc]
107
108
109
+
## Stops
110
+
111
+
| Field | Type | Required/Optional | Description |
| is_installed | Boolean | Required | See GBFS [station_status.json][gbfs-station-status]|
139
+
| is_renting | Boolean | Required | See GBFS [station_status.json][gbfs-station-status]|
140
+
| is_returning | Boolean | Required | See GBFS [station_status.json][gbfs-station-status]|
141
+
142
+
### GBFS Compatibility
143
+
144
+
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.
145
+
146
+
[Top][toc]
147
+
108
148
## Timestamps
109
149
110
150
A `timestamp` refers to integer milliseconds since Unix epoch.
@@ -183,7 +223,6 @@ Note that to handle out-of-order events, the validity of the prior-state shall n
183
223
The *State Machine Diagram* shows how the `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1Ar2-ju8YlddSsTATvQw4YjsSa5108XtidtnJNk-UAfA/edit) for the source file.
184
224
185
225
186
-
187
226
[Top][toc]
188
227
189
228
## Vehicle Types
@@ -224,6 +263,8 @@ If an unsupported or invalid version is requested, the API must respond with a s
Copy file name to clipboardExpand all lines: provider/README.md
+42-10Lines changed: 42 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,9 @@ This specification contains a data standard for *mobility as a service* provider
9
9
*[Status Changes][status]
10
10
*[Realtime Data](#realtime-data)
11
11
*[GBFS](#GBFS)
12
+
*[Data Latency Requirements][data-latency]
12
13
*[Events][events]
14
+
*[Stops][stops]
13
15
*[Vehicles][vehicles]
14
16
15
17
## General Information
@@ -296,9 +298,20 @@ GBFS 2.0 includes some changes that may make it less useful for regulatory purpo
296
298
297
299
[Top][toc]
298
300
301
+
### Data Latency Requirements
302
+
303
+
The data returned by a near-realtime endpoint should be as close to realtime as possible, but in no case should it be more than 5 minutes out-of-date. Near-realtime endpoints must contain `last_updated` and `ttl` properties in the top-level of the response body. These properties are defined as:
304
+
305
+
Field Name | Required | Defines
306
+
--------------------| ----------| ----------
307
+
last_updated | Yes | Timestamp indicating the last time the data in this feed was updated
308
+
ttl | Yes | Integer representing the number of milliseconds before the data in this feed will be updated again (0 if the data should always be refreshed).
309
+
310
+
[Top][toc]
311
+
299
312
### Events
300
313
301
-
The `/events` endpoint is a near-ish real-time feed of status changes, designed to give access to as recent as possible series of events.
314
+
The `/events` endpoint is a near-realtime feed of status changes, designed to give access to as recent as possible series of events.
302
315
303
316
The `/events` endpoint functions similarly to `/status_changes`, but shall not included data older than 2 weeks (that should live in `/status_changes.`)
304
317
@@ -327,13 +340,37 @@ Should either side of the requested time range be missing, `/events` shall retur
327
340
328
341
Should either side of the requested time range be greater than 2 weeks before the time of the request, `/events` shall return a `400 Bad Request` error.
329
342
343
+
### Stops
344
+
345
+
Stop information should be updated on a near-realtime basis by providers who operate _docked_ mobility devices in a given municipality.
346
+
347
+
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]:
348
+
349
+
```json
350
+
{
351
+
"version": "x.y.z",
352
+
"data": {
353
+
"stops": []
354
+
},
355
+
"last_updated": "12345",
356
+
"ttl": "12345"
357
+
}
358
+
```
359
+
360
+
**Endpoint:**`/stops/:stop_id`
361
+
**Method:**`GET`
362
+
**[Beta feature][beta]:** Yes (as of 1.0.0)
363
+
**`data` Payload:**`{ "stops": [] }`, an array of [Stops](/general-information.md#stop)
364
+
365
+
In the case that a `stop_id` query parameter is specified, the `stops` array returned will only have one entry. In the case that no `stop_id` query parameter is specified, all stops will be returned.
366
+
330
367
[Top][toc]
331
368
332
369
### Vehicles
333
370
334
-
The `/vehicles` endpoint returns the current status of vehicles on the PROW. Only vehicles that are currently in available, unavailable, or reserved states should be returned in this payload. Data in this endpoint should reconcile with data from the `/status_changes` enpdoint. The data returned by this endpoint should be as close to realtime as possible, but in no case should it be more than 5 minutes out-of-date. As with other MDS APIs, `/vehicles` is intended for use by regulators, not by the general public. It does not replace the role of a [GBFS][gbfs] feed in enabling consumer-facing applications.
371
+
The `/vehicles` endpoint returns the current status of vehicles on the PROW. Only vehicles that are currently in available, unavailable, or reserved states should be returned in this payload. Data in this endpoint should reconcile with data from the `/status_changes` enpdoint. As with other MDS APIs, `/vehicles` is intended for use by regulators, not by the general public. It does not replace the role of a [GBFS][gbfs] feed in enabling consumer-facing applications.
335
372
336
-
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:
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]:
337
374
338
375
```json
339
376
{
@@ -346,13 +383,6 @@ In addition to the standard [Provider payload wrapper](#response-format), respon
346
383
}
347
384
```
348
385
349
-
Where `last_updated` and `ttl` are defined as follows:
350
-
351
-
Field Name | Required | Defines
352
-
--------------------| ----------| ----------
353
-
last_updated | Yes | Timestamp indicating the last time the data in this feed was updated
354
-
ttl | Yes | Integer representing the number of milliseconds before the data in this feed will be updated again (0 if the data should always be refreshed).
355
-
356
386
**Endpoint:**`/vehicles`
357
387
**Method:**`GET`
358
388
**[Beta feature][beta]:** Yes (as of 0.4.1)
@@ -379,6 +409,7 @@ ttl | Yes | Integer representing the number of millisecond
0 commit comments