From 1424c63442f4e9180d3fb379be46a634c3f8db2e Mon Sep 17 00:00:00 2001 From: William Henderson Date: Mon, 5 Jul 2021 17:21:32 -0700 Subject: [PATCH 1/6] Add rich telemetry data to provider by extending Geographic Data definitions --- general-information.md | 26 +++++++++++++++++++++++--- provider/README.md | 12 ++++++------ 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/general-information.md b/general-information.md index c1042616..28f54683 100644 --- a/general-information.md +++ b/general-information.md @@ -9,6 +9,7 @@ This document contains specifications that are shared between the various MDS AP * [Definitions](#definitions) * [Devices](#devices) * [Geographic Data][geo] + * [Geographic Telemetry Data](#geographic-telemetry-data) * [Stop-based Geographic Data](#stop-based-geographic-data) * [Intersection Operation](#intersection-operation) * [Geography-Driven Events](#geography-driven-events) @@ -73,14 +74,32 @@ Additionally, `device_id` must remain constant for the device's lifetime of serv 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]. When points are used, you may assume a 20 meter buffer around the point when needed. -Whenever an individual location coordinate measurement is presented, it must be -represented as a GeoJSON [`Feature`][geojson-feature] object with a corresponding [`timestamp`][ts] property and [`Point`][geojson-point] geometry: +### Geographic Telemetry Data + +Whenever a vehicle location coordinate measurement is presented, it must be +represented as a GeoJSON [`Feature`][geojson-feature] object with a corresponding +`properties` object with the following properties: + + +| Field | Type | Required/Optional | Field Description | +| -------------- | -------------- | --------------------- | ------------------------------------------------------------ | +| `timestamp` | [timestamp][ts] | Required | Date/time that event occurred. Based on GPS or GNSS clock | +| `altitude` | Double | Required if Available | Altitude above mean sea level in meters | +| `heading` | Double | Required if Available | Degrees - clockwise starting at 0 degrees at true North | +| `speed` | Float | Required if Available | Speed in meters / sec | +| `accuracy` | Float | Required if Available | Accuracy in meters | +| `hdop` | Float | Required if Available | Horizontal GPS or GNSS accuracy value (see [hdop][hdop]) | +| `satellites` | Integer | Required if Available | Number of GPS or GNSS satellites + +Example of a vehicle location GeoJSON [`Feature`][geojson-feature] object: ```json { "type": "Feature", "properties": { - "timestamp": 1529968782421 + "timestamp": 1529968782421, + "accuracy": 10, + "speed": 1.21 }, "geometry": { "type": "Point", @@ -444,6 +463,7 @@ If an unsupported or invalid version is requested, the API must respond with a s [agency]: /agency/README.md [decimal-degrees]: https://en.wikipedia.org/wiki/Decimal_degrees +[hdop]: https://en.wikipedia.org/wiki/Dilution_of_precision_(navigation) [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 [general-stops]: /general-information.md#stops diff --git a/provider/README.md b/provider/README.md index a0eeea21..b4e15d2f 100644 --- a/provider/README.md +++ b/provider/README.md @@ -199,7 +199,7 @@ For the near-ish real time use cases, please use the [events][events] endpoint. ### Routes -To represent a route, MDS `provider` APIs must create a GeoJSON [`FeatureCollection`][geojson-feature-collection], which includes every [observed point][geo] in the route, even those which occur outside the [municipality boundary][muni-boundary]. +To represent a route, MDS `provider` APIs must create a GeoJSON [`FeatureCollection`][geojson-feature-collection], which includes every [observed point][point-geo] in the route, even those which occur outside the [municipality boundary][muni-boundary]. Routes must include at least 2 points: the start point and end point. Routes must include all possible GPS or GNSS samples collected by a Provider. Providers may round the latitude and longitude to the level of precision representing the maximum accuracy of the specific measurement. For example, [a-GPS][agps] is accurate to 5 decimal places, [differential GPS][dgps] is generally accurate to 6 decimal places. Providers may round those readings to the appropriate number for their systems. @@ -271,7 +271,7 @@ Unless stated otherwise by the municipality, this endpoint must return only thos | `event_types` | Enum[] | Required | [Vehicle event(s)][vehicle-events] for state change, allowable values determined by `vehicle_state` | | `event_time` | [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 | -| `event_location` | GeoJSON [Point Feature][geo] | Required | See also [Stop-based Geographic Data][stop-based-geo]. | +| `event_location` | GeoJSON [Point Feature][point-geo] | Required | See also [Stop-based Geographic Data][stop-based-geo]. | | `event_geographies` | UUID[] | Optional | **[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.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 `event_location` is not present. | | `battery_pct` | Float | Required if Applicable | Percent battery charge of device, expressed between 0 and 1 | | `trip_id` | UUID | Required if Applicable | Trip UUID (foreign key to Trips API), required if `event_types` contains `trip_start`, `trip_end`, `trip_cancel`, `trip_enter_jurisdiction`, or `trip_leave_jurisdiction` | @@ -535,8 +535,8 @@ In addition to the standard [Provider payload wrapper](#response-format), respon | `last_event_time` | [timestamp][ts] | Required | Date/time when last state change occurred. See [Event Times][event-times] | | `last_vehicle_state` | Enum | Required | [Vehicle state][vehicle-states] of most recent state change. | | `last_event_types` | Enum[] | Required | [Vehicle event(s)][vehicle-events] of most recent state change, allowable values determined by `last_vehicle_state`. | -| `last_event_location` | GeoJSON [Point Feature][geo]| Required | Location of vehicle's last event. See also [Stop-based Geographic Data][stop-based-geo]. | -| `current_location` | GeoJSON [Point Feature][geo] | Required if Applicable | Current location of vehicle if different from last event, and the vehicle is not currently on a trip. See also [Stop-based Geographic Data][stop-based-geo]. | +| `last_event_location` | GeoJSON [Point Feature][point-geo]| Required | Location of vehicle's last event. See also [Stop-based Geographic Data][stop-based-geo]. | +| `current_location` | GeoJSON [Point Feature][point-geo] | Required if Applicable | Current location of vehicle if different from last event, and the vehicle is not currently on a trip. See also [Stop-based Geographic Data][stop-based-geo]. | | `battery_pct` | Float | Required if Applicable | Percent battery charge of device, expressed between 0 and 1 | [Top][toc] @@ -552,7 +552,6 @@ In addition to the standard [Provider payload wrapper](#response-format), respon [event-times]: #event-times [gbfs]: https://github.com/NABSA/gbfs [general-information]: /general-information.md -[geo]: /general-information.md#geographic-data [geography-driven-events]: /general-information.md#geography-driven-events [geojson-feature-collection]: https://tools.ietf.org/html/rfc7946#section-3.3 [iana]: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml @@ -561,6 +560,7 @@ In addition to the standard [Provider payload wrapper](#response-format), respon [json-api-pagination]: http://jsonapi.org/format/#fetching-pagination [json-schema]: https://json-schema.org [muni-boundary]: #municipality-boundary +[point-geo]: /general-information.md#geographic-telemetry-data [propulsion-types]: /general-information.md#propulsion-types [responses]: /general-information.md#responses [status]: #status-changes @@ -577,4 +577,4 @@ In addition to the standard [Provider payload wrapper](#response-format), respon [vehicle-states]: /general-information.md#vehicle-states [vehicle-events]: /general-information.md#vehicle-state-events [vehicles-schema]: vehicles.json -[versioning]: /general-information.md#versioning +[versioning]: /general-information.md#versioning \ No newline at end of file From eaa380d9c46f5dc948e2a4dd23c7d9f15d56bc49 Mon Sep 17 00:00:00 2001 From: William Henderson Date: Mon, 5 Jul 2021 17:27:27 -0700 Subject: [PATCH 2/6] Fixed mistaken removal of whitespace --- provider/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/provider/README.md b/provider/README.md index b4e15d2f..0465e89f 100644 --- a/provider/README.md +++ b/provider/README.md @@ -577,4 +577,4 @@ In addition to the standard [Provider payload wrapper](#response-format), respon [vehicle-states]: /general-information.md#vehicle-states [vehicle-events]: /general-information.md#vehicle-state-events [vehicles-schema]: vehicles.json -[versioning]: /general-information.md#versioning \ No newline at end of file +[versioning]: /general-information.md#versioning From a5382a2f8a9e1333727edfb7cd821b04999da1db Mon Sep 17 00:00:00 2001 From: William Henderson Date: Mon, 5 Jul 2021 17:54:37 -0700 Subject: [PATCH 3/6] Clarified source and accuracy of speed field --- general-information.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/general-information.md b/general-information.md index 28f54683..42781a97 100644 --- a/general-information.md +++ b/general-information.md @@ -86,7 +86,7 @@ represented as a GeoJSON [`Feature`][geojson-feature] object with a correspondin | `timestamp` | [timestamp][ts] | Required | Date/time that event occurred. Based on GPS or GNSS clock | | `altitude` | Double | Required if Available | Altitude above mean sea level in meters | | `heading` | Double | Required if Available | Degrees - clockwise starting at 0 degrees at true North | -| `speed` | Float | Required if Available | Speed in meters / sec | +| `speed` | Float | Required if Available | Estimated speed in meters / sec as reported by the GPS chipset. | | `accuracy` | Float | Required if Available | Accuracy in meters | | `hdop` | Float | Required if Available | Horizontal GPS or GNSS accuracy value (see [hdop][hdop]) | | `satellites` | Integer | Required if Available | Number of GPS or GNSS satellites From 3e8ed25508181d5da7306d4159ee1142894b8b34 Mon Sep 17 00:00:00 2001 From: William Henderson Date: Mon, 5 Jul 2021 17:56:41 -0700 Subject: [PATCH 4/6] Consistentized punctuation --- general-information.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/general-information.md b/general-information.md index 42781a97..f35f9477 100644 --- a/general-information.md +++ b/general-information.md @@ -86,7 +86,7 @@ represented as a GeoJSON [`Feature`][geojson-feature] object with a correspondin | `timestamp` | [timestamp][ts] | Required | Date/time that event occurred. Based on GPS or GNSS clock | | `altitude` | Double | Required if Available | Altitude above mean sea level in meters | | `heading` | Double | Required if Available | Degrees - clockwise starting at 0 degrees at true North | -| `speed` | Float | Required if Available | Estimated speed in meters / sec as reported by the GPS chipset. | +| `speed` | Float | Required if Available | Estimated speed in meters / sec as reported by the GPS chipset | | `accuracy` | Float | Required if Available | Accuracy in meters | | `hdop` | Float | Required if Available | Horizontal GPS or GNSS accuracy value (see [hdop][hdop]) | | `satellites` | Integer | Required if Available | Number of GPS or GNSS satellites From 001c09abec59c4918dcfbb8472a7e666396437c8 Mon Sep 17 00:00:00 2001 From: William Henderson Date: Mon, 5 Jul 2021 17:57:05 -0700 Subject: [PATCH 5/6] Added matching GPS speed field clarification to agency --- agency/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agency/README.md b/agency/README.md index e1afb8fe..30f9f7f1 100644 --- a/agency/README.md +++ b/agency/README.md @@ -250,7 +250,7 @@ A standard point of vehicle telemetry. References to latitude and longitude impl | `gps.lng` | Double | Required | Longitude of the location | | `gps.altitude` | Double | Required if Available | Altitude above mean sea level in meters | | `gps.heading` | Double | Required if Available | Degrees - clockwise starting at 0 degrees at true North | -| `gps.speed` | Float | Required if Available | Speed in meters / sec | +| `gps.speed` | Float | Required if Available | Estimated speed in meters / sec as reported by the GPS chipset | | `gps.accuracy` | Float | Required if Available | Accuracy in meters | | `gps.hdop` | Float | Required if Available | Horizontal GPS or GNSS accuracy value (see [hdop][hdop]) | | `gps.satellites` | Integer | Required if Available | Number of GPS or GNSS satellites From 27b77408769aba2b39035e97a0093b8f5ef1fbf1 Mon Sep 17 00:00:00 2001 From: William Henderson Date: Thu, 22 Jul 2021 09:30:41 -0700 Subject: [PATCH 6/6] Specify that accuracy is horizontal accuracy --- agency/README.md | 2 +- general-information.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/agency/README.md b/agency/README.md index 30f9f7f1..4b66b82a 100644 --- a/agency/README.md +++ b/agency/README.md @@ -251,7 +251,7 @@ A standard point of vehicle telemetry. References to latitude and longitude impl | `gps.altitude` | Double | Required if Available | Altitude above mean sea level in meters | | `gps.heading` | Double | Required if Available | Degrees - clockwise starting at 0 degrees at true North | | `gps.speed` | Float | Required if Available | Estimated speed in meters / sec as reported by the GPS chipset | -| `gps.accuracy` | Float | Required if Available | Accuracy in meters | +| `gps.accuracy` | Float | Required if Available | Horizontal accuracy, in meters | | `gps.hdop` | Float | Required if Available | Horizontal GPS or GNSS accuracy value (see [hdop][hdop]) | | `gps.satellites` | Integer | Required if Available | Number of GPS or GNSS satellites | `charge` | Float | Required if Applicable | Percent battery charge of vehicle, expressed between 0 and 1 | diff --git a/general-information.md b/general-information.md index f35f9477..a34db377 100644 --- a/general-information.md +++ b/general-information.md @@ -87,7 +87,7 @@ represented as a GeoJSON [`Feature`][geojson-feature] object with a correspondin | `altitude` | Double | Required if Available | Altitude above mean sea level in meters | | `heading` | Double | Required if Available | Degrees - clockwise starting at 0 degrees at true North | | `speed` | Float | Required if Available | Estimated speed in meters / sec as reported by the GPS chipset | -| `accuracy` | Float | Required if Available | Accuracy in meters | +| `accuracy` | Float | Required if Available | Horizontal accuracy, in meters | | `hdop` | Float | Required if Available | Horizontal GPS or GNSS accuracy value (see [hdop][hdop]) | | `satellites` | Integer | Required if Available | Number of GPS or GNSS satellites