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: .github/PULL_REQUEST_TEMPLATE/default.md
+5-1Lines changed: 5 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,11 @@ title: <Insert Title>
9
9
10
10
Thank you for your contribution!
11
11
12
-
*For most Pull Requests, the target branch should be [**`dev`**](https://github.com/openmobilityfoundation/mobility-data-specification/tree/dev). Please ensure you are targeting **`dev`** to avoid complications and help make the Review process as smooth as possible.*
12
+
To avoid complications and help make the Review process as smooth as possible, make sure to:
13
+
14
+
1. Target [**`dev`**](https://github.com/openmobilityfoundation/mobility-data-specification/tree/dev) branch. Please ensure you are targeting **`dev`**, not **`main`**.
15
+
1. Keep the *"Allow edits from maintainers"* button checked to help us resolve some issues for you.
16
+
1. Be ready to resolve any merge conflicts before we approve your Pull Request.
***Ulm, Germany**: A draft of the guidelines can be found at [the city's GitHub presence](https://github.com/stadtulm/mds-zonen).
77
77
***Washington, DC**: [Dockless Vehicle Permits](https://ddot.dc.gov/page/dockless-vehicle-permits-district), [terms and conditions](https://ddot.dc.gov/sites/default/files/dc/sites/ddot/2019.11.6%20Shared%20dockless%202020%20Terms%20and%20Conditions%20scooter.pdf), [data reporting standards](https://ddot.dc.gov/sites/default/files/dc/sites/ddot/2019.11.6%20Dockless%20Permit%20TC%20Attatchments.pdf), and [FAQ](https://docs.google.com/document/d/1G2ddANcXl3lShCZInV3uX2NTBfRRu4Fm-tiaCi203QM/).
78
78
79
-
*_[add your City here by opening a pull request](https://github.com/openmobilityfoundation/mobility-data-specification/compare)_
79
+
*_add a city here by [opening a pull request](https://github.com/openmobilityfoundation/mobility-data-specification/compare/dev...dev) or [making an issue](https://github.com/openmobilityfoundation/mobility-data-specification/issues/new?assignees=&labels=&template=feature-request---proposal.md&title=)_.
80
80
81
81
Other cities include Baltimore, Bellevue, Charlotte, Oakland, and Seattle, via the [NACTO Guidelines for Regulating Shared Micromobility](https://nacto.org/wp-content/uploads/2019/09/NACTO_Shared_Micromobility_Guidelines_Web.pdf), page 48.
Copy file name to clipboardExpand all lines: agency/README.md
+34-14Lines changed: 34 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,38 +2,46 @@
2
2
3
3
This specification contains a collection of RESTful APIs used to specify the digital relationship between *mobility as a service* Providers and the Agencies that regulate them.
4
4
5
-
* Date: 19 Sep 2019
6
-
* Version: BETA
7
-
8
5
## Table of Contents
9
6
10
7
*[General Information](#general-information)
8
+
*[Versioning](#versioning)
9
+
*[Responses and Error Messages](#responses-and-error-messages)
10
+
*[Authorization](#authorization)
11
11
*[Vehicles](#vehicles)
12
-
*[Vehicle Registration](#vehicle---register)
13
-
*[Vehicle Update](#vehicle---update)
14
-
*[Vehicle Events](#vehicle---event)
15
-
*[Vehicles Telemetry](#vehicles---telemetry)
12
+
*[Vehicle - Register](#vehicle---register)
13
+
*[Vehicle - Update](#vehicle---update)
14
+
*[Vehicle - Events](#vehicle---event)
15
+
*[Vehicle - Telemetry](#vehicle---telemetry)
16
16
*[Telemetry Data](#telemetry-data)
17
17
*[Stops](#stops)
18
18
19
19
## General information
20
20
21
21
This specification uses data types including timestamps, UUIDs, and vehicle state definitions as described in the MDS [General Information][general] document.
22
22
23
+
[Top][toc]
24
+
23
25
### Versioning
24
26
25
27
`agency` APIs must handle requests for specific versions of the specification from clients.
26
28
27
29
Versioning must be implemented as specified in the [Versioning section][versioning].
28
30
31
+
[Top][toc]
32
+
29
33
### Responses and Error Messages
30
34
31
35
See the [Responses][responses] and [Error Messages][error-messages] sections.
32
36
37
+
[Top][toc]
38
+
33
39
### Authorization
34
40
35
41
When making requests, the Agency API expects `provider_id` to be part of the claims in a [JWT](https://jwt.io/)`access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the Agency.
36
42
43
+
[Top][toc]
44
+
37
45
## Vehicles
38
46
39
47
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.
@@ -83,7 +91,9 @@ A vehicle record is as follows:
83
91
84
92
_No content returned on vehicle not found._
85
93
86
-
## Vehicle Registration
94
+
[Top][toc]
95
+
96
+
## Vehicle - Register
87
97
88
98
The `/vehicles` registration endpoint is used to register a vehicle for use in the Agency jurisdiction.
89
99
@@ -120,6 +130,8 @@ _No content returned on success._
|`device_id`| UUID | Required | ID used in [Register](#vehicle-register)|
176
+
|`device_id`| UUID | Required | ID used in [Register](#vehicle---register)|
163
177
164
178
Body Params:
165
179
@@ -185,7 +199,9 @@ Body Params:
185
199
|`missing_param`| A required parameter is missing | Array of missing parameters |
186
200
|`unregistered`| Vehicle is not registered ||
187
201
188
-
## Vehicles - Telemetry
202
+
[Top][toc]
203
+
204
+
## Vehicle - Telemetry
189
205
190
206
The vehicle `/telemetry` endpoint allows a Provider to send vehicle telemetry data in a batch for any number of vehicles in the fleet.
191
207
@@ -214,13 +230,15 @@ Body Params:
214
230
|`invalid_data`| None of the provided data was valid. ||
215
231
|`missing_param`| A required parameter is missing. | Array of missing parameters |
216
232
233
+
[Top][toc]
234
+
217
235
## Telemetry Data
218
236
219
237
A standard point of vehicle telemetry. References to latitude and longitude imply coordinates encoded in the [WGS 84 (EPSG:4326)](https://en.wikipedia.org/wiki/World_Geodetic_System) standard GPS or GNSS projection expressed as [Decimal Degrees](https://en.wikipedia.org/wiki/Decimal_degrees).
220
238
221
239
| Field | Type | Required/Optional | Field Description |
|`device_id`| UUID | Required | ID used in [Register](#vehicle-register)|
241
+
|`device_id`| UUID | Required | ID used in [Register](#vehicle---register)|
224
242
|`timestamp`|[timestamp][ts]| Required | Date/time that event occurred. Based on GPS or GNSS clock |
225
243
|`gps`| Object | Required | Telemetry position data |
226
244
|`gps.lat`| Double | Required | Latitude of the location |
@@ -234,9 +252,11 @@ A standard point of vehicle telemetry. References to latitude and longitude impl
234
252
|`charge`| Float | Required if Applicable | Percent battery charge of vehicle, expressed between 0 and 1 |
235
253
|`stop_id`| UUID | Required if Applicable | Stop that the vehicle is currently located at. Only applicable for _docked_ Micromobility. See [Stops][stops]|
236
254
255
+
[Top][toc]
256
+
237
257
## Stops
238
258
239
-
The `/stops` endpoint allows an agency to register Stops.
259
+
The `/stops` endpoint allows an agency to register city-managed Stops, or a provider to register self-managed Stops.
240
260
241
261
**Endpoint:**`/stops`
242
262
**Method:**`POST`
@@ -269,10 +289,10 @@ In the case that a `stop_id` query parameter is specified, the `stops` array ret
@@ -59,6 +64,61 @@ Additionally, `device_id` must remain constant for the device's lifetime of serv
59
64
60
65
[Top][toc]
61
66
67
+
## Geographic Data
68
+
69
+
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].
70
+
71
+
Whenever an individual location coordinate measurement is presented, it must be
72
+
represented as a GeoJSON [`Feature`][geojson-feature] object with a corresponding [`timestamp`][ts] property and [`Point`][geojson-point] geometry:
73
+
74
+
```json
75
+
{
76
+
"type": "Feature",
77
+
"properties": {
78
+
"timestamp": 1529968782421
79
+
},
80
+
"geometry": {
81
+
"type": "Point",
82
+
"coordinates": [
83
+
-118.46710503101347,
84
+
33.9909333514159
85
+
]
86
+
}
87
+
}
88
+
```
89
+
90
+
### Stop-based Geographic Data
91
+
92
+
When an individual location coordinate measurement corresponds to a [Stop][general-stops],
93
+
it must be presented with a `stop_id` property:
94
+
95
+
```json
96
+
{
97
+
"type": "Feature",
98
+
"properties": {
99
+
"timestamp": 1529968782421,
100
+
"stop_id": "b813cde2-a41c-4ae3-b409-72ff221e003d"
101
+
},
102
+
"geometry": {
103
+
"type": "Point",
104
+
"coordinates": [
105
+
-118.46710503101347,
106
+
33.9909333514159
107
+
]
108
+
}
109
+
}
110
+
```
111
+
112
+
### Intersection Operation
113
+
114
+
For the purposes of this specification, the intersection of two geographic datatypes is defined according to the [`ST_Intersects` PostGIS operation][st-intersects]
115
+
116
+
> If a geometry or geography shares any portion of space then they intersect. For geography -- tolerance is 0.00001 meters (so any points that are close are considered to intersect).
117
+
>
118
+
> Overlaps, Touches, Within all imply spatial intersection. If any of the aforementioned returns true, then the geometries also spatially intersect. Disjoint implies false for spatial intersection.
119
+
120
+
[Top][toc]
121
+
62
122
## Propulsion Types
63
123
64
124
|`propulsion`| Description |
@@ -241,14 +301,15 @@ The *State Machine Diagram* shows how the `vehicle_state` and `event_type` relat
241
301
242
302
## Vehicle Types
243
303
244
-
The list of allowed `vehicle_type` values in MDS is:
304
+
The list of allowed `vehicle_type` values in MDS. Aligning with [GBFS vehicle types form factors](https://github.com/NABSA/gbfs/blob/master/gbfs.md#vehicle_typesjson-added-in-v21-rc).
245
305
246
306
|`vehicle_type`| Description |
247
307
|--------------| --- |
248
308
| bicycle | Anything with pedals, including recumbents; can include powered assist |
249
309
| car | Any automobile |
250
310
| scooter | Any motorized mobility device intended for one rider |
251
311
| moped | A motorcycle/bicycle hybrid that can be powered or pedaled |
312
+
| other | A device that does not fit in the other categories |
252
313
253
314
[Top][toc]
254
315
@@ -277,8 +338,16 @@ If an unsupported or invalid version is requested, the API must respond with a s
0 commit comments