From bce70e13f237c514e6211ee2bf5c12cf28bb2753 Mon Sep 17 00:00:00 2001 From: Egor Date: Sat, 3 Jun 2023 11:42:21 +0300 Subject: [PATCH 01/14] Add GBFS endpoint for Whoosh --- providers.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/providers.csv b/providers.csv index b61e6dd1..75754b6d 100644 --- a/providers.csv +++ b/providers.csv @@ -46,7 +46,7 @@ Troopy,micromobility,2b684c7c-f8ad-4c65-92f0-b9e57aaa7dd3,https://www.troopy.com BCycle,micromobility,938D9F8B-B8D3-46CC-9276-F4A8C4FA3610,https://www.bcycle.com,https://mds.bcycle.com,https://gbfs.bcycle.com Tembici,micromobility,46b28e68-8ecb-4875-b97e-836fd5e1930f,https://www.tembici.com.br/,https://api.tembici.com.br/mds,https://api.tembici.com.br/gbfs POPPY Mobility,micromobility,5c869736-797f-4244-9132-fb50a22d1bfd,https://www.poppy.be/,https://poppy.red/mds, -Whoosh,micromobility,3f8908a7-86fa-450d-8889-5d49077e06cd,https://whoosh.bike,https://mds.whoosh.bike, +Whoosh,micromobility,3f8908a7-86fa-450d-8889-5d49077e06cd,https://whoosh.bike,https://mds.whoosh.bike,https://gbfs.whoosh.bike, Telofun,micromobility,3dd253d3-557c-4fcb-98da-9af3edeaaae6,https://www.tel-o-fun.co.il/,https://mds.fsmctmobility.com/api/mds/v1/, Gbike,micromobility,a50b796e-bca2-11ed-afa1-0242ac120002,https://gcoo.io/,https://mds.gcoo.io/,https://mds.gcoo.io/gbfs SURF,micromobility,66c43ccb-f9f9-4f70-9707-37301b9f49a8,https://www.surfingscooters.com,https://api.app.surf/mds,https://api.app.surf/gbfs/en From 488b746a1f912100e4bda0135c2cc62535415683 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 15 Jun 2023 20:47:45 -0400 Subject: [PATCH 02/14] Remove comma --- providers.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/providers.csv b/providers.csv index 75754b6d..a0f3118e 100644 --- a/providers.csv +++ b/providers.csv @@ -46,7 +46,7 @@ Troopy,micromobility,2b684c7c-f8ad-4c65-92f0-b9e57aaa7dd3,https://www.troopy.com BCycle,micromobility,938D9F8B-B8D3-46CC-9276-F4A8C4FA3610,https://www.bcycle.com,https://mds.bcycle.com,https://gbfs.bcycle.com Tembici,micromobility,46b28e68-8ecb-4875-b97e-836fd5e1930f,https://www.tembici.com.br/,https://api.tembici.com.br/mds,https://api.tembici.com.br/gbfs POPPY Mobility,micromobility,5c869736-797f-4244-9132-fb50a22d1bfd,https://www.poppy.be/,https://poppy.red/mds, -Whoosh,micromobility,3f8908a7-86fa-450d-8889-5d49077e06cd,https://whoosh.bike,https://mds.whoosh.bike,https://gbfs.whoosh.bike, +Whoosh,micromobility,3f8908a7-86fa-450d-8889-5d49077e06cd,https://whoosh.bike,https://mds.whoosh.bike,https://gbfs.whoosh.bike Telofun,micromobility,3dd253d3-557c-4fcb-98da-9af3edeaaae6,https://www.tel-o-fun.co.il/,https://mds.fsmctmobility.com/api/mds/v1/, Gbike,micromobility,a50b796e-bca2-11ed-afa1-0242ac120002,https://gcoo.io/,https://mds.gcoo.io/,https://mds.gcoo.io/gbfs SURF,micromobility,66c43ccb-f9f9-4f70-9707-37301b9f49a8,https://www.surfingscooters.com,https://api.app.surf/mds,https://api.app.surf/gbfs/en From 25a87400959eee89e2b06b694ef157a5fef8c138 Mon Sep 17 00:00:00 2001 From: Brian Grass Date: Wed, 9 Aug 2023 16:03:28 -0700 Subject: [PATCH 03/14] Fix links on data-types page --- data-types.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/data-types.md b/data-types.md index 304a43cf..7c3a8b62 100644 --- a/data-types.md +++ b/data-types.md @@ -5,11 +5,11 @@ This MDS data types page catalogs the objects (fields, types, requirements, desc ## Table of Contents - [Vehicles](#vehicles) - - [Vehicle Types](#vehicle-types) + - [Vehicle Types][vehicle-types] - [Propulsion Types](#propulsion-types) - [Vehicle Status](#vehicle-status) - [Events](#events) - - [Event Types](#event-times) + - [Event Types](/modes/event_types.md) - [Telemetry](#telemetry) - [GPS Data][gps] - [Stops](#stops) @@ -251,7 +251,7 @@ A Report is defined by the following structure: | `duration` | string | Value is always `P1M` for monthly. Based on [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) | | `special_group_type` | [Special Group Type](#special-group-type) | Type that applies to this row | | `geography_id` | [Geography](/geography) | ID that applies to this row. Includes all IDs in /geography. When there is no /geography then return `null` for this value and return counts based on the entire operating area. | -| `vehicle_type` | [Vehicle Type](/general-information.md#vehicle-types) | Type that applies to this row | +| `vehicle_type` | [Vehicle Type][vehicle-types] | Type that applies to this row | | `trip_count` | integer | Count of trips taken for this row | | `rider_count` | integer | Count of unique riders for this row | @@ -294,18 +294,18 @@ Other special group types may be added in future MDS releases as relevant agency [Top][toc] [costs-and-currencies]: /general-information.md#costs-and-currencies -[event-times]: /general-information.md#event-times +[event-times]: #event-times [gbfs-station-info]: https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson [gbfs-station-status]: https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_statusjson [geography-driven-events]: /general-information.md#geography-driven-events [gps]: #gps-data [iso4217]: https://en.wikipedia.org/wiki/ISO_4217#Active_codes [modes]: /modes/README.md -[propulsion-types]: /general-information.md#propulsion-types -[stop-based-geo]: #stop-based-geographic-data +[propulsion-types]: #propulsion-types +[stop-based-geo]: /general-information.md#stop-based-geographic-data [stops]: #stops [toc]: #table-of-contents [ts]: /general-information.md#timestamps -[vehicle-states]: /modes#vehicle-states -[vehicle-events]: /modes#event-types -[vehicle-types]: /general-information.md#vehicle-types +[vehicle-states]: /general-information.md#vehicle-states +[vehicle-events]: /general-information.md#event-types +[vehicle-types]: #vehicle-types From 1586d474e60c850e34a69d0818cbb8840dcbe0f9 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Thu, 7 Sep 2023 16:53:54 -0700 Subject: [PATCH 04/14] Update "status changes" to "events" in provider I noticed a few places in the provider README where it was still referring to "status changes" instead of the new term "events". There was also an inconsistency in the depiction of the response format. --- provider/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/provider/README.md b/provider/README.md index e4f7b09a..4163c518 100644 --- a/provider/README.md +++ b/provider/README.md @@ -395,7 +395,7 @@ The `/events/historical` API uses the following query parameter: | Query Parameter | Format | Expected Output | | --------- | ------ | --------------- | -| `event_time` | `YYYY-MM-DDTHH`, an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) extended datetime representing an UTC hour between 00 and 23. | All status changes with an event time occurring within the hour. For example, requesting `event_time=2019-10-01T07` returns all status changes where `2019-10-01T07:00:00 <= status_change.event_time < 2019-10-01T08:00:00` UTC. | +| `event_time` | `YYYY-MM-DDTHH`, an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) extended datetime representing an UTC hour between 00 and 23. | All events with an event time occurring within the hour. For example, requesting `event_time=2019-10-01T07` returns all events where `2019-10-01T07:00:00 <= event.timestamp < 2019-10-01T08:00:00` UTC. | Without an `event_time` query parameter, `/events` shall return a `400 Bad Request` error. @@ -411,14 +411,14 @@ processing for that hour: * For hours that are in the past but for which data is not yet available the API shall return a `202 Accepted` response. * For all other hours the API shall return a `200 OK` response with a fully - populated body, even for hours that contain no status changes to report. - If the hour has no status changes to report the response shall contain an - empty array of status changes: + populated body, even for hours that contain no events to report. + If the hour has no events to report the response shall contain an + empty array of events: ```json { "version": "x.y.z", - "status_changes": [] + "events": [] } ``` From 5f3c43fabce089ec1b421cb21a6cfcac5df6a7b4 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Mon, 16 Oct 2023 12:05:13 -0700 Subject: [PATCH 05/14] Remove word data from response payload descriptions In older versions of MDS data was nested under a `data` key in provider API responses, so trips data would e.g. be response['data']['trips']. This ended up reflected in the docs where each section would have a label like "`data` Payload" describing what was under the `data` key in the payload. In MDS 2.0 this nesting was removed, `trips` is now a top level key in the response from provider trips endpoint. However, the docs were not updated to remove the word "data" from the payload descriptions, leading to potential confusion for readers of the documentation. This PR changes "`data` Payload" to "Payload" throughout the provider README to bring it in line with the spec. --- provider/README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/provider/README.md b/provider/README.md index e4f7b09a..8addbcae 100644 --- a/provider/README.md +++ b/provider/README.md @@ -189,7 +189,7 @@ The `/vehicles` endpoint returns the specified vehicle (if a device_id is provid **Method:** `GET` **[Beta feature][beta]:** No (as of 1.2.0) **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. -**`data` Payload:** `{ "vehicles": [] }`, an array of [Vehicle][vehicles] objects +**Payload:** `{ "vehicles": [] }`, an array of [Vehicle][vehicles] objects _Path Parameters:_ @@ -234,7 +234,7 @@ The `/vehicles/status` endpoint returns the specified vehicle (if a device_id is **Method:** `GET` **[Beta feature][beta]:** No (as of 1.2.0) **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. -**`data` Payload:** `{ "vehicles_status": [] }`, an array of [Vehicle Status][vehicle-status] objects +**Payload:** `{ "vehicles_status": [] }`, an array of [Vehicle Status][vehicle-status] objects _Path Parameters:_ @@ -283,7 +283,7 @@ Unless stated otherwise by the municipality, the trips endpoint must return all **Method:** `GET` **[Beta feature][beta]:** No **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. -**`data` Payload:** `{ "trips": [] }`, an array of [Trip][trips] objects +**Payload:** `{ "trips": [] }`, an array of [Trip][trips] objects ### Trips - Query Parameters @@ -348,7 +348,7 @@ Telemetry for a [trip](#trip) must include at least 2 points: the start point an **Endpoint:** `/telemetry` **Method:** `GET` **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. -**`data` Payload:** `{ "telemetry": [] }`, an array of [Vehicle Telemetry][vehicle-telemetry] objects +**Payload:** `{ "telemetry": [] }`, an array of [Vehicle Telemetry][vehicle-telemetry] objects [Top][toc] @@ -385,7 +385,7 @@ Unless stated otherwise by the municipality, this endpoint must return only thos **Method:** `GET` **[Beta feature][beta]:** No **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. -**`data` Payload:** `{ "events": [] }`, an array of [Events](/data-types.md#events) object +**Payload:** `{ "events": [] }`, an array of [Events](/data-types.md#events) object [Top][toc] @@ -447,7 +447,7 @@ See also [Stop-based Geographic Data][stop-based-geo]. **Method:** `GET` **[Beta feature][beta]:** No (as of 1.0.0) **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. -**`data` Payload:** `{ "events": [] }`, an array of [Events](/data-types.md#events) object objects +**Payload:** `{ "events": [] }`, an array of [Events](/data-types.md#events) object objects #### Recent Events - Query Parameters @@ -494,7 +494,7 @@ In addition to the standard [Provider payload wrapper](#response-format), respon **Method:** `GET` **[Beta feature][beta]:** Yes (as of 1.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/638) **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. -**`data` Payload:** `{ "stops": [] }`, an array of [Stops][stops] +**Payload:** `{ "stops": [] }`, an array of [Stops][stops] In the case that a `stop_id` path 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. @@ -527,8 +527,8 @@ The authenticated reports are monthly, historic flat files that may be pre-gener **[Beta feature][beta]:** No (as of 2.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/672) **Usage note:** This endpoint uses media-type `text/vnd.mds+csv` instead of `application/vnd.mds+json`, see [Versioning][versioning]. **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. -**`data` Filename:** monthly file named by year and month, e.g. `/reports/YYYY-MM.csv` -**`data` Payload:** monthly CSV files of [Report](/data-types.md#Reports) objects +**Filename:** monthly file named by year and month, e.g. `/reports/YYYY-MM.csv` +**Payload:** monthly CSV files of [Report](/data-types.md#Reports) objects #### Responses From 9e49027cf1f0cb57d36733008e16a2bcfff7c4a7 Mon Sep 17 00:00:00 2001 From: bergenklem <134277360+bergenklem@users.noreply.github.com> Date: Tue, 17 Oct 2023 09:05:58 +0200 Subject: [PATCH 06/14] Update car-share.md --- modes/car-share.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/modes/car-share.md b/modes/car-share.md index fb9e4b5a..f0fdd042 100644 --- a/modes/car-share.md +++ b/modes/car-share.md @@ -236,15 +236,13 @@ This is the list of `vehicle_state` and `event_type` pairings that constitute th | `removed` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while removed | | `removed` | `non_operational` | N/A | `maintenance_end` | The vehicle maintenance work has ended | | `removed` | `non_operational` | N/A | `recommissioned` | The vehicle has been re-added to the Provider's fleet after being previously `decommissioned` | -| `reserved` | `available` | N/A | `driver_cancellation` | The driver has canceled the reservation | | `reserved` | `available` | N/A | `customer_cancellation` | The customer has canceled the reservation | | `reserved` | `available` | N/A | `provider_cancellation` | The provider has canceled the reservation | | `reserved` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left the jurisdiction while in a reservation | | `reserved` | `non_contactable` | N/A | `comms_lost` | The vehicle went out of comms while being reserved by a passenger | -| `reserved` | `stopped` | `stopped` | `reservation_stop` | The vehicle has stopped to pick up the passenger | -| `stopped` | `available` | N/A | `driver_cancellation` | The driver has canceled the trip while either waiting for the passenger, or dropping them off | -| `stopped` | `available` | N/A | `customer_cancellation` | The customer has canceled the trip while the vehicle is waiting to pick them up, or they are being dropped off | -| `stopped` | `available` | N/A | `provider_cancellation` | The provider has canceled the trip while the vehicle is waiting for a passenger, or dropping them off | +| `reserved` | `stopped` | `stopped` | `reservation_stop` | The customer has activated the vehicle | +| `stopped` | `available` | N/A | `customer_cancellation` | The customer has canceled the trip | +| `stopped` | `available` | N/A | `provider_cancellation` | The provider has canceled the trip | | `stopped` | `available` | N/A | `trip_end` | The trip has been successfully completed | | `stopped` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while stopped | | `stopped` | `on_trip` | `on_trip` | `trip_resume` | Resume a trip that was previously stopped (e.g. picking up a friend to go to the airport with) | From eebf3fd759f22590001589b5ba35b9849f979788 Mon Sep 17 00:00:00 2001 From: bergenklem <134277360+bergenklem@users.noreply.github.com> Date: Tue, 17 Oct 2023 10:11:21 +0200 Subject: [PATCH 07/14] Update car-share.md --- modes/car-share.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modes/car-share.md b/modes/car-share.md index f0fdd042..576bcc18 100644 --- a/modes/car-share.md +++ b/modes/car-share.md @@ -236,11 +236,13 @@ This is the list of `vehicle_state` and `event_type` pairings that constitute th | `removed` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while removed | | `removed` | `non_operational` | N/A | `maintenance_end` | The vehicle maintenance work has ended | | `removed` | `non_operational` | N/A | `recommissioned` | The vehicle has been re-added to the Provider's fleet after being previously `decommissioned` | +| `reserved` | `available` | N/A | `driver_cancellation` | The driver has canceled the reservation | | `reserved` | `available` | N/A | `customer_cancellation` | The customer has canceled the reservation | | `reserved` | `available` | N/A | `provider_cancellation` | The provider has canceled the reservation | | `reserved` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left the jurisdiction while in a reservation | | `reserved` | `non_contactable` | N/A | `comms_lost` | The vehicle went out of comms while being reserved by a passenger | -| `reserved` | `stopped` | `stopped` | `reservation_stop` | The customer has activated the vehicle | +| `reserved` | `stopped` | `stopped` | `reservation_stop` | The customer has activated the vehicle | +| `stopped` | `available` | N/A | `driver_cancellation` | The driver has canceled the trip | | `stopped` | `available` | N/A | `customer_cancellation` | The customer has canceled the trip | | `stopped` | `available` | N/A | `provider_cancellation` | The provider has canceled the trip | | `stopped` | `available` | N/A | `trip_end` | The trip has been successfully completed | From 5f5e98eada341abf45ceee4b9e705dcf5d3d7efe Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Wed, 18 Oct 2023 12:34:31 -0700 Subject: [PATCH 08/14] Update provider vehicles endpoints descriptions The description of the Provider vehicles endpoints was never really updated in the MDS 1 -> 2 transition so this rearranges and clarifies some things now that there are two vehicle information endpoints, one for static information like vehicle/propulsion type and another for realtime status. These changes are mostly rearranging/clarifying, but there is one major addition to the description of the `/vehicles` endpoint describing that when called without a device ID it is expected to return every vehicle ever deployed in a jurisdiction. --- provider/README.md | 37 ++++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/provider/README.md b/provider/README.md index e4f7b09a..125108ca 100644 --- a/provider/README.md +++ b/provider/README.md @@ -168,22 +168,19 @@ For Timestamps, Vehicle Types, Propulsion Types, UUIDs, Costs, and Currencies, r ## Vehicles -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. +There are two vehicles related endpoints: -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. +- `/vehicles` returns unchanging information about vehicles such as vehicle and propulsion type +- `/vehicles/status` returns the current status of vehicles for real-time monitoring -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]: +As with other MDS APIs, the vehicles endpoints are intended for use by regulators, not by the general public. They can be deployed by providers as standalone MDS endpoints 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 endpoints does not replace the role of a public [GBFS][gbfs] feed in enabling consumer-facing applications. If a provider is using both the vehicles endpoints and GBFS endpoints, the vehicles endpoints should be considered source of truth regarding an agency's compliance checks. -```json -{ - "version": "x.y.z", - "last_updated": "12345", - "ttl": "12345", - "vehicles": [] -} -``` +### Vehicle Information -The `/vehicles` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles. Contains vehicle properties that do not change often. +The `/vehicles` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles. +It contains vehicle properties that do not change often. +When `/vehicles` is called without specifying a device ID it should return every vehicle that has +ever been deployed in an agency's [Jurisdiction](/general-information.md#definitions) and/or area of agency responsibility. **Endpoint:** `/vehicles/{device_id}` **Method:** `GET` @@ -228,7 +225,21 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem ### Vehicle Status -The `/vehicles/status` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles. Contains specific vehicle status records that are updated frequently. +The `/vehicles/status` endpoint 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 [PROW](/general-information.md#definitions) state [`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`, `removed`, and `missing`, which include vehicles not in the [PROW](/general-information.md#definitions) but provide some operational clarity for agencies, these vehicles must only persist in the feed for 90 minutes before being removed (and should persist in the feed for at least 90 minutes). + +The `/vehicles/status` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles. +It contains specific vehicle status records that are updated frequently. + +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]: + +```json +{ + "version": "x.y.z", + "last_updated": "12345", + "ttl": "12345", + "vehicles": [] +} +``` **Endpoint:** `/vehicles/status/{device_id}` **Method:** `GET` From 00c05fbc15b52e35e5c88cb891839d2e9f9d2a29 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 30 Oct 2023 15:15:24 -0400 Subject: [PATCH 09/14] Reworded comment for start_date in Reports --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 304a43cf..ab4f7960 100644 --- a/data-types.md +++ b/data-types.md @@ -247,7 +247,7 @@ A Report is defined by the following structure: | Column Name | Type | Comments | |----------------------| ----------------------------------------- | ------------------------------------------------ | | `provider_id` | UUID | A UUID for the Provider, unique within MDS. See MDS provider_id in [provider list](/providers.csv). | -| `start_date` | date | Start date of trip the data row, ISO 8601 date format, i.e. YYYY-MM-DD | +| `start_date` | date | Start date of the [Trip](#trips) data row, in ISO 8601 date format, i.e. YYYY-MM-DD | | `duration` | string | Value is always `P1M` for monthly. Based on [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) | | `special_group_type` | [Special Group Type](#special-group-type) | Type that applies to this row | | `geography_id` | [Geography](/geography) | ID that applies to this row. Includes all IDs in /geography. When there is no /geography then return `null` for this value and return counts based on the entire operating area. | From 08af501fc01355547f12f3b7a0d27f2d74383909 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Mon, 30 Oct 2023 14:56:47 -0700 Subject: [PATCH 10/14] Fix key in /vehicles/status example response The example API response for the /vehicles/status endpoint had the data key as 'vehicles' when it is in fact 'vehicles_status'. --- provider/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/provider/README.md b/provider/README.md index e45f2c72..2698ac37 100644 --- a/provider/README.md +++ b/provider/README.md @@ -247,7 +247,7 @@ If `device_id` is specified, `GET` will return an array with a vehicle status re ```json { "version": "x.y.z", - "vehicles": [ ... ] + "vehicles_status": [ ... ] "links": { "first": "https://...", "last": "https://...", From bf2326930d889fa26966ff9e4ef5bd229ab7dea0 Mon Sep 17 00:00:00 2001 From: Brian Grass Date: Tue, 5 Dec 2023 11:59:52 -0800 Subject: [PATCH 11/14] Address PR feedback --- data-types.md | 8 ++++---- provider/README.md | 6 ++---- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/data-types.md b/data-types.md index 7c3a8b62..828765ee 100644 --- a/data-types.md +++ b/data-types.md @@ -5,11 +5,11 @@ This MDS data types page catalogs the objects (fields, types, requirements, desc ## Table of Contents - [Vehicles](#vehicles) - - [Vehicle Types][vehicle-types] + - [Vehicle Types](#vehicle-types) - [Propulsion Types](#propulsion-types) - [Vehicle Status](#vehicle-status) - [Events](#events) - - [Event Types](/modes/event_types.md) + - [Event Times](#event-times) - [Telemetry](#telemetry) - [GPS Data][gps] - [Stops](#stops) @@ -108,7 +108,7 @@ Events represent changes in vehicle status. | `event_types` | Enum[] | Required | Vehicle [event types][vehicle-events] for state change, with allowable values determined by `vehicle_state` | | `timestamp` | [Timestamp][ts] | Required | Date/time that event occurred at. See [Event Times][event-times] | | `publication_time` | [Timestamp][ts] | Optional | Date/time that event became available through the status changes endpoint | -| `location` | [GPS][gps] | Required | See also [Stop-based Geographic Data][stop-based-geo]. | +| `location` | [GPS][gps] | Required | See also [Telemetry][telemetry]. | | `event_geographies` | UUID[] | Optional | **[Beta feature](/general-information.md#beta-features):** *Yes (as of 2.0.0)*. Array of Geography UUIDs consisting of every Geography that contains the location of the status change. See [Geography Driven Events][geography-driven-events]. Required if `location` is not present. | | `battery_percent` | Integer | Required if Applicable | Percent battery charge of vehicle, expressed between 0 and 100 | | `fuel_percent` | Integer | Required if Applicable | Percent fuel in vehicle, expressed between 0 and 100 | @@ -302,8 +302,8 @@ Other special group types may be added in future MDS releases as relevant agency [iso4217]: https://en.wikipedia.org/wiki/ISO_4217#Active_codes [modes]: /modes/README.md [propulsion-types]: #propulsion-types -[stop-based-geo]: /general-information.md#stop-based-geographic-data [stops]: #stops +[telemetry]: #telemetry [toc]: #table-of-contents [ts]: /general-information.md#timestamps [vehicle-states]: /general-information.md#vehicle-states diff --git a/provider/README.md b/provider/README.md index e4f7b09a..0e989262 100644 --- a/provider/README.md +++ b/provider/README.md @@ -273,7 +273,7 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem ## Trips -A [trip][trips-general-info] represents a journey taken by a *mobility as a service* customer with a geo-tagged start and stop point. +A [trip][trips] represents a journey taken by a *mobility as a service* customer with a geo-tagged start and stop point. The trips endpoint allows a user to query historical trip data. @@ -441,7 +441,7 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem The `/events/recent` endpoint is a near-realtime feed of events less than two weeks old. -See also [Stop-based Geographic Data][stop-based-geo]. +See also [Telemetry][telemetry]. **Endpoint:** `/events/recent` **Method:** `GET` @@ -574,12 +574,10 @@ See [Provider examples](examples.md#reports). [responses]: /general-information.md#responses [schema]: /schema/ [stops]: /data-types.md#stops -[stop-based-geo]: /general-information.md#stop-based-geographic-data [telemetry]: /data-types.md#telemetry [telemetry---query-parameters]: #telemetry-query-parameters [toc]: #table-of-contents [trips]: /data-types.md#trips -[trips-general-info]: /general-information.md#stop-based-geographic-data [ts]: /general-information.md#timestamps [vehicles]: /data-types.md#vehicles [vehicle-types]: /data-types.md#vehicle-types From 90ad321e0d994c98f9af0965d5e5b857873d95e7 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Thu, 7 Dec 2023 10:46:25 -0800 Subject: [PATCH 12/14] Update /vehicles endpoint description - Specify that /vehicles called without a device ID should return all vehicles deployed in a region in the last thirty days - Specify that vehicle information about all device IDs present in MDS data for a region must be accessible via /vehicles/device_id regardless of when the vehicle was deployed --- provider/README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/provider/README.md b/provider/README.md index 125108ca..fe251c50 100644 --- a/provider/README.md +++ b/provider/README.md @@ -170,17 +170,20 @@ For Timestamps, Vehicle Types, Propulsion Types, UUIDs, Costs, and Currencies, r There are two vehicles related endpoints: -- `/vehicles` returns unchanging information about vehicles such as vehicle and propulsion type +- `/vehicles` returns rarely changed information about vehicles such as vehicle and propulsion type - `/vehicles/status` returns the current status of vehicles for real-time monitoring As with other MDS APIs, the vehicles endpoints are intended for use by regulators, not by the general public. They can be deployed by providers as standalone MDS endpoints 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 endpoints does not replace the role of a public [GBFS][gbfs] feed in enabling consumer-facing applications. If a provider is using both the vehicles endpoints and GBFS endpoints, the vehicles endpoints should be considered source of truth regarding an agency's compliance checks. ### Vehicle Information -The `/vehicles` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles. +The `/vehicles` endpoint returns the specified vehicle (if a `device_id` is provided) or a list of vehicles. It contains vehicle properties that do not change often. When `/vehicles` is called without specifying a device ID it should return every vehicle that has -ever been deployed in an agency's [Jurisdiction](/general-information.md#definitions) and/or area of agency responsibility. +been deployed in an agency's [Jurisdiction](/general-information.md#definitions) and/or area of agency responsibility +in the last 30 days. +Vehicle information about all device IDs present in other MDS endpoints must be acessible via the +`/vehicles/{device_id}` style call regardless of when they were deployed. **Endpoint:** `/vehicles/{device_id}` **Method:** `GET` From 240af57570efa1266d6ddda66d8295b7705a6c05 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 18 Dec 2023 15:25:22 -0500 Subject: [PATCH 13/14] Add Nextbike --- providers.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/providers.csv b/providers.csv index a0f3118e..8dfdd122 100644 --- a/providers.csv +++ b/providers.csv @@ -50,3 +50,4 @@ Whoosh,micromobility,3f8908a7-86fa-450d-8889-5d49077e06cd,https://whoosh.bike,ht Telofun,micromobility,3dd253d3-557c-4fcb-98da-9af3edeaaae6,https://www.tel-o-fun.co.il/,https://mds.fsmctmobility.com/api/mds/v1/, Gbike,micromobility,a50b796e-bca2-11ed-afa1-0242ac120002,https://gcoo.io/,https://mds.gcoo.io/,https://mds.gcoo.io/gbfs SURF,micromobility,66c43ccb-f9f9-4f70-9707-37301b9f49a8,https://www.surfingscooters.com,https://api.app.surf/mds,https://api.app.surf/gbfs/en +Nextbike,micromobility,31e54f5a-66c4-4a4c-bb6e-236351c90312,https://www.nextbike.de,https://platform-services.tier-services.io/data-sharing/mds/,https://api.nextbike.net/maps/gbfs/ From e2d1916b09176543363f00c4106f750d6f548e33 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 18 Dec 2023 15:53:18 -0500 Subject: [PATCH 14/14] Update ReleaseNotes.md --- ReleaseNotes.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/ReleaseNotes.md b/ReleaseNotes.md index 629c4a30..b1e59545 100644 --- a/ReleaseNotes.md +++ b/ReleaseNotes.md @@ -1,3 +1,31 @@ +## 2.0.1 + +> Release 2023-12-18 + +The 2.0.1 release fixes some minor issues and typos to help make the specifcation clearer. + +### CHANGES + +See the closed PRs tagged with [Milestone 2.0.1](https://github.com/openmobilityfoundation/mobility-data-specification/pulls?q=is%3Apr+is%3Aclosed+milestone%3A2.0.1) and [Issues](https://github.com/openmobilityfoundation/mobility-data-specification/issues?q=is%3Aissue+milestone%3A2.0.1+is%3Aclosed) for a full list of changes. + +**Minor updates** + +- [#879](https://github.com/openmobilityfoundation/mobility-data-specification/issues/879) Clarify which vehicles are included in the MDS 2.0 /vehicles endpoint +- [#868](https://github.com/openmobilityfoundation/mobility-data-specification/issues/868) Correction of description vehicle events (car sharing) bug Car Share + +**Typos and wording clarifications** + +- [#880](https://github.com/openmobilityfoundation/mobility-data-specification/issues/880) Remove word "data" from provider response payload descriptions +- [#894](https://github.com/openmobilityfoundation/mobility-data-specification/issues/894) Fixing broken links in data-types markdown document +- [#876](https://github.com/openmobilityfoundation/mobility-data-specification/issues/876) Reports endpoint - START_DATE clarification +- [#884](https://github.com/openmobilityfoundation/mobility-data-specification/issues/884) Fix JSON key in /vehicles/status example response +- [#878](https://github.com/openmobilityfoundation/mobility-data-specification/issues/878) Update "status changes" to "events" in provider + +**Identifier updates** + +- [#872](https://github.com/openmobilityfoundation/mobility-data-specification/issues/872) Add GBFS endpoint for Whoosh +- [#890](https://github.com/openmobilityfoundation/mobility-data-specification/issues/890) Add Nextbike + ## 2.0.0 > Released 2023-05-09