diff --git a/agency/README.md b/agency/README.md index 6bdccf14..26c3c201 100644 --- a/agency/README.md +++ b/agency/README.md @@ -183,7 +183,8 @@ Body Params: | `vehicle_state` | Enum | Required | see [Vehicle States][vehicle-states] | | `event_types` | Enum[] | Required | see [Vehicle Events][vehicle-events] | | `timestamp` | [timestamp][ts] | Required | Date of last event update | -| `telemetry` | [Telemetry](#telemetry-data) | Required | Single point of telemetry | +| `telemetry` | [Telemetry](#telemetry-data) | Required | Single point of telemetry. | +| `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 event. See [Geography Driven Events](#geography-driven-events). Required if `telemetry` is not present. | | `trip_id` | UUID | Optional | UUID provided by Operator to uniquely identify the trip. Required if `event_types` contains `trip_start`, `trip_end`, `trip_cancel`, `trip_enter_jurisdiction`, or `trip_leave_jurisdiction` | 201 Success Response: @@ -326,6 +327,7 @@ If `stop_id` is specified, `GET` will return an array with a single stop record, [beta]: /general-information.md#beta-features [general]: /general-information.md +[geography-driven-events]: /general-information.md#geography-driven-events [error-messages]: /general-information.md#error-messages [hdop]: https://support.esri.com/en/other-resources/gis-dictionary/term/358112bd-b61c-4081-9679-4fca9e3eb926 [propulsion-types]: /general-information.md#propulsion-types diff --git a/general-information.md b/general-information.md index ccea07d8..f33773a3 100644 --- a/general-information.md +++ b/general-information.md @@ -120,6 +120,33 @@ For the purposes of this specification, the intersection of two geographic datat > > Overlaps, Touches, Within all imply spatial intersection. If any of the aforementioned returns true, then the geometries also spatially intersect. Disjoint implies false for spatial intersection. +[Top][toc] + +## Geography-Driven Events **[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.0)* + +Geography-Driven Events is a new MDS feature for Agencies to perform complete Policy compliance monitoring without precise location data. Geography-Driven Events describe individual vehicles in realtime – not just aggregate data. However, rather than receiving the exact location of a vehicle, Agencies receive information about the vehicle's current geographic region. The regions used for Geography-Driven Events correspond to the Geographies in an Agency's current Policy. In this way, the data-shared using Geography-Driven Events is matched to an Agency's particular regulatory needs. + +Here's how it works in practice: + +1. The Agency creates a geographic Policy Area for a local regulatory need + + *Scooters traveling within downtown during peak hours incur a $0.20 fee.* + +2. Providers notify the Agency in real-time about events in the Policy Area. + + *At 5:21pm scooter X7123 entered downtown.* + +3. The Agency can refine their data needs over time by revising their published Policy Areas. + + *Agency adds rule disallowing parking on waterfront path, begins receiving data on events within area.* + + + +Agencies that wish to use Geography-Driven Events do so by requiring a new `event_geographies` field in status events. When an Agency is using Geography-Driven Events, Providers must emit a new `changed_geographies` status event whenever a vehicle in a trip enters or leaves a Geography managed by a Policy. + +During the Beta period for this feature, location and telemtry data remain required fields. This allows Aggencies to test Geography-Driven Events, measuring its accuracy and efficacy against regulatory systems based on precise location data. After the beta period, if Geography-Driven Events is deemed by OMF to be accurate and effective, the specification will evolve to allow cities to use Geography-Driven Events in lieu of location or telemtry data. + + [Top][toc] ## Propulsion Types @@ -337,6 +364,7 @@ Vehicles can enter the `unknown` state to and from any other state with the foll | `unknown` | `on_trip` | `located` | The vehicle has been located by the provider | | `unknown` | `on_trip` | `unspecified` | The provider cannot definitively state how a vehicle started a trip. | | `on_trip` | `elsewhere` | `trip_leave_jurisdiction` | A vehicle on a trip left the jurisdiction | +| `on_trip` | `on_trip ` | `changed_geographies` | **[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.0)*. The vehicle has entered or left one or more Geographies managed by a Policy. See [Geography Driven Events](#geography-driven-events).| | `unknown` | `elsewhere` | `comms_restored` | The vehicle transmitted status information after a period of being out of communication. | | `unknown` | `elsewhere` | `located` | The vehicle has been located by the provider | | `unknown` | `elsewhere` | `unspecified` | The provider cannot definitively state how a vehicle went `elsewhere`. | diff --git a/policy/README.md b/policy/README.md index 62ca2411..c4dd1ade 100644 --- a/policy/README.md +++ b/policy/README.md @@ -126,6 +126,7 @@ Method: `GET` [Top][toc] + ### Flat Files To use flat files, policies shall be represented in two (2) files: @@ -217,7 +218,7 @@ An individual `Policy` object is defined by the following fields: | `provider_ids` | UUID[] | Optional | Providers for whom this policy is applicable; empty arrays and `null`/absent implies all Providers. See MDS [provider list](/providers.csv). | | `description` | String | Required | Description of policy | | `currency` | String | Optional | An ISO 4217 Alphabetic Currency Code representing the [currency](../general-information.md#costs-and-currencies) of all Rules of [type](#rule-types) `rate`.| -| `start_date` | [timestamp][ts] | Required | Beginning date/time of policy enforcement | +| `start_date` | [timestamp][ts] | Required | Beginning date/time of policy enforcement. In order to give providers sufficient time to poll, `start_date` must be at least 20 minutes after `published_date`. | | `end_date` | [timestamp][ts] | Optional | End date/time of policy enforcement | | `published_date` | [timestamp][ts] | Required | Timestamp that the policy was published | | `prev_policies` | UUID[] | Optional | Unique IDs of prior policies replaced by this one | @@ -351,6 +352,7 @@ If a vehicle is matched with a rule, then it _will not_ be considered in the sub The internal mechanics of ordering are up to the Policy editing and hosting software. + [Top][toc] [beta]: /general-information.md#beta diff --git a/provider/README.md b/provider/README.md index 8831e7a4..77d604a7 100644 --- a/provider/README.md +++ b/provider/README.md @@ -265,7 +265,8 @@ 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][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` | | `associated_ticket` | String | Optional | Identifier for an associated ticket inside an Agency-maintained 311 or CRM system | @@ -424,6 +425,7 @@ In addition to the standard [Provider payload wrapper](#response-format), respon [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 [intersection]: /general-information.md#intersection-operation