From 77f122f8bf8031eab1c9d875724aa72690c776d3 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Wed, 26 Sep 2018 22:09:11 -0700 Subject: [PATCH] clarifying location type --- provider/README.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/provider/README.md b/provider/README.md index e5a65f28..a8ec0df7 100644 --- a/provider/README.md +++ b/provider/README.md @@ -71,6 +71,25 @@ 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)](https://en.wikipedia.org/wiki/World_Geodetic_System) standard GPS projection expressed as [Decimal Degrees](https://en.wikipedia.org/wiki/Decimal_degrees). +Whenever an individual location coordinate measurement is presented, it must be +represented as a GeoJSON [`Feature`](https://tools.ietf.org/html/rfc7946#section-3.2) object with a corresponding [`timestamp`][ts] property and [`Point`](https://tools.ietf.org/html/rfc7946#section-3.1.2) geometry: + +```json +{ + "type": "Feature", + "properties": { + "timestamp": 1529968782.421409 + }, + "geometry": { + "type": "Point", + "coordinates": [ + -118.46710503101347, + 33.9909333514159 + ] + } +} +``` + [Top][toc] ### Timestamps @@ -101,7 +120,7 @@ Data: `{ "trips": [] }`, an array of objects with the following structure | `trip_id` | UUID | Required | A unique ID for each trip | | `trip_duration` | Integer | Required | Time, in Seconds | | `trip_distance` | Integer | Required | Trip Distance, in Meters | -| `route` | Route | Required | See detail below | +| `route` | GeoJSON `FeatureCollection` | Required | See [Routes](#routes) detail below | | `accuracy` | Integer | Required | The approximate level of accuracy, in meters, of `Points` within `route` | | `start_time` | [timestamp][ts] | Required | | | `end_time` | [timestamp][ts] | Required | | @@ -127,8 +146,7 @@ For example: bbox=-122.4183,37.7758,-122.4120,37.7858 ``` -Gets all trips within that bounding-box where any point inside the `route` is inside said box. The order is definied as: southwest longitude, southwest latitude, northeast longitude, northeast latitude (separated by commas). - +Gets all trips within that bounding-box where any point inside the `route` is inside said box. The order is defined as: southwest longitude, southwest latitude, northeast longitude, northeast latitude (separated by commas). ### Vehicle Types @@ -148,7 +166,7 @@ Gets all trips within that bounding-box where any point inside the `route` is in ### Routes -To represent a route, MDS `provider` APIs should create a GeoJSON Feature Collection, which includes every observed point in the route, and a [timestamp][ts]. +To represent a route, MDS `provider` APIs must create a GeoJSON [`FeatureCollection`](https://tools.ietf.org/html/rfc7946#section-3.3), which includes every [observed point][geo] in the route. Routes must include at least 2 points: the start point and end point. Additionally, routes must include all possible GPS samples collected by a provider. @@ -207,7 +225,7 @@ Data: `{ "status_changes": [] }`, an array of objects with the following structu | `event_type` | Enum | Required | See [event types](#event-types) table | | `event_type_reason` | Enum | Required | Reason for status change, allowable values determined by [`event type`](#event-types) | | `event_time` | [timestamp][ts] | Required | Date/time that event occurred, based on device clock | -| `event_location` | Point | Required | | +| `event_location` | GeoJSON [Point Feature][geo] | Required | | | `battery_pct` | Float | Required if Applicable | Percent battery charge of device, expressed between 0 and 1 | | `associated_trips` | UUID[] | Optional based on device | Array of UUID's. For "Reserved" event types, associated trips (foreign key to Trips API) | @@ -251,5 +269,6 @@ All MDS compatible `provider` APIs must expose a [GBFS](https://github.com/NABSA [Top][toc] +[geo]: #geographic-data [toc]: #table-of-contents [ts]: #timestamps \ No newline at end of file