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 diff --git a/data-types.md b/data-types.md index 304a43cf..3f292be6 100644 --- a/data-types.md +++ b/data-types.md @@ -9,7 +9,7 @@ This MDS data types page catalogs the objects (fields, types, requirements, desc - [Propulsion Types](#propulsion-types) - [Vehicle Status](#vehicle-status) - [Events](#events) - - [Event Types](#event-times) + - [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 | @@ -247,11 +247,11 @@ 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. | -| `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 [stops]: #stops +[telemetry]: #telemetry [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 diff --git a/modes/car-share.md b/modes/car-share.md index fb9e4b5a..576bcc18 100644 --- a/modes/car-share.md +++ b/modes/car-share.md @@ -241,10 +241,10 @@ This is the list of `vehicle_state` and `event_type` pairings that constitute th | `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 | `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 | | `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) | diff --git a/provider/README.md b/provider/README.md index e4f7b09a..b7e3ec0e 100644 --- a/provider/README.md +++ b/provider/README.md @@ -168,28 +168,28 @@ 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 rarely changed 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 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 +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` **[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:_ @@ -228,13 +228,27 @@ 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` **[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:_ @@ -247,7 +261,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://...", @@ -273,7 +287,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. @@ -283,7 +297,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 +362,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 +399,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] @@ -395,7 +409,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 +425,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": [] } ``` @@ -441,13 +455,13 @@ 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` **[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 +508,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 +541,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 @@ -574,12 +588,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 diff --git a/providers.csv b/providers.csv index b61e6dd1..8dfdd122 100644 --- a/providers.csv +++ b/providers.csv @@ -46,7 +46,8 @@ 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 +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/