Skip to content

Commit a9ae3a8

Browse files
schnuerleschnuerle
committed
Rearranged Provider readme
1 parent 6330d48 commit a9ae3a8

1 file changed

Lines changed: 75 additions & 78 deletions

File tree

‎provider/README.md‎

Lines changed: 75 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -13,31 +13,30 @@ This specification contains a data standard for *mobility as a service* provider
1313
* [Modes](#modes)
1414
* [Responses and Error Messages](#responses-and-error-messages)
1515
* [GBFS](#GBFS)
16+
* [Data Latency Requirements][data-latency]
1617
* [JSON Schema](#json-schema)
1718
* [Pagination](#pagination)
1819
* [Municipality Boundary](#municipality-boundary)
1920
* [Event Times](#event-times)
2021
* [Other Data Types](#other-data-types)
2122
* [Trips][trips]
2223
* [Trips - Query Parameters](#trips---query-parameters)
24+
* [Trips - Responses](#trips---responses)
2325
* [Routes](#routes)
26+
* [Telemetry][telemetry]
27+
* [Telemetry - Query Parameters](#telemetry---query-parameters)
2428
* [Events][events]
29+
* [Historical Events - Query Parameters](#events---query-parameters)
30+
* [Historical Events - Responses](#historical-events---responses)
2531
* [Recent Events](#recent-events)
2632
* [Recent Events - Query Parameters](#recent-events---query-parameters)
27-
* [Historical Events](#historical-events)
28-
* [Historical Events - Query Parameters](#events---query-parameters)
29-
* [Telemetry][telemetry]
30-
* [Telemetry - Query Parameters](#telemetry---query-parameters)
3133
* [Vehicles][vehicles]
34+
* [Stops](#stops)
3235
* [Reports](#reports)
3336
* [Reports - Response](#reports---response)
3437
* [Reports - Example](#reports---example)
3538
* [Data Redaction](#data-redaction)
36-
* [Realtime Data](#realtime-data)
37-
* [Data Latency Requirements][data-latency]
38-
* [Events][events]
39-
* [Stops](#stops)
40-
* [Vehicles][vehicles]
39+
4140

4241
## General Information
4342

@@ -91,6 +90,17 @@ See the [GBFS Requirement](/README.md#gbfs-requirement) language for more detail
9190

9291
[Top][toc]
9392

93+
### Data Latency Requirements
94+
95+
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:
96+
97+
Field Name | Required | Defines
98+
--------------------| ----------| ----------
99+
last_updated | Yes | Timestamp indicating the last time the data in this feed was updated
100+
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).
101+
102+
[Top][toc]
103+
94104
### JSON Schema
95105

96106
MDS defines [JSON Schema][json-schema] files for each endpoint.
@@ -251,6 +261,29 @@ Trips that start or end at a [Stop][stops] must include a `stop_id` property in
251261

252262
[Top][toc]
253263

264+
## Telemetry
265+
266+
The `/telemetry` endpoint is a feed of vehicle telemetry data for publishing all available location data. For privacy reasons, in-trip telemetry may be delayed at the discretion of the regulating body.
267+
268+
Unless stated otherwise by the municipality, this endpoint must return only those telemetry that [intersects][intersection] with the [municipality boundary][muni-boundary].
269+
270+
> Note: As a result of this definition, consumers should query the [trips endpoint][trips] to infer when vehicles enter or leave the municipality boundary.
271+
272+
**Endpoint:** `/telemetry`
273+
**Method:** `GET`
274+
**Schema:** [`telemetry` schema][telemetry-schema]
275+
**`data` Payload:** `{ "telemetry": [] }`, an array of `telemetry` objects
276+
277+
### Telemetry - Query Parameters
278+
279+
| Parameter | Format | Expected Output |
280+
| --------- | ------ | --------------- |
281+
| `telemetry_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 telemetry with timestamp occurring within the hour. For example, requesting `telemetry_time=2019-10-01T07` returns all telemetry where `2019-10-01T07:00:00 <= telemetry.timestamp < 2019-10-01T08:00:00` UTC. |
282+
283+
Without a `telemetry_time` query parameter, `/telemetry` shall return a `400 Bad Request` error.
284+
285+
[Top][toc]
286+
254287
## Events
255288

256289
The `/events/recent` and `/events/historical/` endpoints return a list of Event objects, describing the activity of the Provider's vehicles. Recent events are at most two weeks old and can be queried with start/stop time, and historical events are packaged in hour-sized chunks for ease of implementation.
@@ -316,7 +349,7 @@ See also [Stop-based Geographic Data][stop-based-geo].
316349
**Schema:** [`events` schema][events-schema]
317350
**`data` Payload:** `{ "events": [] }`, an array of Event objects
318351

319-
#### Recent Events Query Parameters
352+
#### Recent Events - Query Parameters
320353

321354
The Recent Events API requires two parameters:
322355

@@ -331,44 +364,34 @@ Should either side of the requested time range be greater than 2 weeks before th
331364

332365
[Top][toc]
333366

334-
## Reports
367+
## Vehicles
335368

336-
Reports are information that providers can send back to agencies containing aggregated data that is not contained within other MDS endpoints, like counts of special groups of riders. These supplemental reports are not a substitute for other MDS Provider endpoints.
337-
338-
The authenticated reports are monthly, historic flat files that may be pre-generated by the provider.
339-
340-
### Reports - Response
341-
342-
**Endpoint:** `/reports`
343-
**Method:** `GET`
344-
**[Beta feature][beta]:** No (as of 2.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/672)
345-
**Usage note:** This endpoint uses media-type `text/vnd.mds+csv` instead of `application/vnd.mds+json`, see [Versioning][versioning].
346-
**Schema:** TBD
347-
**`data` Filename:** monthly file named by year and month, e.g. `/reports/YYYY-MM.csv`
348-
**`data` Payload:** monthly CSV files of [Report](/data-types.md#Reports) objects
349-
350-
[Top][toc]
351-
352-
### Reports - Example
353-
354-
See [Provider examples](examples.md#reports).
355-
356-
[Top][toc]
369+
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.
357370

358-
## Realtime Data
371+
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.
359372

360-
### Data Latency Requirements
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]:
361374

362-
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:
375+
```json
376+
{
377+
"version": "x.y.z",
378+
"data": {
379+
"vehicles": []
380+
},
381+
"last_updated": "12345",
382+
"ttl": "12345"
383+
}
384+
```
363385

364-
Field Name | Required | Defines
365-
--------------------| ----------| ----------
366-
last_updated | Yes | Timestamp indicating the last time the data in this feed was updated
367-
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).
386+
**Endpoint:** `/vehicles`
387+
**Method:** `GET`
388+
**[Beta feature][beta]:** No (as of 1.2.0)
389+
**Schema:** [`vehicles` schema][vehicles-schema]
390+
**`data` Payload:** `{ "vehicles": [] }`, an array of [Vehicle](vehicle) objects
368391

369392
[Top][toc]
370393

371-
### Stops
394+
## Stops
372395

373396
Stop information should be updated on a near-realtime basis by providers who operate _docked_ mobility devices in a given municipality.
374397

@@ -395,53 +418,27 @@ In the case that a `stop_id` query parameter is specified, the `stops` array ret
395418

396419
[Top][toc]
397420

398-
### Telemetry
421+
## Reports
399422

400-
The `/telemetry` endpoint is a feed of vehicle telemetry data for publishing all available location data. For privacy reasons, in-trip telemetry may be delayed at the discretion of the regulating body.
423+
Reports are information that providers can send back to agencies containing aggregated data that is not contained within other MDS endpoints, like counts of special groups of riders. These supplemental reports are not a substitute for other MDS Provider endpoints.
401424

402-
Unless stated otherwise by the municipality, this endpoint must return only those telemetry that [intersects][intersection] with the [municipality boundary][muni-boundary].
425+
The authenticated reports are monthly, historic flat files that may be pre-generated by the provider.
403426

404-
> Note: As a result of this definition, consumers should query the [trips endpoint][trips] to infer when vehicles enter or leave the municipality boundary.
427+
### Reports - Response
405428

406-
**Endpoint:** `/telemetry`
429+
**Endpoint:** `/reports`
407430
**Method:** `GET`
408-
**Schema:** [`telemetry` schema][telemetry-schema]
409-
**`data` Payload:** `{ "telemetry": [] }`, an array of `telemetry` objects
410-
411-
#### Telemetry - Query Parameters
412-
413-
| Parameter | Format | Expected Output |
414-
| --------- | ------ | --------------- |
415-
| `telemetry_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 telemetry with timestamp occurring within the hour. For example, requesting `telemetry_time=2019-10-01T07` returns all telemetry where `2019-10-01T07:00:00 <= telemetry.timestamp < 2019-10-01T08:00:00` UTC. |
416-
417-
Without a `telemetry_time` query parameter, `/telemetry` shall return a `400 Bad Request` error.
431+
**[Beta feature][beta]:** No (as of 2.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/672)
432+
**Usage note:** This endpoint uses media-type `text/vnd.mds+csv` instead of `application/vnd.mds+json`, see [Versioning][versioning].
433+
**Schema:** TBD
434+
**`data` Filename:** monthly file named by year and month, e.g. `/reports/YYYY-MM.csv`
435+
**`data` Payload:** monthly CSV files of [Report](/data-types.md#Reports) objects
418436

419437
[Top][toc]
420438

421-
### Vehicles
422-
423-
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.
424-
425-
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.
426-
427-
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]:
428-
429-
```json
430-
{
431-
"version": "x.y.z",
432-
"data": {
433-
"vehicles": []
434-
},
435-
"last_updated": "12345",
436-
"ttl": "12345"
437-
}
438-
```
439+
### Reports - Example
439440

440-
**Endpoint:** `/vehicles`
441-
**Method:** `GET`
442-
**[Beta feature][beta]:** No (as of 1.2.0)
443-
**Schema:** [`vehicles` schema][vehicles-schema]
444-
**`data` Payload:** `{ "vehicles": [] }`, an array of [Vehicle](vehicle) objects
441+
See [Provider examples](examples.md#reports).
445442

446443
[Top][toc]
447444

0 commit comments

Comments
 (0)