diff --git a/agency/README.md b/agency/README.md index e1afb8fe..4b66b82a 100644 --- a/agency/README.md +++ b/agency/README.md @@ -250,8 +250,8 @@ 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.accuracy` | Float | Required if Available | Accuracy in meters | +| `gps.speed` | Float | Required if Available | Estimated speed in meters / sec as reported by the GPS chipset | +| `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 c1042616..a34db377 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 | Estimated speed in meters / sec as reported by the GPS chipset | +| `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 + +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 b9edaefc..1384ecd6 100644 --- a/provider/README.md +++ b/provider/README.md @@ -218,7 +218,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. @@ -290,7 +290,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` | @@ -573,8 +573,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] @@ -590,7 +590,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 @@ -599,6 +598,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