From ab6c0e1a3f73310fc748fa8fa4e2403b813c7b12 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 3 Nov 2021 11:27:01 -0400 Subject: [PATCH 001/173] Minor text updates --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dd6d6c5c..249e65c7 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ CDS is designed to be a modular and flexible specification. Regulatory agencies ## Structure -CDS contains a series of connected endpoint and fields beneath each interconnected API. +CDS contains a series of connected endpoints and fields beneath each interconnected API. ![CDS Structure](https://i.imgur.com/L44996v.gif) @@ -71,7 +71,7 @@ CDS contains a series of connected endpoint and fields beneath each interconnect # Versions -CDS has a **current release**, and **upcoming releases** in development. For a full list of releases, their status, recommended versions, and timelines, see the [Official CDS Releases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Releases) page. +CDS has a **current release**, and an **upcoming releases** in development. For a full list of releases, their status, recommended versions, and timelines, see the [Official CDS Releases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Releases) page. ## Technical Information From 677ccdf8b2009b3e51a21a45b28975e162e946e0 Mon Sep 17 00:00:00 2001 From: Jascha Franklin-Hodge Date: Thu, 4 Nov 2021 13:23:02 -0400 Subject: [PATCH 002/173] Added stronger attribution for CurbLR. --- curbs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/curbs/README.md b/curbs/README.md index 0ec25ba5..48025bbc 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -314,7 +314,7 @@ A Curb Space is represented as a JSON object whose fields are as follows: ## Policy -A Policy object is a rule that allows or prohibits a particular set of users from using a particular curb at a particular time or times. Multiple Policy objects together define the full extent of regulations within a [Curb Zone](#curb-zone). Much of this is similar to curbLR. +A Policy object is a rule that allows or prohibits a particular set of users from using a particular curb at a particular time or times. Multiple Policy objects together define the full extent of regulations within a [Curb Zone](#curb-zone). The design of the Policy object borrows heavily from the work of the [CurbLR](https://github.com/curblr/curblr-spec) project. The `policy` field within the FeatureCollection returned by [Query Curb Zones](#query-curb-zones) contains a list of the Policy objects referenced by the returned zones. In addition, the [Query Curb Policies](#query-curb-policies) endpoint return the complete list of policies. From 13c42d1a47e4d36a5fb6ae2e5de1076358303954 Mon Sep 17 00:00:00 2001 From: Jascha Franklin-Hodge Date: Thu, 4 Nov 2021 13:27:37 -0400 Subject: [PATCH 003/173] Small language tweaks --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 249e65c7..7c439871 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,10 @@ # Overview -Urban curb is a valuable, limited, and often under-managed part of the public right of way. Curb demand is growing, including from commercial activity like passenger pickup/drop off, traditional and on-demand delivery services, new mobility programs like scooters, bikeshare, and carshare, and goods and freight delivery. While cities have made some progress in digitizing their curb and using curb data, more tools are needed to proactively manage curbs and sidewalks, and in doing so deliver more public value from this scarce resource. Curb data standards can provide a mechanism for expressing static and dynamic regulations, measuring activity at the curb, and providing access and utilization for curb users. +Urban curb is a valuable, limited, and often under-managed part of the public right of way. Curb demand is growing, including from commercial activity like passenger pickup/drop off, traditional and on-demand delivery services, new mobility programs like scooters, bikeshare, and carshare, and goods and freight delivery. While cities have made some progress in digitizing their curb and using curb data, more tools are needed to proactively manage curbs and sidewalks, and to deliver more public value from this scarce resource. Curb data standards can provide a mechanism for expressing static and dynamic regulations, measuring activity at the curb, and developing policies that create more accessible, useful curbs. The Curb Data Specification (CDS) will help cities and companies pilot and scale dynamic curb zones that optimize commercial loading activities of people and goods, and measure the impact of these programs. -In the short term we will produce standards that are necessary to support dynamic curb utilization use cases for commercial loading activities by privately operated companies. In the long term we want to help cities manage their curb zone programs and surrounding areas and measure the utilization and impact for all use cases. - The CDS will be consumed by both cities and transportation providers operating in the public right of way. In many cases, the same mobility providers using curbs with CDS may also be interacting with other OMF [MDS Policy](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/policy), [MDS Provider](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/provider), and [MDS Agency](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/agency) data objects within the same [MDS Jurisdiction](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/jurisdiction) or [MDS Geography](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/geography), and using similar [MDS Metrics](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/metrics). Consistent with the Technology Design Principles codified in the OMF [Architectural Landscape Document](https://github.com/openmobilityfoundation/governance/blob/main/documents/OMF-MDS-Architectural-Landscape.pdf), the members of this working group are making reasonable best efforts to ensure that work is both _modular_ and _interoperable_ with other technology managed by the OMF as to avoid duplication and downstream implementation complexity. [Top][toc] From 1b2bafb17a58839c6bb5a4a8b23eaac4c15d185c Mon Sep 17 00:00:00 2001 From: Jascha Franklin-Hodge Date: Thu, 4 Nov 2021 13:29:56 -0400 Subject: [PATCH 004/173] Minor language tweaks. --- curbs/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 0ec25ba5..5f766e62 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -1,9 +1,9 @@ # Curb Data Specification: Curbs API The Curbs API is a REST API allowing cities to specify areas of interest along the curb along with -the rules for using them: who is allowed to park, load, unload, pick up, drop off, etc. at the curb, -for how long, for what price (if any), at what times, and on what days. Locations defined in the -Curbs API can be connected to event and metric data and shared with companies and the public, for +the rules for using them: who is allowed to park, load, unload, pick up, drop off, etc., +for how long, for what price (if any), at what times, and on which days. Locations defined in the +Curbs API can be connected to event and metrics data, and can be shared with companies and the public, for purposes such as routing, finding legal parking, loading, and pick-up/drop-off spots, or analyzing curb utilization over time. From 1d8a6a017a0c5f1e1dea46e5ad03facf4d82cdf4 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 12 Nov 2021 12:53:34 -0500 Subject: [PATCH 005/173] Metric endpoints optionally dynamic --- metrics/README.md | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index 39bc0376..07c26933 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -9,8 +9,8 @@ The Metrics API is a REST API allowing historic metrics calculations based on Ev There are two different endpoints that are part of the Metrics API: - - A [Activities](#curb-event) is infomration about an activity that occurs near, at, or within a pre-defined curb area. Activities is a subset of items from the Events API. Activities is *optional*. - - A [Aggregates](#status) is aggregated counts and methodology of curb events. Aggregates is *optional*. + - A [Activities](#curb-event) is information about an activity that occurs near, at, or within a pre-defined curb area. Activities is a subset of items from the Events API. Activities is *optional* within Metrics. + - A [Aggregates](#status) is aggregated counts and methodology of curb events. Aggregates is *optional* within Metrics. # Table of Contents @@ -52,7 +52,17 @@ _Optional endpoint; if not implemented, a server should reply with 501 Not Imple ### Query Parameters -No query parameters for this endpoint. +An agency may choose to make this endpoint static (and return all the available data at once in a single file) or dynamic (and allow the use of query parameters to filter the data). If dynamic, all query parameters are optional. + +| Name | Type | Description | +| ------------ | --------- | ---------------------------------------------- | +| `curb_area` | [UUID][uuid] | The ID of a [Curb Area](/curbs/#curb-area). If specified, only return data contained within this area. | +| `curb_zone` | [UUID][uuid] | The ID of a [Curb Zone](/curbs/#curb-zone). If specified, only return data contained within this area. | +| `curb_space` | [UUID][uuid] | The ID of a [Curb Space](/curbs/#curb-space). If specified, only return data contained within this area. | +| `min_lat`
`min_lng`
`max_lat`
`max_lng` | Numeric | Specifies a latitude and longitude bounding box. If one of these parameters is specified, all four MUST be. If specified only return Curb Zones that intersect the supplied bounding box. | +| `lat`
`lng`
`radius` | Numeric | Specifies a latitude and longitude bounding point and a radius away from that point. If one of these parameters is specified, all three MUST be. Returns only Curb Zones that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Zones in the response MUST be ordered ascending by distance from the center point. | +| `start_time` | [Timestamp][ts] | The start of the time period to return data | +| `end_time` | [Timestamp][ts] | The end of the time period to return data | [Top][toc] @@ -67,7 +77,17 @@ _Optional endpoint; if not implemented, a server should reply with 501 Not Imple ### Query Parameters -No query parameters for this endpoint. +An agency may choose to make this endpoint static (and return all the available data at once in a single file) or dynamic (and allow the use of query parameters to filter the data). If dynamic, all query parameters are optional. + +| Name | Type | Description | +| ------------ | --------- | ---------------------------------------------- | +| `curb_area` | [UUID][uuid] | The ID of a [Curb Area](/curbs/#curb-area). If specified, only return data contained within this area. | +| `curb_zone` | [UUID][uuid] | The ID of a [Curb Zone](/curbs/#curb-zone). If specified, only return data contained within this area. | +| `curb_space` | [UUID][uuid] | The ID of a [Curb Space](/curbs/#curb-space). If specified, only return data contained within this area. | +| `min_lat`
`min_lng`
`max_lat`
`max_lng` | Numeric | Specifies a latitude and longitude bounding box. If one of these parameters is specified, all four MUST be. If specified only return Curb Zones that intersect the supplied bounding box. | +| `lat`
`lng`
`radius` | Numeric | Specifies a latitude and longitude bounding point and a radius away from that point. If one of these parameters is specified, all three MUST be. Returns only Curb Zones that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Zones in the response MUST be ordered ascending by distance from the center point. | +| `start_time` | [Timestamp][ts] | The start of the time period to return data | +| `end_time` | [Timestamp][ts] | The end of the time period to return data | [Top][toc] @@ -85,7 +105,7 @@ An Activity is represented as a CSV object, whose fields are as follows, pulled | `event_id` | [UUID][uuid] | Required | The globally unique identifier of the event that occurred. | | `event_type` | [Event Type](#event-type) | Required | The event_type that happened for this event. | | `event_location` | GeoJSON | Required | The geographic point location where the event occurred. | -| `event_time` | [Timestamp][ts] | Required | Time at which the event occurred. | +| `event_time` | [Timestamp][ts] | Required | Timestamp (date/time) at which the event occurred. | | `curb_zone_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Zone where the event occurred. Required for events that occurred at a known Curb Zone for ALL _event_types_. | | `curb_area_ids` | [UUID][uuid] | Conditionally Required | Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area for these event_types: _enter_area, exit_area, park_start, park_end_ | | `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space for these event_types: _park_start, park_end, enter_area, exit_area_ | From 6178e5419647cac9bdbe776840872360f4b3e6d0 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 12 Nov 2021 13:35:31 -0500 Subject: [PATCH 006/173] Clarifications on metrics parameters --- metrics/README.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index 07c26933..71c42d5f 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -54,15 +54,15 @@ _Optional endpoint; if not implemented, a server should reply with 501 Not Imple An agency may choose to make this endpoint static (and return all the available data at once in a single file) or dynamic (and allow the use of query parameters to filter the data). If dynamic, all query parameters are optional. -| Name | Type | Description | -| ------------ | --------- | ---------------------------------------------- | -| `curb_area` | [UUID][uuid] | The ID of a [Curb Area](/curbs/#curb-area). If specified, only return data contained within this area. | -| `curb_zone` | [UUID][uuid] | The ID of a [Curb Zone](/curbs/#curb-zone). If specified, only return data contained within this area. | -| `curb_space` | [UUID][uuid] | The ID of a [Curb Space](/curbs/#curb-space). If specified, only return data contained within this area. | -| `min_lat`
`min_lng`
`max_lat`
`max_lng` | Numeric | Specifies a latitude and longitude bounding box. If one of these parameters is specified, all four MUST be. If specified only return Curb Zones that intersect the supplied bounding box. | -| `lat`
`lng`
`radius` | Numeric | Specifies a latitude and longitude bounding point and a radius away from that point. If one of these parameters is specified, all three MUST be. Returns only Curb Zones that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Zones in the response MUST be ordered ascending by distance from the center point. | -| `start_time` | [Timestamp][ts] | The start of the time period to return data | -| `end_time` | [Timestamp][ts] | The end of the time period to return data | +| Name | Type | Required/Optional | Description | +| ------------ | --------- | ----------------- | ---------------------------------------------- | +| `curb_place_type` | Enum | Optional | The type of curb place this aggregate applies to from the Curbs API: `area`, `zone`, `space`. Required with `curb_place_id`. | +| `curb_place_id` | [UUID][uuid] | Optional | The ID of this single curb place. If specified, only return data contained within this area. Required with `curb_place_type`. | +| `metric_type` | Enum | Optional | The single metric to return from the [Methodology](#methodology): `total_events`, `turnover`, `average_dwell_time`, `occupancy_percent`. | +| `min_lat`
`min_lng`
`max_lat`
`max_lng` | Numeric | Optional | Specifies a latitude and longitude bounding box. If one of these parameters is specified, all four MUST be. If specified only return Curb Zones that intersect the supplied bounding box. | +| `lat`
`lng`
`radius` | Numeric | Optional | Specifies a latitude and longitude bounding point and a radius away from that point. If one of these parameters is specified, all three MUST be. Returns only Curb Zones that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Zones in the response MUST be ordered ascending by distance from the center point. | +| `start_time` | [Timestamp][ts] | Optional | The start of the time period to return data | +| `end_time` | [Timestamp][ts] | Optional | The end of the time period to return data | [Top][toc] @@ -77,17 +77,17 @@ _Optional endpoint; if not implemented, a server should reply with 501 Not Imple ### Query Parameters -An agency may choose to make this endpoint static (and return all the available data at once in a single file) or dynamic (and allow the use of query parameters to filter the data). If dynamic, all query parameters are optional. - -| Name | Type | Description | -| ------------ | --------- | ---------------------------------------------- | -| `curb_area` | [UUID][uuid] | The ID of a [Curb Area](/curbs/#curb-area). If specified, only return data contained within this area. | -| `curb_zone` | [UUID][uuid] | The ID of a [Curb Zone](/curbs/#curb-zone). If specified, only return data contained within this area. | -| `curb_space` | [UUID][uuid] | The ID of a [Curb Space](/curbs/#curb-space). If specified, only return data contained within this area. | -| `min_lat`
`min_lng`
`max_lat`
`max_lng` | Numeric | Specifies a latitude and longitude bounding box. If one of these parameters is specified, all four MUST be. If specified only return Curb Zones that intersect the supplied bounding box. | -| `lat`
`lng`
`radius` | Numeric | Specifies a latitude and longitude bounding point and a radius away from that point. If one of these parameters is specified, all three MUST be. Returns only Curb Zones that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Zones in the response MUST be ordered ascending by distance from the center point. | -| `start_time` | [Timestamp][ts] | The start of the time period to return data | -| `end_time` | [Timestamp][ts] | The end of the time period to return data | +An agency may choose to make this endpoint static (and return all the available data at once in a single file) or dynamic (and allow the use of any or all of the query parameters below to filter the data). If dynamic, all query parameters are optional. + +| Name | Type | Required/Optional | Description | +| ------------ | --------- | ----------------- | ---------------------------------------------- | +| `curb_place_type` | Enum | Optional | The type of curb place this aggregate applies to from the Curbs API: `area`, `zone`, `space`. Required with `curb_place_id`. | +| `curb_place_id` | [UUID][uuid] | Optional | The ID of this single curb place. If specified, only return data contained within this area. Required with `curb_place_type`. | +| `metric_type` | Enum | Optional | The single metric to return from the [Methodology](#methodology): `total_events`, `turnover`, `average_dwell_time`, `occupancy_percent`. | +| `min_lat`
`min_lng`
`max_lat`
`max_lng` | Numeric | Optional | Specifies a latitude and longitude bounding box. If one of these parameters is specified, all four MUST be. If specified only return Curb Zones that intersect the supplied bounding box. | +| `lat`
`lng`
`radius` | Numeric | Optional | Specifies a latitude and longitude bounding point and a radius away from that point. If one of these parameters is specified, all three MUST be. Returns only Curb Zones that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Zones in the response MUST be ordered ascending by distance from the center point. | +| `start_time` | [Timestamp][ts] | Optional | The start of the time period to return data | +| `end_time` | [Timestamp][ts] | Optional | The end of the time period to return data | [Top][toc] From a9eb302cef72d76ab90db0b405425736ef58a9b6 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 12 Nov 2021 14:45:03 -0500 Subject: [PATCH 007/173] Added Metrics Representative Sample Data section --- metrics/README.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index 71c42d5f..411b0d2b 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -14,6 +14,7 @@ There are two different endpoints that are part of the Metrics API: # Table of Contents +- [Representative Sample Data](#representative-sample-data) - [REST Endpoints](#rest-endpoints) * [Update Frequency](#update-frequency) * [Query Activities](#query-activities) @@ -24,6 +25,10 @@ There are two different endpoints that are part of the Metrics API: * [Methodology](#methodology) * [Examples](#examples) +# Representative Sample Data + +All data returned by the Metrics API should be viewed as using representative sample data, and not neccessarily a 100% accurate picture of what happens at every defined curb space. This is because CDS Events can come from multiple sources (company data feeds, sensors, video analysis, payments, check-ins, enforcement, and/or other city data sources), cities may implement only one or more of these sources, each source returns different types and accuracy of data, and sources may not be easily cross-comparible. It is up to the city consuming Events and producing Metrics to determine accuracy and methodology details within their circumstances, and we welcome feedback, refinement, clarification, and more defined methodology per source type for future CDS releases. + # REST Endpoints All endpoints return a CSV file that can either be pre-computed or created on demand. @@ -33,11 +38,11 @@ versioning in the future. Clients SHOULD specify an `Accept` header containing `application/vnd.cds+csv;version=0.0`. If the server receives a request that contains an `Accept` header but does not include this value; it MUST respond with a status of `406 Not Acceptable`. -You may choose to serve a CSV file directly from a web-based file system, service, or data portal, in which case adding a header is not required. +You may choose to serve a static CSV file directly from a web-based file system, service, or data portal, in which case adding a header is not required. ## Update Frequency -The agency serving the data may choose how frequently they want to update the data. At least monthly is recommended but it may be longer or weekly, daily, hourly, or even more frequently. +The agency serving the data may choose how frequently they want to update the data. At least monthly is recommended but it may be longer, or weekly, daily, hourly, or even more frequently. [Top][toc] @@ -52,7 +57,7 @@ _Optional endpoint; if not implemented, a server should reply with 501 Not Imple ### Query Parameters -An agency may choose to make this endpoint static (and return all the available data at once in a single file) or dynamic (and allow the use of query parameters to filter the data). If dynamic, all query parameters are optional. +An agency may choose to make this endpoint static (and return all the available data at once in a single file) or dynamic (and allow the use of any or all of the query parameters below to filter the data). If dynamic, all query parameters are optional. | Name | Type | Required/Optional | Description | | ------------ | --------- | ----------------- | ---------------------------------------------- | @@ -77,7 +82,7 @@ _Optional endpoint; if not implemented, a server should reply with 501 Not Imple ### Query Parameters -An agency may choose to make this endpoint static (and return all the available data at once in a single file) or dynamic (and allow the use of any or all of the query parameters below to filter the data). If dynamic, all query parameters are optional. +An agency may choose to make this endpoint static (and return all the available data at once in a single file) or dynamic (and allow the use of any or all of the query parameters below to filter the data). If dynamic, all query parameters are optional. | Name | Type | Required/Optional | Description | | ------------ | --------- | ----------------- | ---------------------------------------------- | From 09166228f7d36f6eb86a39d5f0374e7cd8faeae7 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 15 Nov 2021 11:23:36 -0500 Subject: [PATCH 008/173] Added currency and cost to event --- events/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/events/README.md b/events/README.md index 4206a8da..318c8b93 100644 --- a/events/README.md +++ b/events/README.md @@ -118,6 +118,9 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `propulsion_types` | Array of [Propulsion Type](#propulsion-type) | Conditionally Required | List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type. | | `blocked_lane_types` | Array of [Lane Type](#lane-type) | Conditionally Required | Type(s) of lane blocked by the vehicle performing the event. If no lanes are blocked by the vehicle performing the event, the array should be empty. Required for the following event_types: _park_start_ | | `curb_occupants` | Array of [Curb Occupant](#curb-occupants) | Conditionally Required | Current occupants of the Curb Zone. If the sensor is capable of identifying the linear location of the vehicle, then elements are sorted in ascending order according to the start property of the linear reference. Otherwise, elements appear in no particular order. Required for the following event_types: _park_start, park_end, scheduled_report_ | +| `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | +| `currency` | String | Optional | Fields specifying a monetary cost use a currency as specified in ISO 4217. All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of 100 (for 100 cents). If the currency field is null, USD cents is implied. | +| `actual_cost` | Integer | Optional | If available from the source, the actual cost, in the currency defined in currency, paid by the curb user for this event. | [Top][toc] From 4e2b8a06db2af4c249cd1346b0c9d7cf118f0b99 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 15 Nov 2021 11:51:45 -0500 Subject: [PATCH 009/173] Remove notes --- metrics/README.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index 411b0d2b..badf856f 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -120,7 +120,7 @@ An Activity is represented as a CSV object, whose fields are as follows, pulled ### Event Types -The following Event Types are included in the Activities data, and the others event types are not returned. +The following Event Types are included in the Activities data, and the other event types are not returned. - **park_start**: a vehicle stopped, parked, or double parked - **park_end**: a parked vehicle leaving a parked or stopped state and resuming movement @@ -146,11 +146,7 @@ An Aggregate is represented as a CSV object, whose fields are as follows, as cal ### Methodology -Cities are facilitating access to the curb for different users based on the curb access priorities of that particular area. The following metrics can be useful in understanding how curb usage aligns with priorities. - -An event/transaction at the curb is defined as... TBD - -Unit of measure, time, length, etc... TBD +Cities are facilitating access to the curb for different users based on the curb access priorities of that particular area. The following metrics will be used in understanding how curb usage aligns with priorities. #### Total Events From 134889e4e651ba75a19f97d8fa0044fa315e21af Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 15 Nov 2021 20:19:49 -0500 Subject: [PATCH 010/173] Grammar fix --- metrics/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index badf856f..6b481953 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -9,8 +9,8 @@ The Metrics API is a REST API allowing historic metrics calculations based on Ev There are two different endpoints that are part of the Metrics API: - - A [Activities](#curb-event) is information about an activity that occurs near, at, or within a pre-defined curb area. Activities is a subset of items from the Events API. Activities is *optional* within Metrics. - - A [Aggregates](#status) is aggregated counts and methodology of curb events. Aggregates is *optional* within Metrics. + - [Activities](#curb-event) is information about an activity that occurs near, at, or within a pre-defined curb area. Activities is a subset of items from the Events API. Activities is *optional* within Metrics. + - [Aggregates](#status) is aggregated counts and methodology of curb events. Aggregates is *optional* within Metrics. # Table of Contents From 96fba4e3f6179246b5405807a4bf1990c1374643 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 15 Nov 2021 20:30:07 -0500 Subject: [PATCH 011/173] Added activity_type --- events/README.md | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/events/README.md b/events/README.md index 318c8b93..38bf4021 100644 --- a/events/README.md +++ b/events/README.md @@ -22,6 +22,7 @@ There are two different endpoints that are part of the Events API: * [Event Type](#event-type) * [Vehicle Type](#vehicle-type) * [Propulsion Type](#propulsion-type) + * [Activity Type](#activity-type) * [Lane Type](#lane-type) * [Curb Occupant](#curb-occupant) * [Status](#status) @@ -116,9 +117,9 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | | `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | | `propulsion_types` | Array of [Propulsion Type](#propulsion-type) | Conditionally Required | List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type. | +| `activity_type` | [Activity Type](#activity-type) | Conditionally Required | Type of activity that the vehicle performed. Required for sources capable of determining activity type for relevant event_types. | | `blocked_lane_types` | Array of [Lane Type](#lane-type) | Conditionally Required | Type(s) of lane blocked by the vehicle performing the event. If no lanes are blocked by the vehicle performing the event, the array should be empty. Required for the following event_types: _park_start_ | | `curb_occupants` | Array of [Curb Occupant](#curb-occupants) | Conditionally Required | Current occupants of the Curb Zone. If the sensor is capable of identifying the linear location of the vehicle, then elements are sorted in ascending order according to the start property of the linear reference. Otherwise, elements appear in no particular order. Required for the following event_types: _park_start, park_end, scheduled_report_ | -| `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | | `currency` | String | Optional | Fields specifying a monetary cost use a currency as specified in ISO 4217. All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of 100 (for 100 cents). If the currency field is null, USD cents is implied. | | `actual_cost` | Integer | Optional | If available from the source, the actual cost, in the currency defined in currency, paid by the curb user for this event. | @@ -128,14 +129,16 @@ A Curb Event is represented as a JSON object, whose fields are as follows: `event_type`. Curb Event Type enumerates the set of possible types of Curb Event. The values that it can assume are listed below: -- **comms_lost**: communications with the event source were lost -- **comms_restored**: communications with the event source were restored -- **decommissioned**: event source was decommissioned -- **park_start**: a vehicle stopped, parked, or double parked -- **park_end**: a parked vehicle leaving a parked or stopped state and resuming movement -- **scheduled_report**: event source reported status status at a scheduled interval -- **enter_area**: vehicle enters the relevant geographic area -- **exit_area**: vehicle exits the relevant geographic area +| `event_type` | Description | +|----------------| ----------- | +| `comms_lost` | communications with the event source were lost | +| `comms_restored` | communications with the event source were restored | +| `decommissioned` | event source was decommissioned | +| `park_start` | a vehicle stopped, parked, or double parked | +| `park_end` | a parked vehicle leaving a parked or stopped state and resuming movement | +| `scheduled_report` | event source reported status status at a scheduled interval | +| `enter_area` | vehicle enters the relevant geographic area | +| `exit_area` | vehicle exits the relevant geographic area | [Top][toc] @@ -172,6 +175,21 @@ A vehicle may have one or more values from the `propulsion`, depending on the nu [Top][toc] +### Activity Type + +Type of activity that the vehicle performed. + +| `activity_type` | Description | +| ----------------- | ------------------------------------------------------ | +| `passenger_transport` | Picking up and/or dropping off of human passengers | +| `food_delivery` | Delivery of food items ready for consumption to an end consumer | +| `parcel_delivery` | Delivery of parcels, including bulk food goods to a restaurant or other business | +| `construction` | Construction of hard assets including buildings and roadside infrastructure | +| `waste_management` | Retrieval/disposal of waste | +| `unspecified` | Unknown or unspecified activity type | + +[Top][toc] + ### Lane Type `lane_type`. Type(s) of lane blocked by the vehicle performing the event. From 9745cb88cbb9a989a0367ec7ff75c451febce145 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 15 Nov 2021 20:33:38 -0500 Subject: [PATCH 012/173] Added lane types --- events/README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/events/README.md b/events/README.md index 38bf4021..d53a1cf2 100644 --- a/events/README.md +++ b/events/README.md @@ -192,9 +192,15 @@ Type of activity that the vehicle performed. ### Lane Type -`lane_type`. Type(s) of lane blocked by the vehicle performing the event. - -- **type1**: TBD +`lane_type`. Type(s) of lane used or blocked by the vehicle performing the event. + +| `lane_type` | Description | +| -------------- | ------------------------------------------------------ | +| `traffic_lane` | A standard vehicle traffic lane | +| `turn_lane` | A dedicated turn lane | +| `bike_lane` | A lane dedicated for usage by cyclists | +| `bus_lane` | A lane dedicated for usage by busses | +| `unspecified` | Unspecified | [Top][toc] From bd7886a0610920f8d3d499bb17bc4d3b6a0f26f5 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 15 Nov 2021 20:40:18 -0500 Subject: [PATCH 013/173] Table formatting --- events/README.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/events/README.md b/events/README.md index d53a1cf2..ffa26638 100644 --- a/events/README.md +++ b/events/README.md @@ -146,17 +146,18 @@ A Curb Event is represented as a JSON object, whose fields are as follows: Type of vehicle, similar to vehicle_type in MDS. For this CDS release the list will be developed independently here to accommodate CDS and MDS use cases, while still aligning to the MDS design principles. In the next major MDS 2.0 release and next CDS release, alignment between CDS and MDS vehicle types can occur. -| `vehicle_type` | Description | -|----------------| ----------- | -| bicycle | A two-wheeled mobility device intended for personal transportation that can be operated via pedals, with or without a motorized assist (includes e-bikes, recumbents, and tandems) | -| cargo_bicycle | A two- or three-wheeled bicycle intended for transporting larger, heavier cargo than a standard bicycle (such as goods or passengers), with or without motorized assist (includes bakfiets/front-loaders, cargo trikes, and long-tails) | -| car | A passenger car or similar light-duty vehicle | -| scooter | A standing or seated fully-motorized mobility device intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles | -| moped | A seated fully-motorized mobility device capable of travel at moderate or high speeds and suited for operation in general urban traffic | -| truck | A light or heavy duty 4 wheeled truck | -| van | A van with significant interior cargo space | -| freight | A large delivery truck with attached cab | -| other | A device that does not fit in the other categories | +| `vehicle_type` | Description | +|------------------| ----------- | +| `bicycle` | A two-wheeled mobility device intended for personal transportation that can be operated via pedals, with or without a motorized assist (includes e-bikes, recumbents, and tandems) | +| `cargo_bicycle` | A two- or three-wheeled bicycle intended for transporting larger, heavier cargo than a standard bicycle (such as goods or passengers), with or without motorized assist (includes bakfiets/front-loaders, cargo trikes, and long-tails) | +| `car` | A passenger car or similar light-duty vehicle | +| `scooter` | A standing or seated fully-motorized mobility device intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles | +| `moped` | A seated fully-motorized mobility device capable of travel at moderate or high speeds and suited for operation in general urban traffic | +| `truck` | A light or heavy duty 4 wheeled truck | +| `van` | A van with significant interior cargo space | +| `freight` | A large delivery truck with attached cab | +| `other` | A device that does not fit in the other categories | +| `unspecified` | Unspecified | [Top][toc] @@ -208,9 +209,11 @@ Type of activity that the vehicle performed. `curb_occupants`. A Curb Occupant object represents a specific vehicle’s occupancy in a curb region at a specific point in time. Curb Occupant objects contain the following fields: -- **type**: _Vehicle Type, required_. The type of the occupant. When the event source is not capable of distinguishing vehicle type, this property must take the value “unspecified.” -- **length**: _Float, conditionally required._ The approximate length in centimeters of the vehicle. Required when the event source is capable of determining vehicle length. -- **linear_location**: _Array of Float, conditionally required._ A two-element array that specifies the start and end of the occupant’s linear location relative to the start of the Curb Zone in that order. Required when the event source is capable of determining the linear location of occupants. +| Name | Type | Required/Optional | Description | +| ------ | ------ | ------------------- | ------------- | +| `type` | [Vehicle Type](#vehicle-type) | Required | The vehicle type of the occupant. When the event source is not capable of distinguishing vehicle type, this property must take the value "unspecified". +| `length` | Float | Conditionally required | The approximate length in centimeters of the vehicle. Required when the event source is capable of determining vehicle length. +| `linear_location` | Array of Float | Conditionally required | A two-element array that specifies the start and end of the occupant’s linear location relative to the start of the Curb Zone in that order. Required when the event source is capable of determining the linear location of occupants. [Top][toc] From f00f6315761bcf1201e73160c20ea7e33bbfdd16 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 16 Nov 2021 11:51:33 -0500 Subject: [PATCH 014/173] Singularized Metrics endpoints --- metrics/README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index 6b481953..ed34af95 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -17,11 +17,11 @@ There are two different endpoints that are part of the Metrics API: - [Representative Sample Data](#representative-sample-data) - [REST Endpoints](#rest-endpoints) * [Update Frequency](#update-frequency) - * [Query Activities](#query-activities) - * [Query Aggregates](#query-aggregates) + * [Query Activity](#query-activity) + * [Query Aggregate](#query-aggregate) - [Data Objects](#data-objects) - * [Activities](#activities) - * [Aggregates](#aggregates) + * [Activity](#activity) + * [Aggregate](#aggregate) * [Methodology](#methodology) * [Examples](#examples) @@ -46,12 +46,12 @@ The agency serving the data may choose how frequently they want to update the da [Top][toc] -## Query Activities +## Query Activity -Endpoint: `/metrics/activities` +Endpoint: `/metrics/activity` Method: `GET` `data` Payload: a CSV object with the following fields: - - `activities`: an array of [Activities](#activity) objects + - `activity`: an array of [Activity](#activity) objects _Optional endpoint; if not implemented, a server should reply with 501 Not Implemented._ @@ -71,12 +71,12 @@ An agency may choose to make this endpoint static (and return all the available [Top][toc] -## Query Aggregates +## Query Aggregate -Endpoint: `/metrics/aggregates` +Endpoint: `/metrics/aggregate` Method: `GET` `data` Payload: a CSV object with the following fields: - - `activities`: an array of [Aggregates](#aggregates) objects + - `aggregate`: an array of [Aggregate](#aggregate) objects _Optional endpoint; if not implemented, a server should reply with 501 Not Implemented._ @@ -98,7 +98,7 @@ An agency may choose to make this endpoint static (and return all the available # Data Objects -## Activities +## Activity Activities are a historic subset of curb events, with some rows combined, some columns removed for clarity and privacy, and for some curb event types. Activities are meant to provide a granular view of activity happening around the curb places, so consumers can do their own analysis and aggregation. @@ -129,7 +129,7 @@ The following Event Types are included in the Activities data, and the other eve [Top][toc] -## Aggregates +## Aggregate Aggregates are historic pre-computed counts and metrics of Events occuring in curb places, aggregated to the hour. From 70779323862e4c6dfa3b9d30c2263c1419dc360f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 16 Nov 2021 17:13:55 -0500 Subject: [PATCH 015/173] Added motorcycle --- events/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/events/README.md b/events/README.md index ffa26638..9b558ddd 100644 --- a/events/README.md +++ b/events/README.md @@ -153,6 +153,7 @@ Type of vehicle, similar to vehicle_type in MDS. For this CDS release the list w | `car` | A passenger car or similar light-duty vehicle | | `scooter` | A standing or seated fully-motorized mobility device intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles | | `moped` | A seated fully-motorized mobility device capable of travel at moderate or high speeds and suited for operation in general urban traffic | +| `motorcycle` | A seated mobility device capable of travel at high speeds and suited for operation in general urban traffic or expressways | | `truck` | A light or heavy duty 4 wheeled truck | | `van` | A van with significant interior cargo space | | `freight` | A large delivery truck with attached cab | From eaddeb0f1c75d559d4b546f705c9e27546df9ca8 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 17 Nov 2021 17:06:57 -0500 Subject: [PATCH 016/173] Clarify lane type --- events/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/events/README.md b/events/README.md index 9b558ddd..32e2f96c 100644 --- a/events/README.md +++ b/events/README.md @@ -194,11 +194,11 @@ Type of activity that the vehicle performed. ### Lane Type -`lane_type`. Type(s) of lane used or blocked by the vehicle performing the event. +`lane_type`. Type(s) of lane used or blocked by the vehicle performing the event, ouside of curb zones. E.g., double parking. | `lane_type` | Description | | -------------- | ------------------------------------------------------ | -| `traffic_lane` | A standard vehicle traffic lane | +| `travel_lane` | A standard vehicle travel lane | | `turn_lane` | A dedicated turn lane | | `bike_lane` | A lane dedicated for usage by cyclists | | `bus_lane` | A lane dedicated for usage by busses | From 3b97913cff851198dfd1b3236f7a56927acfe6ef Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 19 Nov 2021 09:55:15 -0500 Subject: [PATCH 017/173] Added source type --- events/README.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/events/README.md b/events/README.md index 32e2f96c..5be45880 100644 --- a/events/README.md +++ b/events/README.md @@ -20,6 +20,7 @@ There are two different endpoints that are part of the Events API: - [Data Objects](#data-objects) * [Curb Event](#curb-event) * [Event Type](#event-type) + * [Source Type](#source-type) * [Vehicle Type](#vehicle-type) * [Propulsion Type](#propulsion-type) * [Activity Type](#activity-type) @@ -100,19 +101,19 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | ------ | ------ | ------------------- | ------------- | | `event_id` | [UUID][uuid] | Required | The globally unique identifier of the event that occurred. | | `event_type` | [Event Type](#event-type) | Required | The event_type that happened for this event. | -| `event_source_category` | Enum [Sensor Category](#sensor-category) | Required | General category of the source creating the event. | -| `source_operator_id` | [UUID][uuid] | Required | Unique identifier of the entity responsible for operating the event source. | -| `source_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded. | +| `source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | +| `source_operator_id` | [UUID][uuid] | Required | Unique identifier of the entity responsible for operating the event source. This can be generated outside of CDS beforhand for each source operator. Different than `provider_id`. | +| `source_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is an ID they use and may be the same as `vehicle_id`. | +| `provider_id` | [UUID][uuid] | Optional | Unique ID of the provider responsible for operating the vehicle at the time of the event, if any. IDs are global and come from the [providers.csv](/providers.csv) file here in the CDS repo. | +| `provider_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. | +| `sensor_id` | [UUID][uuid] | Optional | If a sensor was used, the globally unique identifier of the sensor that recorded the event. Not needed if data is coming from a provider directly. | +| `sensor_status` | Object | Optional | The status of the sensor that reported the event at the time that the event was reported. _is_commissioned_: Boolean, required. Indicates whether the sensor is currently in a state where it should be reporting data. _is_online_: Boolean, required. Indicates whether the sensor is currently online and reporting data. | | `event_location` | GeoJSON | Required | The geographic point location where the event occurred. | | `event_time` | [Timestamp][ts] | Required | Time at which the event occurred. | | `publication_time` | [Timestamp][ts] | Required | Time at which the event became available for consumption by this API. | | `curb_zone_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Zone where the event occurred. Required for events that occurred at a known Curb Zone for ALL _event_types_. | | `curb_area_ids` | [UUID][uuid] | Conditionally Required | Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area for these event_types: _enter_area, exit_area, park_start, park_end_ | | `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space for these event_types: _park_start, park_end, enter_area, exit_area_ | -| `provider_id` | [UUID][uuid] | Optional | Unique ID of the provider responsible for operating the vehicle at the time of the event, if any. IDs are global and come from the [providers.csv](/providers.csv) file here in the CDS repo. | -| `provider_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event, if any. | -| `sensor_id` | [UUID][uuid] | Optional | If a sensor was used, the globally unique identifier of the sensor that recorded the event. | -| `sensor_status` | Object | Optional | The status of the sensor that reported the event at the time that the event was reported. _is_commissioned_: Boolean, required. Indicates whether the sensor is currently in a state where it should be reporting data. _is_online_: Boolean, required. Indicates whether the sensor is currently online and reporting data. | | `vehicle_id` | String | Optional | A vehicle identifier visible on the vehicle itself. | | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | | `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | @@ -142,6 +143,22 @@ A Curb Event is represented as a JSON object, whose fields are as follows: [Top][toc] +### Source Type + +`source_type`. Curb Source Type enumerates the set of possible categories of sources that are sending this event. The values that it can assume are listed below: + +| `source_type` | Description | +|----------------| ----------- | +| `data_feed` | directly from a provider data feed send to the agency | +| `camera` | video or static image processing source | +| `above_ground` | sensor deployed above ground | +| `in_ground` | sensor deployed in the ground | +| `meter` | a smart parking meter | +| `in_person` | an individual on site recording the event digitally or otherwise | +| `other` | sources not ennumerated above | + +[Top][toc] + ### Vehicle Type Type of vehicle, similar to vehicle_type in MDS. For this CDS release the list will be developed independently here to accommodate CDS and MDS use cases, while still aligning to the MDS design principles. In the next major MDS 2.0 release and next CDS release, alignment between CDS and MDS vehicle types can occur. From a32262f42afcd881cb6faf6b831f5a8a6f422ebf Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 19 Nov 2021 09:58:04 -0500 Subject: [PATCH 018/173] Minor typo --- events/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index 5be45880..e0b6afc2 100644 --- a/events/README.md +++ b/events/README.md @@ -149,7 +149,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `source_type` | Description | |----------------| ----------- | -| `data_feed` | directly from a provider data feed send to the agency | +| `data_feed` | directly from a provider data feed sent to the agency | | `camera` | video or static image processing source | | `above_ground` | sensor deployed above ground | | `in_ground` | sensor deployed in the ground | From f9e6ada127c48962479ca47d34b7cfac1fecc631 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 19 Nov 2021 11:56:55 -0500 Subject: [PATCH 019/173] Updated lane_type with ideas from WZDx --- events/README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/events/README.md b/events/README.md index e0b6afc2..35f83ccb 100644 --- a/events/README.md +++ b/events/README.md @@ -215,10 +215,14 @@ Type of activity that the vehicle performed. | `lane_type` | Description | | -------------- | ------------------------------------------------------ | -| `travel_lane` | A standard vehicle travel lane | -| `turn_lane` | A dedicated turn lane | -| `bike_lane` | A lane dedicated for usage by cyclists | -| `bus_lane` | A lane dedicated for usage by busses | +| `travel_lane` | A standard vehicle travel lane. | +| `turn_lane` | A dedicated turn lane. | +| `bike_lane` | A lane dedicated for usage by cyclists. | +| `bus_lane` | A lane dedicated for usage by busses. | +| `parking` | A lane used for parking, not allowed for travel. | +| `shoulder` | A portion of the roadway that is outside (either right or left) of the main travel lanes. A shoulder can have many uses but is not intended for general traffic. | +| `median` | An often unpaved, non-drivable area that separates sections of the roadway. | +| `sidewalk` | A path for pedestrians, usually on the side of the roadway. | | `unspecified` | Unspecified | [Top][toc] From dd3d8a94d2bb46abada2e87b719aa709864307af Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 22 Nov 2021 15:03:18 -0500 Subject: [PATCH 020/173] Added activity_category --- events/README.md | 47 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 10 deletions(-) diff --git a/events/README.md b/events/README.md index 35f83ccb..26289164 100644 --- a/events/README.md +++ b/events/README.md @@ -23,6 +23,7 @@ There are two different endpoints that are part of the Events API: * [Source Type](#source-type) * [Vehicle Type](#vehicle-type) * [Propulsion Type](#propulsion-type) + * [Activity Category](#activity-category) * [Activity Type](#activity-type) * [Lane Type](#lane-type) * [Curb Occupant](#curb-occupant) @@ -118,7 +119,8 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | | `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | | `propulsion_types` | Array of [Propulsion Type](#propulsion-type) | Conditionally Required | List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type. | -| `activity_type` | [Activity Type](#activity-type) | Conditionally Required | Type of activity that the vehicle performed. Required for sources capable of determining activity type for relevant event_types. | +| `activity_category` | [Activity Category](#activity-category) | Conditionally Required | General activity that the vehicle performed. Required for sources capable of determining activity type for relevant event_types. | +| `activity_type` | [Activity Type](#activity-type) | Conditionally Required | Detailed type of activity that the vehicle performed. Required for sources capable of determining activity type for relevant event_types. | | `blocked_lane_types` | Array of [Lane Type](#lane-type) | Conditionally Required | Type(s) of lane blocked by the vehicle performing the event. If no lanes are blocked by the vehicle performing the event, the array should be empty. Required for the following event_types: _park_start_ | | `curb_occupants` | Array of [Curb Occupant](#curb-occupants) | Conditionally Required | Current occupants of the Curb Zone. If the sensor is capable of identifying the linear location of the vehicle, then elements are sorted in ascending order according to the start property of the linear reference. Otherwise, elements appear in no particular order. Required for the following event_types: _park_start, park_end, scheduled_report_ | | `currency` | String | Optional | Fields specifying a monetary cost use a currency as specified in ISO 4217. All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of 100 (for 100 cents). If the currency field is null, USD cents is implied. | @@ -194,18 +196,43 @@ A vehicle may have one or more values from the `propulsion`, depending on the nu [Top][toc] -### Activity Type +### Activity Category -Type of activity that the vehicle performed. +General, high-level category of activity that the vehicle performed, discernible by many sensors. -| `activity_type` | Description | -| ----------------- | ------------------------------------------------------ | +| `activity_category` | Description | +| --------------------- | ------------------------------------------------------ | +| `construction` | Construction of hard assets including buildings and roadside infrastructure | +| `delivery` | General delivery of parcels, goods, freight | +| `emergency_use` | Includes ambulance, fire truck, police | +| `parking` | Vehicle parking, charging, or stopping | | `passenger_transport` | Picking up and/or dropping off of human passengers | -| `food_delivery` | Delivery of food items ready for consumption to an end consumer | -| `parcel_delivery` | Delivery of parcels, including bulk food goods to a restaurant or other business | -| `construction` | Construction of hard assets including buildings and roadside infrastructure | -| `waste_management` | Retrieval/disposal of waste | -| `unspecified` | Unknown or unspecified activity type | +| `special_events` | Includes unloading equipment for concerts, theatre, street events | +| `waste_management` | Retrieval/disposal of waste | + +[Top][toc] + +### Activity Type + +Detailed type of activity that the vehicle performed, if discernible based on the source, likely from advanced sensors or self-reported in company data feeds. Usually a subset of one of an [Activity Category](#activity_category). + +| `activity_type` | Description | +| --------------------- | ------------------------------------------------------ | +| `device_maintenance` | Includes scooter pickup, drop off, battery swapping | +| `ems` | Emergency medical vehicle use | +| `fire` | Emergency fire vehicle | +| `food_delivery` | Delivery of food items ready for consumption to an end consumer | +| `parcel_delivery` | Delivery of parcels, including bulk food goods to a restaurant or other business | +| `police` | Use by a police vehicle | +| `public_transit` | Includes large or small buses or paratransit. | +| `ride_hail` | Includes privately run ride hailing services | +| `road_maintenance` | Includes pothole patching, striping, snow plowing, street sweeping | +| `service_vehicles` | Includes private sector activity like some utilities | +| `taxi` | Traditionaly licensed taxi services | +| `utility_work` | Includes public sector activity like sewer, water, telecoms | +| `vehicle_charging` | Parking for electric vehicles to charge | +| `vehicle_parking` | Includes private or commercial vehicle free or paid/metered parking | +| `unspecified` | Unknown or unspecified activity type | [Top][toc] From 63319e34f60772a3f0daf0ada7734b6052f0ea55 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 22 Nov 2021 15:22:03 -0500 Subject: [PATCH 021/173] Added optional session_id --- events/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/events/README.md b/events/README.md index 26289164..f4e0d3ee 100644 --- a/events/README.md +++ b/events/README.md @@ -109,6 +109,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `provider_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. | | `sensor_id` | [UUID][uuid] | Optional | If a sensor was used, the globally unique identifier of the sensor that recorded the event. Not needed if data is coming from a provider directly. | | `sensor_status` | Object | Optional | The status of the sensor that reported the event at the time that the event was reported. _is_commissioned_: Boolean, required. Indicates whether the sensor is currently in a state where it should be reporting data. _is_online_: Boolean, required. Indicates whether the sensor is currently online and reporting data. | +| `session_id` | [UUID][uuid] | Optional | If a source can determine if certain events can be connected, then they may provide a `session_id` to help connect via 'event_type' later. E.g., a park_start event and park_end event may be connected by the same `session_id`. | | `event_location` | GeoJSON | Required | The geographic point location where the event occurred. | | `event_time` | [Timestamp][ts] | Required | Time at which the event occurred. | | `publication_time` | [Timestamp][ts] | Required | Time at which the event became available for consumption by this API. | From e39fdc6b42cce859c54dea96dde8217a7a3bf20f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 08:08:44 -0500 Subject: [PATCH 022/173] Renamed total_events to total_sessions --- metrics/README.md | 66 +++++++++++++++++++++++------------------------ 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index ed34af95..61b9f0bf 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -63,7 +63,7 @@ An agency may choose to make this endpoint static (and return all the available | ------------ | --------- | ----------------- | ---------------------------------------------- | | `curb_place_type` | Enum | Optional | The type of curb place this aggregate applies to from the Curbs API: `area`, `zone`, `space`. Required with `curb_place_id`. | | `curb_place_id` | [UUID][uuid] | Optional | The ID of this single curb place. If specified, only return data contained within this area. Required with `curb_place_type`. | -| `metric_type` | Enum | Optional | The single metric to return from the [Methodology](#methodology): `total_events`, `turnover`, `average_dwell_time`, `occupancy_percent`. | +| `metric_type` | Enum | Optional | The single metric to return from the [Methodology](#methodology): `total_sessions`, `turnover`, `average_dwell_time`, `occupancy_percent`. | | `min_lat`
`min_lng`
`max_lat`
`max_lng` | Numeric | Optional | Specifies a latitude and longitude bounding box. If one of these parameters is specified, all four MUST be. If specified only return Curb Zones that intersect the supplied bounding box. | | `lat`
`lng`
`radius` | Numeric | Optional | Specifies a latitude and longitude bounding point and a radius away from that point. If one of these parameters is specified, all three MUST be. Returns only Curb Zones that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Zones in the response MUST be ordered ascending by distance from the center point. | | `start_time` | [Timestamp][ts] | Optional | The start of the time period to return data | @@ -88,7 +88,7 @@ An agency may choose to make this endpoint static (and return all the available | ------------ | --------- | ----------------- | ---------------------------------------------- | | `curb_place_type` | Enum | Optional | The type of curb place this aggregate applies to from the Curbs API: `area`, `zone`, `space`. Required with `curb_place_id`. | | `curb_place_id` | [UUID][uuid] | Optional | The ID of this single curb place. If specified, only return data contained within this area. Required with `curb_place_type`. | -| `metric_type` | Enum | Optional | The single metric to return from the [Methodology](#methodology): `total_events`, `turnover`, `average_dwell_time`, `occupancy_percent`. | +| `metric_type` | Enum | Optional | The single metric to return from the [Methodology](#methodology): `total_sessions`, `turnover`, `average_dwell_time`, `occupancy_percent`. | | `min_lat`
`min_lng`
`max_lat`
`max_lng` | Numeric | Optional | Specifies a latitude and longitude bounding box. If one of these parameters is specified, all four MUST be. If specified only return Curb Zones that intersect the supplied bounding box. | | `lat`
`lng`
`radius` | Numeric | Optional | Specifies a latitude and longitude bounding point and a radius away from that point. If one of these parameters is specified, all three MUST be. Returns only Curb Zones that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Zones in the response MUST be ordered ascending by distance from the center point. | | `start_time` | [Timestamp][ts] | Optional | The start of the time period to return data | @@ -139,7 +139,7 @@ An Aggregate is represented as a CSV object, whose fields are as follows, as cal | ------ | ------ | ------------------- | ------------- | | `curb_place_type` | Enum | Required | The type of curb place this aggregate applies to from the Curbs API: `area`, `zone`, `space`. | | `curb_place_id` | [UUID][uuid] | Required | The ID of this curb place. | -| `metric_type` | Enum | Required | The metric this aggregate applies to from the [Methodology](#methodology): `total_events`, `turnover`, `average_dwell_time`, `occupancy_percent`. | +| `metric_type` | Enum | Required | The metric this aggregate applies to from the [Methodology](#methodology): `total_sessions`, `turnover`, `average_dwell_time`, `occupancy_percent`. | | `date` | date | Required | The date the event occured in ISO 8601 format, local timezone, in "YYYY-MM-DD" format. E.g. "2021-10-31" | | `hour` | integer | Required | The hour of the day the event occured in ISO 8601 format, local timezone, in "hh" format. E.g. "23" | | `value` | number | Required | The results of the calculations for this metric from the [Methodology](#methodology). Note that "-1" means the the sensor/source was offline for the majority of the time. E.g. "6", "2.9", "-1", or "0.05" | @@ -148,18 +148,18 @@ An Aggregate is represented as a CSV object, whose fields are as follows, as cal Cities are facilitating access to the curb for different users based on the curb access priorities of that particular area. The following metrics will be used in understanding how curb usage aligns with priorities. -#### Total Events +#### Total Sessions -`count[events]` for a specific time period -Name: `total_events` +`count[sessions]` for a specific time period +Name: `total_sessions` _Use Case_ -Cities use this to determine ‘demand’ for curb space and understand how much activity is happening at the curb. Seems pretty basic but a lot of cities don’t have this insight or if they do it’s not current or comprehensive. +Cities use this to determine ‘demand’ for curb space and understand how much activity is happening at the curb. A session is a parking event, defined by the `park_start` and `park_end` event types. #### Turnover -`count[events]/hour` for a specific time period +`count[sessions]/hour` for a specific time period Name: `turnover` _Use Case_ @@ -168,7 +168,7 @@ Used together with Average Dwell Time by cities to understand how long vehicles #### Average Dwell Time -`sum[dwell time] / count[events]` for a specific time period +`sum[dwell time] / count[sessions]` for a specific time period Name: `average_dwell_time` _Use Case_ @@ -196,30 +196,30 @@ Example of available for 2 aggregate metrics in 2 places over a 1 day period. ``` curb_place_type,curb_place_id,metric_type,date,hour,value -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,0,3 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,1,7 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,2,2 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,3,7 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,4,9 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,5,10 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,6,13 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,7,16 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,8,17 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,9,13 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,10,15 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,11,19 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,12,29 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,13,27 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,14,26 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,15,38 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,16,34 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,17,35 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,18,33 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,19,20 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,20,16 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,21,12 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,22,-1 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_events,2021-10-31,23,8 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,0,3 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,1,7 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,2,2 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,3,7 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,4,9 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,5,10 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,6,13 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,7,16 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,8,17 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,9,13 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,10,15 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,11,19 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,12,29 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,13,27 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,14,26 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,15,38 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,16,34 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,17,35 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,18,33 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,19,20 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,20,16 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,21,12 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,22,-1 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,23,8 Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,0,10.5 Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,1,5.0 Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,2,3.0 From e50bde1f2a617f0979a51f3bee10624eadc3d9ca Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 09:27:16 -0500 Subject: [PATCH 023/173] Changed Metrics 'Activity' to 'Session' --- metrics/README.md | 44 ++++++++++++++++++++++++++++---------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index 61b9f0bf..43b33a34 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -9,18 +9,18 @@ The Metrics API is a REST API allowing historic metrics calculations based on Ev There are two different endpoints that are part of the Metrics API: - - [Activities](#curb-event) is information about an activity that occurs near, at, or within a pre-defined curb area. Activities is a subset of items from the Events API. Activities is *optional* within Metrics. - - [Aggregates](#status) is aggregated counts and methodology of curb events. Aggregates is *optional* within Metrics. + - [Session](#session) is information about an activity that occurs near, at, or within a pre-defined curb area. Sessions is a subset of items from the Events API. Sessions is *optional* within Metrics. + - [Aggregate](#aggregate) is aggregated counts and methodology of curb events. Aggregates is *optional* within Metrics. # Table of Contents - [Representative Sample Data](#representative-sample-data) - [REST Endpoints](#rest-endpoints) * [Update Frequency](#update-frequency) - * [Query Activity](#query-activity) + * [Query Session](#query-session) * [Query Aggregate](#query-aggregate) - [Data Objects](#data-objects) - * [Activity](#activity) + * [Activity](#session) * [Aggregate](#aggregate) * [Methodology](#methodology) * [Examples](#examples) @@ -46,12 +46,12 @@ The agency serving the data may choose how frequently they want to update the da [Top][toc] -## Query Activity +## Query Session -Endpoint: `/metrics/activity` +Endpoint: `/metrics/session` Method: `GET` `data` Payload: a CSV object with the following fields: - - `activity`: an array of [Activity](#activity) objects + - `session`: an array of [Session](#session) objects _Optional endpoint; if not implemented, a server should reply with 501 Not Implemented._ @@ -98,19 +98,24 @@ An agency may choose to make this endpoint static (and return all the available # Data Objects -## Activity +## Session -Activities are a historic subset of curb events, with some rows combined, some columns removed for clarity and privacy, and for some curb event types. -Activities are meant to provide a granular view of activity happening around the curb places, so consumers can do their own analysis and aggregation. +Sessions are a historic subset of curb events, with some rows combined, some columns removed for clarity and privacy, and for only some curb event types. +Sessions are meant to provide a granular view of parking and area sessions happening around the curb places, so consumers can do their own analysis. -An Activity is represented as a CSV object, whose fields are as follows, pulled from the Curb Events endpoint in the Events API: +A Session is represented as a CSV object, whose fields are as follows, pulled from the Curb Events endpoint in the Events API: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `event_id` | [UUID][uuid] | Required | The globally unique identifier of the event that occurred. | -| `event_type` | [Event Type](#event-type) | Required | The event_type that happened for this event. | -| `event_location` | GeoJSON | Required | The geographic point location where the event occurred. | -| `event_time` | [Timestamp][ts] | Required | Timestamp (date/time) at which the event occurred. | +| `session_type` | Enum | Required | The type of session that happened for this event: `parking` or `area` | +| `event_id_start` | [UUID][uuid] | Conditionally Required | The globally unique identifier of the **start/enter** event that occurred. | +| `event_id_end` | [UUID][uuid] | Conditionally Required | The globally unique identifier of the **end/exit** event that occurred. | +| `event_location_start_latitude` | Number | Conditionally Required | The geographic latitude point location where the **start/enter** of the event occurred. | +| `event_location_start_longitude` | Number | Conditionally Required | The geographic longitude point location where the **start/enter** of the event occurred. | +| `event_location_end_latitude` | Number | Conditionally Required | The geographic latitude point location where the **end/exit** of the event occurred. | +| `event_location_end_longitude` | Number | Conditionally Required | The geographic longitude point location where the **end/exit** of the event occurred. | +| `event_time_start` | [Timestamp][ts] | Conditionally Required | Timestamp (date/time) at which the event started with the `park_start` or `enter_area` event types. | +| `event_time_end` | [Timestamp][ts] | Conditionally Required | Timestamp (date/time) at which the event occurred. | | `curb_zone_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Zone where the event occurred. Required for events that occurred at a known Curb Zone for ALL _event_types_. | | `curb_area_ids` | [UUID][uuid] | Conditionally Required | Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area for these event_types: _enter_area, exit_area, park_start, park_end_ | | `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space for these event_types: _park_start, park_end, enter_area, exit_area_ | @@ -120,13 +125,20 @@ An Activity is represented as a CSV object, whose fields are as follows, pulled ### Event Types -The following Event Types are included in the Activities data, and the other event types are not returned. +The following Event Types are relevant to the Session data, and the other event types are not utilized. +For `session_type` of `parking`: - **park_start**: a vehicle stopped, parked, or double parked - **park_end**: a parked vehicle leaving a parked or stopped state and resuming movement + +For `session_type` of `area`: - **enter_area**: vehicle enters the relevant geographic area - **exit_area**: vehicle exits the relevant geographic area +**Note:** It is prefereable to return both start/end or enter/exit pairs of events. However, even if only one of these is present, the available data should be returned with the corresponding missing values of `event_id_X`, `event_location_X`, `event_time_X` returned as _null_. + +A "session duration" can be calculated by looking at the difference between the `event_time_start` and `event_time_end`. + [Top][toc] ## Aggregate From 30285f297d534ea8782b7b1122bcc727cf414994 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 09:43:29 -0500 Subject: [PATCH 024/173] Removed propulsion type for simplicity --- metrics/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/metrics/README.md b/metrics/README.md index 43b33a34..28ab58f1 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -121,7 +121,6 @@ A Session is represented as a CSV object, whose fields are as follows, pulled fr | `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space for these event_types: _park_start, park_end, enter_area, exit_area_ | | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | | `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | -| `propulsion_types` | Array of [Propulsion Type](#propulsion-type) | Conditionally Required | List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type. | ### Event Types From 6c92dfaf69591e2af7eb9b0a379c28a0b830e354 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 09:56:00 -0500 Subject: [PATCH 025/173] TOC update --- metrics/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/metrics/README.md b/metrics/README.md index 28ab58f1..d8b879f7 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -20,7 +20,7 @@ There are two different endpoints that are part of the Metrics API: * [Query Session](#query-session) * [Query Aggregate](#query-aggregate) - [Data Objects](#data-objects) - * [Activity](#session) + * [Session](#session) * [Aggregate](#aggregate) * [Methodology](#methodology) * [Examples](#examples) From 5df2474b67f282c15318f2573cdf817df8dc3cc5 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 10:02:12 -0500 Subject: [PATCH 026/173] Added dwell time reference --- metrics/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index d8b879f7..dee4c4c0 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -136,13 +136,13 @@ For `session_type` of `area`: **Note:** It is prefereable to return both start/end or enter/exit pairs of events. However, even if only one of these is present, the available data should be returned with the corresponding missing values of `event_id_X`, `event_location_X`, `event_time_X` returned as _null_. -A "session duration" can be calculated by looking at the difference between the `event_time_start` and `event_time_end`. +A "session duration" or "dwell time" can be calculated by calculating the difference between the `event_time_start` and `event_time_end`. [Top][toc] ## Aggregate -Aggregates are historic pre-computed counts and metrics of Events occuring in curb places, aggregated to the hour. +Aggregates are historic pre-computed counts and metrics of Events occuring in curb places, aggregated to the hour. All Aggregates can be calculated from the data included in [Session](#session). An Aggregate is represented as a CSV object, whose fields are as follows, as calculated from the Metrics [Methodology](#methodology): @@ -157,7 +157,7 @@ An Aggregate is represented as a CSV object, whose fields are as follows, as cal ### Methodology -Cities are facilitating access to the curb for different users based on the curb access priorities of that particular area. The following metrics will be used in understanding how curb usage aligns with priorities. +Cities are facilitating access to the curb for different users based on the curb access priorities of that particular area. The following metrics will be used in understanding how curb usage aligns with priorities. The metrics may be calculated using the [Session](#session) data and returned here, #### Total Sessions From 4a28e03a3e1d6f2861ca03847c9ea4d6bb719649 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 10:47:43 -0500 Subject: [PATCH 027/173] Updated well-known values for user classes --- curbs/README.md | 48 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 8 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 5f766e62..8fb6d715 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -361,22 +361,54 @@ for instance, implies that the Curb Zone does allow loading at the time in quest A user class represents any class of vehicles that is regulated by a city with respect to curb space. They can be defined by the vehicle's physical characteristics (e.g., trucks, vans, EVs), -the presence/absence of a particular permit (e.g., residential parking permits) or even by the +the presence/absence of a particular permit (e.g., residential parking permits), or even by the intent or destination of the driver, for things like hotel or school unloading zones. -New user classes MAY be generated by data providers to reflect their regulations, but when possible, -the following known values should be used: +These are not meant to be a mirror to similarly named items in the Events API, but instead serve a +unique purpose of describing locally defined regulations at a curb. +This array of user classes serves as an 'AND' function. A vehcile must have all the properties listed +in the array to use the curb. To create an 'OR' function at the same curb, you must create a new rule +with the new array of values. + +New user classes MAY be generated to reflect local regulations, but when possible, +the following well-known recommended values should be used. + +**Well-known values:** + +Vehicle types - `bicycle` - `bus` -- `handicap` +- `cargo_bicycle` +- `car` +- `freight` +- `moped` - `motorcycle` -- `resident` +- `scooter` +- `truck` +- `van` + +Vehicle properties +- `handicap` +- `human` +- `electric_assist` +- `electric` +- `combustion` + +Purpose +- `construction` +- `delivery` +- `emergency_use` +- `freight` +- `parking` +- `permit` - `rideshare` +- `school` +- `service_vehicles` +- `special_events` - `taxi` -- `commercial` (applies to "truck"; if "commercial" and "truck" user classes have separate rules, - trucks use the "truck" rule) -- `truck` +- `utilities` +- `waste_management` ### Time Span From 9e24139ab9e70f7cca37dddce2099c6870816dcb Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 10:51:10 -0500 Subject: [PATCH 028/173] Updated Curbs TOC --- curbs/README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/curbs/README.md b/curbs/README.md index 8fb6d715..28186a49 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -42,6 +42,12 @@ There are four different endpoints that are part of the Curbs API: * [Curb Area](#curb-area) * [Curb Space](#curb-space) * [Policy](#policy) + * [Rule](#rate) + * [Time Span](#time-span) + * [Rate](#rate) + * [Activities](#activities) + * [User Classes](#user-classes) + * [Location Reference](#location-reference) # REST Endpoints From 7e554286783cf35e744d5708b0eec452d152ab13 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 10:52:06 -0500 Subject: [PATCH 029/173] Order of TOC --- curbs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 28186a49..73295d1b 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -43,10 +43,10 @@ There are four different endpoints that are part of the Curbs API: * [Curb Space](#curb-space) * [Policy](#policy) * [Rule](#rate) - * [Time Span](#time-span) - * [Rate](#rate) * [Activities](#activities) * [User Classes](#user-classes) + * [Time Span](#time-span) + * [Rate](#rate) * [Location Reference](#location-reference) # REST Endpoints From bf64f288b00dbfa08ad7e1cac5c0cd60f8017a93 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 10:53:16 -0500 Subject: [PATCH 030/173] Added TOC top links --- curbs/README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/curbs/README.md b/curbs/README.md index 73295d1b..4eef4e02 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -261,6 +261,8 @@ A Curb Zone is represented as a JSON object, whose fields are as follows: | `entire_roadway`| Boolean | Optional | If "true", this curb location takes up the entire width of the roadway (which may be impassible for through traffic when the Curb Zone is being used for parking or loading). This is a common condition for alleyways. If `entire_roadway` is `true`, `street_side` MUST NOT be present. | | `curb_area_id`| [UUID][uuid] | Optional | The ID of the [Curb Area](#curb-area) that this Curb Zone is a part of. If specified, the area identified MUST be retrievable through the Curb API and its geographical area MUST contain that of the Curb Zone. | +[Top][toc] + ### Curb Zone ID Stability The `curb_zone_id` field uniquely identifies a particular zone with one particular set of policies. @@ -333,6 +335,8 @@ A Policy is represented as a JSON object whose fields are as follows: | `rules` | Array of [Rules](#rule) | Required | The rule(s) that this policy applies. If a Policy specifies multiple rules, each rule MUST specify disjoint lists of user classes. | | `time_spans` | Array of [Time Spans](#time-span) | Optional | If specified, this regulation only applies at the times defined within. | +[Top][toc] + ### Rule A rule defines who is allowed to do what, and for how long, on a curb, per the policy. @@ -346,6 +350,8 @@ It is a JSON object with the following fields: | `user_classes` | Array of Strings | If specified, this regulation only applies to users matching the [user classes](#user-classes) contained within. If not specified, this regulation applies to everyone. | | `rate` | Array of [Rates](#rate) | Optional | The cost of using this Curb Zone when this regulation applies. Rates are repeated to allow for prices that change over time. For instance, a regulation may have a price of $1 for the first hour but $2 for every subsequent hour. | +[Top][toc] + #### Activities The following activities may be specified for rules within a policy. The reason we have @@ -363,6 +369,8 @@ for instance, implies that the Curb Zone does allow loading at the time in quest - `travel`: represents curbside lanes intended for moving vehicles, like bus lanes, bike lanes, and rush-hour-only travel lanes; implies that parking, loading, and stopping are prohibited). +[Top][toc] + #### User Classes A user class represents any class of vehicles that is regulated by a city with respect to curb @@ -416,6 +424,8 @@ Purpose - `utilities` - `waste_management` +[Top][toc] + ### Time Span A Time Span defines a period of time (that may occur once or repeatedly) during which a given regulation applies. When multiple fields are combined, all criteria must be met in order for a given Time Span to apply. For instance, the following Time Span represents 10AM to 1PM on Mondays and Tuesdays: @@ -442,6 +452,8 @@ A Time Span is represented as a JSON object whose fields are as follows: | `designated_period` | String | Optional | A string representing an arbitrarily-named, externally-defined period of time. Any values MAY be specified but the following known values SHOULD be used when possible:
  • `snow emergency`
  • `holidays`
  • `school days`
  • `game days`
| | `designated_period_except` | `Boolean` | `Optional` | If specified and `true`, this Time Span applies at all times not matching the named designated period. (e.g., if `designated_period` is `snow emergency` and `designated_period_except` is `true`, this Time Span does not apply on snow days). | +[Top][toc] + ### Rate A Rate defines the amount a user of the curb needs to pay when a given rule applies. It is a JSON object with the following fields: From aec89af314e24e1640d28f3083c8c5bc97bd70be Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 10:53:52 -0500 Subject: [PATCH 031/173] Updated rule TOC link --- curbs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/curbs/README.md b/curbs/README.md index 4eef4e02..53e335ce 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -42,7 +42,7 @@ There are four different endpoints that are part of the Curbs API: * [Curb Area](#curb-area) * [Curb Space](#curb-space) * [Policy](#policy) - * [Rule](#rate) + * [Rule](#rule) * [Activities](#activities) * [User Classes](#user-classes) * [Time Span](#time-span) From 5ae7bde1e3effe4c360499f1125857233d1d91dd Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 11:00:15 -0500 Subject: [PATCH 032/173] Merged activities into event_purpose --- events/README.md | 21 +++++---------------- 1 file changed, 5 insertions(+), 16 deletions(-) diff --git a/events/README.md b/events/README.md index f4e0d3ee..51cfef14 100644 --- a/events/README.md +++ b/events/README.md @@ -23,8 +23,7 @@ There are two different endpoints that are part of the Events API: * [Source Type](#source-type) * [Vehicle Type](#vehicle-type) * [Propulsion Type](#propulsion-type) - * [Activity Category](#activity-category) - * [Activity Type](#activity-type) + * [Event Purpose](#event_purpose) * [Lane Type](#lane-type) * [Curb Occupant](#curb-occupant) * [Status](#status) @@ -120,8 +119,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | | `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | | `propulsion_types` | Array of [Propulsion Type](#propulsion-type) | Conditionally Required | List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type. | -| `activity_category` | [Activity Category](#activity-category) | Conditionally Required | General activity that the vehicle performed. Required for sources capable of determining activity type for relevant event_types. | -| `activity_type` | [Activity Type](#activity-type) | Conditionally Required | Detailed type of activity that the vehicle performed. Required for sources capable of determining activity type for relevant event_types. | +| `event_purpose` | [Event Purpose](#event-purpose) | Conditionally Required | General curb usage purpose that the vehicle performed during the event. Required for sources capable of determining activity type for relevant event_types. | | `blocked_lane_types` | Array of [Lane Type](#lane-type) | Conditionally Required | Type(s) of lane blocked by the vehicle performing the event. If no lanes are blocked by the vehicle performing the event, the array should be empty. Required for the following event_types: _park_start_ | | `curb_occupants` | Array of [Curb Occupant](#curb-occupants) | Conditionally Required | Current occupants of the Curb Zone. If the sensor is capable of identifying the linear location of the vehicle, then elements are sorted in ascending order according to the start property of the linear reference. Otherwise, elements appear in no particular order. Required for the following event_types: _park_start, park_end, scheduled_report_ | | `currency` | String | Optional | Fields specifying a monetary cost use a currency as specified in ISO 4217. All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of 100 (for 100 cents). If the currency field is null, USD cents is implied. | @@ -197,11 +195,11 @@ A vehicle may have one or more values from the `propulsion`, depending on the nu [Top][toc] -### Activity Category +### Event Purpose -General, high-level category of activity that the vehicle performed, discernible by many sensors. +General purpose that the vehicle performed during its event, discernible by observation, sensors, or self-reported in company data feeds. New event purposes MAY be generated to reflect local curb uses, but when possible, the following well-known recommended values should be used. It may not always be knowable, but where it is possible this information should be conveyed. -| `activity_category` | Description | +| `event_purpose` | Description | | --------------------- | ------------------------------------------------------ | | `construction` | Construction of hard assets including buildings and roadside infrastructure | | `delivery` | General delivery of parcels, goods, freight | @@ -210,15 +208,6 @@ General, high-level category of activity that the vehicle performed, discernible | `passenger_transport` | Picking up and/or dropping off of human passengers | | `special_events` | Includes unloading equipment for concerts, theatre, street events | | `waste_management` | Retrieval/disposal of waste | - -[Top][toc] - -### Activity Type - -Detailed type of activity that the vehicle performed, if discernible based on the source, likely from advanced sensors or self-reported in company data feeds. Usually a subset of one of an [Activity Category](#activity_category). - -| `activity_type` | Description | -| --------------------- | ------------------------------------------------------ | | `device_maintenance` | Includes scooter pickup, drop off, battery swapping | | `ems` | Emergency medical vehicle use | | `fire` | Emergency fire vehicle | From b7739487f081a477af98d988fb44b369a4618c28 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 11:00:37 -0500 Subject: [PATCH 033/173] Event purpose in TOC --- events/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index 51cfef14..e94b5719 100644 --- a/events/README.md +++ b/events/README.md @@ -23,7 +23,7 @@ There are two different endpoints that are part of the Events API: * [Source Type](#source-type) * [Vehicle Type](#vehicle-type) * [Propulsion Type](#propulsion-type) - * [Event Purpose](#event_purpose) + * [Event Purpose](#event-purpose) * [Lane Type](#lane-type) * [Curb Occupant](#curb-occupant) * [Status](#status) From ba7586f1e5598c1bc3c390124c0fdc04aa30829b Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 11:07:51 -0500 Subject: [PATCH 034/173] Removed session_id from Events --- events/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/events/README.md b/events/README.md index e94b5719..eef8dfd3 100644 --- a/events/README.md +++ b/events/README.md @@ -108,7 +108,6 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `provider_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. | | `sensor_id` | [UUID][uuid] | Optional | If a sensor was used, the globally unique identifier of the sensor that recorded the event. Not needed if data is coming from a provider directly. | | `sensor_status` | Object | Optional | The status of the sensor that reported the event at the time that the event was reported. _is_commissioned_: Boolean, required. Indicates whether the sensor is currently in a state where it should be reporting data. _is_online_: Boolean, required. Indicates whether the sensor is currently online and reporting data. | -| `session_id` | [UUID][uuid] | Optional | If a source can determine if certain events can be connected, then they may provide a `session_id` to help connect via 'event_type' later. E.g., a park_start event and park_end event may be connected by the same `session_id`. | | `event_location` | GeoJSON | Required | The geographic point location where the event occurred. | | `event_time` | [Timestamp][ts] | Required | Time at which the event occurred. | | `publication_time` | [Timestamp][ts] | Required | Time at which the event became available for consumption by this API. | From e1697fde11f7e36517171bd5aeeac662ca592fc3 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 11:11:50 -0500 Subject: [PATCH 035/173] Event purpose multiple values --- events/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index eef8dfd3..468f5aef 100644 --- a/events/README.md +++ b/events/README.md @@ -196,7 +196,7 @@ A vehicle may have one or more values from the `propulsion`, depending on the nu ### Event Purpose -General purpose that the vehicle performed during its event, discernible by observation, sensors, or self-reported in company data feeds. New event purposes MAY be generated to reflect local curb uses, but when possible, the following well-known recommended values should be used. It may not always be knowable, but where it is possible this information should be conveyed. +General purpose that the vehicle performed during its event, discernible by observation, sensors, or self-reported in company data feeds. New event purposes MAY be generated to reflect local curb uses, but when possible, the following well-known recommended values should be used. It may not always be knowable, but where it is possible this information should be conveyed. If multile purposes apply, then use the more descriptive/specific value. | `event_purpose` | Description | | --------------------- | ------------------------------------------------------ | From 486a71527d996be60645e47605a7445d289018ef Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 11:13:15 -0500 Subject: [PATCH 036/173] User class multiple values --- curbs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 53e335ce..a4ccb017 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -386,7 +386,8 @@ in the array to use the curb. To create an 'OR' function at the same curb, you m with the new array of values. New user classes MAY be generated to reflect local regulations, but when possible, -the following well-known recommended values should be used. +the following well-known recommended values should be used. If multile similar values apply, then use the more +descriptive/specific value when possible. **Well-known values:** @@ -395,7 +396,6 @@ Vehicle types - `bus` - `cargo_bicycle` - `car` -- `freight` - `moped` - `motorcycle` - `scooter` From a8acc51e85d9e71509aa0b300996ca496bba7bfd Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 30 Nov 2021 11:15:55 -0500 Subject: [PATCH 037/173] Added example for user class --- curbs/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index a4ccb017..2025f8ec 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -382,7 +382,8 @@ These are not meant to be a mirror to similarly named items in the Events API, b unique purpose of describing locally defined regulations at a curb. This array of user classes serves as an 'AND' function. A vehcile must have all the properties listed -in the array to use the curb. To create an 'OR' function at the same curb, you must create a new rule +in the array to use the curb. For example, an accessible EV bus will use `handicap-accessible` AND `electric` +AND `bus`. To create 'OR' values at the same curb, you must create a new rule with the new array of values. New user classes MAY be generated to reflect local regulations, but when possible, @@ -403,7 +404,7 @@ Vehicle types - `van` Vehicle properties -- `handicap` +- `handicap-accessible` - `human` - `electric_assist` - `electric` From 3123525be30c93268c70863ae7027223dd8f5f7e Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 3 Dec 2021 15:36:44 -0500 Subject: [PATCH 038/173] Policy link on page --- curbs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/curbs/README.md b/curbs/README.md index 68ec8889..30dbe996 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -21,7 +21,7 @@ There are four different endpoints that are part of the Curbs API: - A [Curb Area](#curb-area) is a larger area of interest, such as a neighborhood or corridor, that could be used to show proximity, approaches, conflicts, circling, or other activity. Curb areas are *optional*. - - A [Curb Policy](#curb-area) A Policy object is a rule that allows or prohibits a particular set of + - A [Curb Policy](#policy) A Policy object is a rule that allows or prohibits a particular set of users from using a particular curb at a particular time or times. Curb policies are *optional*. ![Curb Places](https://i.imgur.com/YQ7P243.jpg) From 2e877eb170fb32f21588cbf345f72154f273d808 Mon Sep 17 00:00:00 2001 From: Brian Hamlin <83317465+bhamlinSDOT@users.noreply.github.com> Date: Fri, 3 Dec 2021 15:40:06 -0800 Subject: [PATCH 039/173] Update Curb Policy link. Fixed the Curb Policy link so it points to the right section. --- curbs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/curbs/README.md b/curbs/README.md index 0ec25ba5..13db0ccc 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -21,7 +21,7 @@ There are four different endpoints that are part of the Curbs API: - A [Curb Area](#curb-area) is a larger area of interest, such as a neighborhood or corridor, that could be used to show proximity, approaches, conflicts, circling, or other activity. Curb areas are *optional*. - - A [Curb Policy](#curb-area) A Policy object is a rule that allows or prohibits a particular set of + - A [Curb Policy](#policy) A Policy object is a rule that allows or prohibits a particular set of users from using a particular curb at a particular time or times. Curb policies are *optional*. ![Curb Places](https://i.imgur.com/YQ7P243.jpg) From 46883d4bd94369da83f149cf079f36bd568d456d Mon Sep 17 00:00:00 2001 From: Jacob Baskin Date: Wed, 8 Dec 2021 20:13:48 -0500 Subject: [PATCH 040/173] Fix typo in README --- curbs/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/curbs/README.md b/curbs/README.md index 13db0ccc..58dabc88 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -28,6 +28,7 @@ There are four different endpoints that are part of the Curbs API: # Table of Contents + - [REST Endpoints](#rest-endpoints) * [Query Curb Zones](#query-curb-zones) * [Query Curb Areas](#query-curb-areas) @@ -322,7 +323,7 @@ A Policy is represented as a JSON object whose fields are as follows: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `curb_policy_id` | UUD | Required | An ID that uniquely identifies this exact regulation across Curb Zones. Two Policy objects containing the same `curb_policy_id` MUST be completely identical. A `curb_policy_id` MUST NOT be reused -- once created, it must continue to refer to the identical policy forever. | +| `curb_policy_id` | UUID | Required | An ID that uniquely identifies this exact regulation across Curb Zones. Two Policy objects containing the same `curb_policy_id` MUST be completely identical. A `curb_policy_id` MUST NOT be reused -- once created, it must continue to refer to the identical policy forever. | | `priority` | Integer | Required | Specifies which other policies this one takes precedence over. If two Policies on the same Curb Zone have overlapping [Time Spans](#time-span) and apply to the same user class, the one that applies at a given time is the one with the **lowest** priority. Two Policies that apply to the same Curb Zone with overlapping Time Spans and user classes MUST NOT have the same priority. | | `rules` | Array of [Rules](#rule) | Required | The rule(s) that this policy applies. If a Policy specifies multiple rules, each rule MUST specify disjoint lists of user classes. | | `time_spans` | Array of [Time Spans](#time-span) | Optional | If specified, this regulation only applies at the times defined within. | From 5455259f76f5117661a61ec2a72603815f338bb9 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 13 Dec 2021 15:44:42 -0500 Subject: [PATCH 041/173] Create providers.csv --- providers.csv | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 providers.csv diff --git a/providers.csv b/providers.csv new file mode 100644 index 00000000..35e33cad --- /dev/null +++ b/providers.csv @@ -0,0 +1,2 @@ +provider_name,provider_id,url +SAMPLE COMPANY NAME,d548b89f-a76d-45f7-9e07-c2aae304031b,https://www.companywebsitename.com From 19e7a5a9f1fb52d0d1e8c1fcd5f5ae73a0460b6f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 13 Dec 2021 15:50:07 -0500 Subject: [PATCH 042/173] Clarified provider_id usage --- events/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/events/README.md b/events/README.md index 468f5aef..8efe0bc5 100644 --- a/events/README.md +++ b/events/README.md @@ -103,9 +103,9 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `event_type` | [Event Type](#event-type) | Required | The event_type that happened for this event. | | `source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | | `source_operator_id` | [UUID][uuid] | Required | Unique identifier of the entity responsible for operating the event source. This can be generated outside of CDS beforhand for each source operator. Different than `provider_id`. | -| `source_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is an ID they use and may be the same as `vehicle_id`. | -| `provider_id` | [UUID][uuid] | Optional | Unique ID of the provider responsible for operating the vehicle at the time of the event, if any. IDs are global and come from the [providers.csv](/providers.csv) file here in the CDS repo. | -| `provider_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. | +| `source_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as `vehicle_id`. | +| `provider_id` | [UUID][uuid] | Optional | Unique ID of the provider/operator/company responsible for operating the vehicle at the time of the event, if any. IDs are global and come from the [providers.csv](/providers.csv) file here in the CDS repo. An agency a their discretion may allow a small, local company to simply provide a consistent `provider_name` string instead of a `provider_id` from the global `providers.csv` file. | +| `provider_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `provider_id` or on its own. | | `sensor_id` | [UUID][uuid] | Optional | If a sensor was used, the globally unique identifier of the sensor that recorded the event. Not needed if data is coming from a provider directly. | | `sensor_status` | Object | Optional | The status of the sensor that reported the event at the time that the event was reported. _is_commissioned_: Boolean, required. Indicates whether the sensor is currently in a state where it should be reporting data. _is_online_: Boolean, required. Indicates whether the sensor is currently online and reporting data. | | `event_location` | GeoJSON | Required | The geographic point location where the event occurred. | From 646711b42e0b3e4ad1448199f1ab911fe28806bd Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 13 Dec 2021 20:37:10 -0500 Subject: [PATCH 043/173] Added license_plate with temporary privacy comment --- events/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index 8efe0bc5..c4759fd6 100644 --- a/events/README.md +++ b/events/README.md @@ -103,7 +103,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `event_type` | [Event Type](#event-type) | Required | The event_type that happened for this event. | | `source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | | `source_operator_id` | [UUID][uuid] | Required | Unique identifier of the entity responsible for operating the event source. This can be generated outside of CDS beforhand for each source operator. Different than `provider_id`. | -| `source_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as `vehicle_id`. | +| `source_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as the external `vehicle_id`. | | `provider_id` | [UUID][uuid] | Optional | Unique ID of the provider/operator/company responsible for operating the vehicle at the time of the event, if any. IDs are global and come from the [providers.csv](/providers.csv) file here in the CDS repo. An agency a their discretion may allow a small, local company to simply provide a consistent `provider_name` string instead of a `provider_id` from the global `providers.csv` file. | | `provider_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `provider_id` or on its own. | | `sensor_id` | [UUID][uuid] | Optional | If a sensor was used, the globally unique identifier of the sensor that recorded the event. Not needed if data is coming from a provider directly. | @@ -115,6 +115,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `curb_area_ids` | [UUID][uuid] | Conditionally Required | Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area for these event_types: _enter_area, exit_area, park_start, park_end_ | | `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space for these event_types: _park_start, park_end, enter_area, exit_area_ | | `vehicle_id` | String | Optional | A vehicle identifier visible on the vehicle itself. | +| `license_plate` | String | Optional | The consistently placed vehicle license plate, usable by ALPR systems, when required for curb use. This field is potentially sensitive (depending on local, state, and national laws) and a data privacy framework is recommended for collecting, retention, deletion, obsfucation, and security. | | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | | `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | | `propulsion_types` | Array of [Propulsion Type](#propulsion-type) | Conditionally Required | List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type. | From 219b6eddde2aedd7a7c25dd0700a4c293f1b48ce Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 14 Dec 2021 10:03:54 -0500 Subject: [PATCH 044/173] Added historic curb zones and previous policies support --- curbs/README.md | 54 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 38 insertions(+), 16 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index bab0b23c..2990e220 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -169,6 +169,7 @@ All query parameters are optional. | Name | Type | Description | | ------------ | --------- | ---------------------------------------------- | | `time` | [Timestamp][ts] | The Curb Zone object will only be returned if its validity period includes this time; otherwise, the server should reply with `404 Not Found`. Availability data (if supplied) will be returned as of this time. | +| `show_historic` | Boolean | Whether to return historic, retired curb zone data. Default is "false" to reduce payload size and complexity. | [Top][toc] @@ -231,7 +232,8 @@ criteria: 1. Never overlap other Curb Zones in the same dataset with overlapping validity times. This applies to both the zone's polygon geometries and linear references (if used). 1. Be assigned a unique ID, in the form of a [UUID][uuid]. This ID SHOULD remain consistent as long as - the Curb Zone's extent and policies remain substantially the same. + the Curb Zone's geography remains substantially the same. Policies may be updated without changing + the ID. 1. It SHOULD NOT be possible to legally park a single vehicle in two different Curb Zone at the same time (i.e., a given non-demarcated parking area or loading zone should be represented as a single curb location), unless this conflicts with the requirements above. @@ -241,8 +243,12 @@ A Curb Zone is represented as a JSON object, whose fields are as follows: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | | `curb_zone_id` | [UUID][uuid] | Required | The ID of this Curb Zone. | -| `geometry` | [Polygon][polygon] | Required | The spatial extent of this curb zone. | +| `geometry` | [Polygon][polygon] | Required | The spatial extent of this curb zone. A new `curb_zone_id` is required if this geometry changes. | | `curb_policy_ids` | Array of [UUIDs][uuid] | Required | An array of IDs of [Policy objects](#policy). Together, these define the regulations of this Curb Zone. | +| `prev_policies` | Array of [Previous Policy](#previous-policy) objects | Optional | An array of information about previous policies that have applied to this curb zone. The are listed in order with the most recent ones first. | +| `published_date` | [Timestamp][ts] | Required | The date/time that this curb zone was first published in this data feed. | +| `last_updated_date` | [Timestamp][ts] | Required | The date/time that the properties of ths curb zone were last updated. This helps consumers know that some curb objects fields may have changed. | +| `prev_curb_zone_ids` | Array of [UUIDs][uuid] | Optional | An array of IDs of previous curb zone objects. The are listed in order with the most recent ones first. | | `start_date` | [Timestamp][ts] | Required | The earliest time that the data for this curb location is known to be valid. This could be the date on which the data was collected, for instance. This MUST never change for a given id. | | `end_date` | [Timestamp][ts] | Optional | The time at which the data for this curb location ceases to be valid. If not present, the data will be presumed to be valid indefinitely. | | `location_references` | Array of [Location Reference](#location-reference) objects | Optional | One or more linear references for this Curb Zone. | @@ -266,17 +272,10 @@ A Curb Zone is represented as a JSON object, whose fields are as follows: ### Curb Zone ID Stability -The `curb_zone_id` field uniquely identifies a particular zone with one particular set of policies. +The `curb_zone_id` field uniquely identifies a particular zone with one particular set of policies in a specific geographic area. - - *New ID*: When a Curb Zone ceases to be valid, or it needs substantive changes, its ID - MUST NOT not be reused by a Curb Zone with different data, even if it occupies the same - location. If data updates reflect changes in the physical world or agency regulations, - a new ID MUST be assigned. - - *No new ID*: data updates that reflect changes in how the same physical locations or - regulations are modeled digitally -- e.g., additional metadata, or regulations being modeled - more accurately -- SHOULD NOT be implemented by ending a Curb Zone's validity and creating a - new one with a new ID. The existing Curb Zone can be updated silently with the new data; - callers MAY NOT rely on a Curb Zone with the same ID remaining identical over time. +- *New ID*: When a Curb Zone ceases to be valid, or it needs substantive geometric changes, it will be retired and returned only when the `show_historic` flag is "true" in the [Query Curb Zones](#query-curb-zones) endpoint parameters. Its ID _MUST NOT_ not be reused by a Curb Zone with different data. If geometric data updates reflect changes in the physical world, a new ID MUST be assigned and the previous one stored for historic lookups. +- *No new ID*: data updates that reflect changes in how the same physical locations or regulations are modeled digitally -- e.g., additional metadata, or regulations being modeled more accurately -- SHOULD NOT be implemented by ending a Curb Zone's validity and creating a new one with a new ID. The existing Curb Zone can be updated silently with the new data and its `last_updated_date` changed. Callers MAY NOT rely on a Curb Zone with the same ID remaining identical over time. If policies in a zone change, you may update the policy IDs, track previous policies, and reset the `last_updated_date`, but keep the zone ID the same. [Top][toc] @@ -285,9 +284,10 @@ The `curb_zone_id` field uniquely identifies a particular zone with one particul Defines curb areas in a city and their properties. A Curb Area is a particular neighborhood or area of interest that includes one or more [Curb Zones](#curb-zone). Important notes about Curb Areas: - * Curb Areas MAY overlap with other Curb Areas - * Curb Areas are not meant to be city-wide, and instead should be an area of interest around one + - Curb Areas MAY overlap with other Curb Areas + - Curb Areas are not meant to be city-wide, and instead should be an area of interest around one or more Curb Zones that is no bigger than a neighborhood. + - Unline Zones, Areas may be updated as needed, with a new `curb_area_id` being optionally assigned by the city A Curb Area is represented as a JSON object, whose fields are as follows: @@ -295,7 +295,9 @@ A Curb Area is represented as a JSON object, whose fields are as follows: | ------ | ------ | ------------------- | ------------- | | `curb_area_id` | [UUID][uuid] | Required | The ID for the curb area. | | `geometry` | [Polygon][polygon] | Required | The spatial extent of this curb location. | -| `name` | String | Required | The name of this curb area. | +| `name` | String | Optional | The name of this curb area for reference. | +| `published_date` | [Timestamp][ts] | Required | The date/time that this curb area was first published in this data feed. | +| `last_updated_date` | [Timestamp][ts] | Required | The date/time that the properties of ths curb area were last updated. This helps consumers know that some fields may have changed. | | `curb_zone_ids` | Array of [UUIDs][uuid] | Required | The IDs of all the Curb Zones included within this Curb Area at the requested time. | [Top][toc] @@ -303,8 +305,10 @@ A Curb Area is represented as a JSON object, whose fields are as follows: ## Curb Space Defines individual demarcated spaces within a Curb Zone. Important notes about Curb Spaces: + - Curb Spaces may NOT overlap with other Curb Spaces - Curb Spaces must be wholly contained within a single Curb Zone + - Unline Zones, Spaces may be updated as needed, with a new `curb_space_id` being optionally assigned by the city A Curb Space is represented as a JSON object whose fields are as follows: @@ -312,6 +316,9 @@ A Curb Space is represented as a JSON object whose fields are as follows: | ------ | ------ | ------------------- | ------------- | | `curb_space_id` | [UUID][uuid] | Required | The ID of the curb space. | | `geometry` | [Polygon][polygon] | Required |The spatial extent of this curb location. | +| `name` | String | Optional | The name of this curb space for reference. | +| `published_date` | [Timestamp][ts] | Required | The date/time that this curb area was first published in this data feed. | +| `last_updated_date` | [Timestamp][ts] | Required | The date/time that the properties of ths curb area were last updated. This helps consumers know that some fields may have changed. | | `curb_zone_id` | [UUID][uuid] | Required | The ID of the Curb Zone this space is within. The geometry of the specified Curb Zone MUST contain the geometry of this space. | | `space_number` | Integer | Optional | The sequence number of this space within its Zone. If specified, two spaces within the same Curb Zone MUST NOT share a space number, and space numbers SHOULD be consecutive positive integers starting at 1. | | `length` | Integer | Required | Length in centimeters of this Space. If comparing the length of a vehicle to that of a space, note that vehicles may have to account for a buffer for doors, mirrors, bumpers, ramps, etc. | @@ -323,7 +330,7 @@ A Curb Space is represented as a JSON object whose fields are as follows: ## Policy -A Policy object is a rule that allows or prohibits a particular set of users from using a particular curb at a particular time or times. Multiple Policy objects together define the full extent of regulations within a [Curb Zone](#curb-zone). The design of the Policy object borrows heavily from the work of the [CurbLR](https://github.com/curblr/curblr-spec) project. +A Policy object is a rule that allows or prohibits a particular set of users from using a particular curb at a particular time or times. Multiple Policy objects together define the full extent of regulations within a [Curb Zone](#curb-zone). The design of the Policy object borrows heavily from the work of the [CurbLR](https://github.com/curblr/curblr-spec) project, with additions for the larger scope of CDS. The `policy` field within the FeatureCollection returned by [Query Curb Zones](#query-curb-zones) contains a list of the Policy objects referenced by the returned zones. In addition, the [Query Curb Policies](#query-curb-policies) endpoint return the complete list of policies. @@ -332,6 +339,7 @@ A Policy is represented as a JSON object whose fields are as follows: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | | `curb_policy_id` | UUID | Required | An ID that uniquely identifies this exact regulation across Curb Zones. Two Policy objects containing the same `curb_policy_id` MUST be completely identical. A `curb_policy_id` MUST NOT be reused -- once created, it must continue to refer to the identical policy forever. | +| `published_date` | [Timestamp][ts] | Required | The date/time that this policy was first published in this data feed. | | `priority` | Integer | Required | Specifies which other policies this one takes precedence over. If two Policies on the same Curb Zone have overlapping [Time Spans](#time-span) and apply to the same user class, the one that applies at a given time is the one with the **lowest** priority. Two Policies that apply to the same Curb Zone with overlapping Time Spans and user classes MUST NOT have the same priority. | | `rules` | Array of [Rules](#rule) | Required | The rule(s) that this policy applies. If a Policy specifies multiple rules, each rule MUST specify disjoint lists of user classes. | | `time_spans` | Array of [Time Spans](#time-span) | Optional | If specified, this regulation only applies at the times defined within. | @@ -484,6 +492,20 @@ A Location Reference is a JSON object with the following fields: | `end` | Integer | Required | The distance (in centimeters) from the start of the referenced linear feature to the end of the Curb Zone. end MAY be smaller than start, implying that the direction of the Curb Zone is opposite to the direction of the referenced linear feature. | | `side` | String | Optional | If the referenced linear feature is a roadway, the side of the roadway on which the Curb Zone may be found, when heading from the start to the end of the feature in its native orientation. Values are `left` and `right`. MUST be absent for features where `entire_roadway` is true. | +[Top][toc] + +## Previous Policy + +An array of information about what previous policies applied to a [curb zone](#curb-zone) and when. This allows cities to historically track what policies applied to a curb zone. + +A Previous Policy is a JSON object with the following fields: + +| Name | Type | Required/Optional | Description | +| ------ | ------ | ------------------- | ------------- | +| `curb_policy_ids` | Array of [UUIDs][uuid] | Required | An array of IDs of [Policy objects](#policy). Together, these define the previous regulations of this Curb Zone. | +| `start_date` | [Timestamp][ts] | Required | The date/time that this policy started being active for this curb location. | +| `end_date` | [Timestamp][ts] | Required | The date/time that this policy ended being active for this curb location. | + [Top][toc] [toc]: #table-of-contents From 79f2f0fd74b7aa25ea5429b74064d99d05da40ce Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 11:16:14 -0500 Subject: [PATCH 045/173] Rearrange main page --- README.md | 57 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 7c439871..f5993476 100644 --- a/README.md +++ b/README.md @@ -7,63 +7,66 @@ - [Overview](#overview) - [Work in Progress](#work-in-progress) -- [Get Involved](#get-involved) - [Curb Data Specification APIs](#curb-data-specification-apis) - - [Modularity](#modularity) - [Structure](#structure) + - [Modularity](#modularity) + - [MDS Overlap](#mds-overlap) +- [Get Involved](#get-involved) - [Versions](#versions) - [Technical Information](#technical-information) - [Membership](#membership) # Overview -Urban curb is a valuable, limited, and often under-managed part of the public right of way. Curb demand is growing, including from commercial activity like passenger pickup/drop off, traditional and on-demand delivery services, new mobility programs like scooters, bikeshare, and carshare, and goods and freight delivery. While cities have made some progress in digitizing their curb and using curb data, more tools are needed to proactively manage curbs and sidewalks, and to deliver more public value from this scarce resource. Curb data standards can provide a mechanism for expressing static and dynamic regulations, measuring activity at the curb, and developing policies that create more accessible, useful curbs. +The Curb Data Specification (**CDS**), a project of the [Open Mobility Foundation](http://www.openmobilityfoundation.org/) (**OMF**), is a data standard and set of Application Programming Interfaces (APIs) that helps cities manage and companies use dynamic curb zones that optimize loading activities of people and goods, and measure the impact of these programs. -The Curb Data Specification (CDS) will help cities and companies pilot and scale dynamic curb zones that optimize commercial loading activities of people and goods, and measure the impact of these programs. +Urban curb is a valuable, limited, and often under-managed part of the public right of way. Curb demand is growing, including from commercial activity like passenger pickup/drop off, traditional and on-demand delivery services, new mobility programs like scooters, bikeshare, and carshare, and goods and freight delivery. While cities have made some progress in digitizing their curb and using curb data, more tools are needed to proactively manage curbs and sidewalks, and to deliver more public value from this scarce resource. Curb data standards can provide a mechanism for expressing static and dynamic regulations, measuring activity at the curb, and developing policies that create more accessible, useful curbs. -The CDS will be consumed by both cities and transportation providers operating in the public right of way. In many cases, the same mobility providers using curbs with CDS may also be interacting with other OMF [MDS Policy](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/policy), [MDS Provider](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/provider), and [MDS Agency](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/agency) data objects within the same [MDS Jurisdiction](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/jurisdiction) or [MDS Geography](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/geography), and using similar [MDS Metrics](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/metrics). Consistent with the Technology Design Principles codified in the OMF [Architectural Landscape Document](https://github.com/openmobilityfoundation/governance/blob/main/documents/OMF-MDS-Architectural-Landscape.pdf), the members of this working group are making reasonable best efforts to ensure that work is both _modular_ and _interoperable_ with other technology managed by the OMF as to avoid duplication and downstream implementation complexity. +![Curb Data Specification Logo](https://i.imgur.com/dc855VZ.png) [Top][toc] -# Work in Progress +# Curb Data Specification APIs -The CDS is a work in progress and is under ongoing development by the community under the guidance of the [Working Group Steering Committee](https://github.com/openmobilityfoundation/curb-data-specification/wiki) on specific [discussion topics](https://github.com/openmobilityfoundation/curb-data-specification/discussions) and bi-weekly [public meetings](https://github.com/openmobilityfoundation/curb-data-specification/wiki#meeting-agendas) around a specific [Scope of Work](https://docs.google.com/document/d/1yY5pRiiei8seVxXOmcYiqCA7wx7DueeatJnjbZoV3hU/). Work and dicussion is also happening in the [Curb Data Specification - Draft and Ideas Doc](https://docs.google.com/document/d/1UgD2fHtVyIMwNG-qXJRv-gcY7nCdYxokbMsLTs32Em4/edit?usp=sharing) before being committed to GitHub. The Steering Committee has created supplemntary resources the [Architectural Decisions](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Curb-Architectural-Decisions), [Curbs Use Cases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Curbs-Use-Cases), and [Pilot Project Guide](https://docs.google.com/document/d/1Mb1wpy4AFJ1MLvDpSIJsii4_1j2JC16NxNUVPI5BMNM/edit?usp=sharing) pages. The goal is to release a beta version of the spec by the end of 2021 and incorporate feedback from pilot programs into future versions. +CDS is at its core a set of Application Programming Interfaces (APIs) and endpoints within those APIs, which allow information to flow between organizations managing and using curb places. It includes the following APIs and their associated endpoints: -[Top][toc] +1. **[Curbs API](/curbs)** - communicate curb locations and policies publicly +1. **[Events API](/events)** - capture activity at Curbs from sensors and curb users +1. **[Metrics API](/metrics)** - methodology and metrics to understand Events at Curbs -# Get Involved - -The OMF’s [Curb Management Working Group](https://github.com/openmobilityfoundation/curb-data-specification/wiki), led by a steering committee of individuals representing public agencies and private sector companies, is developing this data specification for curb usage. The CDS will encompass digitized curb regulations, real time and historic event information, and utilization metrics. The specification will allow sharing of this data between cities, commercial companies, and the public. Get involoved by siging up to the [Curb Mailing List](https://groups.google.com/a/openmobilityfoundation.org/g/wg-curb). +CDS is a data exchange format and a translation layer between internal systems and external entities using data feeds. It is not expected that CDS will be the format used internally to store curb regulations in a city. The internal storage format is something different, and a subset of that data should be able to be converted to CDS for publishing out to the public and curb users. -The Curb Data Specification is an open source project with all development taking place on GitHub. Read our **[Community Wiki](https://github.com/openmobilityfoundation/curb-data-specification/wiki)** to get started. Comments and ideas can be shared by [starting a discussion](https://github.com/openmobilityfoundation/curb-data-specification/discussions), [creating an issue](https://github.com/openmobilityfoundation/curb-data-specification/issues), and specific changes can be suggested by [opening a pull request](https://github.com/openmobilityfoundation/curb-data-specification/pulls). Before contributing, please review our OMF [CONTRIBUTING page](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) and our [CODE OF CONDUCT page](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md) to understand guidelines and policies for participation. +Many parts of the CDS definitions and APIs align across each other. In these cases, consolidated information can be found on the [General Information](/general-information.md) page. -For questions about CDS please contact by email at [info@openmobilityfoundation.org](mailto:info@openmobilityfoundation.org) or [on our website](https://www.openmobilityfoundation.org/get-in-touch/). Media inquiries to [media@openmobilityfoundation.org](mailto:media@openmobilityfoundation.org). +## Structure -[Top][toc] +CDS contains a series of connected endpoints and fields beneath each interconnected API. -# Curb Data Specification APIs +

-CDS is at its core a set of Application Programming Interfaces (APIs) and endpoints within those APIs, which allow information to flow between organizations using and managing the curb areas. It includes the following APIs and their associated endpoints: +## Modularity -1. [Curbs API](/curbs) -1. [Events API](/events) -1. [Metrics API](/metrics) +CDS is designed to be a modular and flexible specification. Regulatory agencies can use the components of the API that are appropriate for their needs. An agency may choose to use only Curbs, while others may use Curbs, Events, and Metrics. Even within each API many endpoints and fields are optional. This design allows agencies, software and hardware companies, and curb users to use what's appropriate for their use cases, work within their operational capabilities, and text CDS in their pilot projects. -CDS is a data exchange format and a translation layer between internal systems and external entities using data feeds. It is not expected that CDS will be the format used internally to store curb regulations in a city. The internal storage format is something different, and a subset of that data should be able to be converted to CDS for publishing out to the public and curb users. +## MDS Overlap -Many parts of the CDS definitions and APIs align across each other. In these cases, consolidated information can be found on the [General Information](/general-information.md) page. +Like the [Mobility Data Specification](https://github.com/openmobilityfoundation/mobility-data-specification/) (MDS), the CDS will be consumed by both cities and transportation providers operating in the public right of way. In many cases, the same mobility providers using curbs with CDS may also be interacting with other OMF [MDS Policy](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/policy), [MDS Provider](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/provider), and [MDS Agency](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/agency) data objects within the same [MDS Jurisdiction](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/jurisdiction) or [MDS Geography](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/geography), and using similar [MDS Metrics](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/metrics). Consistent with the Technology Design Principles codified in the [Technology Council's](https://github.com/openmobilityfoundation/governance/wiki/Technology-Council) OMF [Architectural Landscape Document](https://github.com/openmobilityfoundation/governance/blob/main/documents/OMF-MDS-Architectural-Landscape.pdf), the members of this working group are making reasonable best efforts to ensure that work is both _modular_ and _interoperable_ with other technology managed by the OMF as to avoid duplication and downstream implementation complexity. [Top][toc] -## Modularity +# Work in Progress -CDS is designed to be a modular and flexible specification. Regulatory agencies can use the components of the API that are appropriate for their needs. An agency may choose to use only Curbs, while others may use Curbs, Events, and Metrics. Even within each API many endpoints and fields are optional. This design allows agencies, software and hardware companies, and curb users to use what's appropriate for their use cases, work within their operational capabilities, and text CDS in their pilot projects. +The CDS is a work in progress and is under ongoing development by the community under the guidance of the [Working Group Steering Committee](https://github.com/openmobilityfoundation/curb-data-specification/wiki) on specific [discussion topics](https://github.com/openmobilityfoundation/curb-data-specification/discussions) and bi-weekly [public meetings](https://github.com/openmobilityfoundation/curb-data-specification/wiki#meeting-agendas) around a specific [Scope of Work](https://docs.google.com/document/d/1yY5pRiiei8seVxXOmcYiqCA7wx7DueeatJnjbZoV3hU/). Work and dicussion is also happening in the [Curb Data Specification - Draft and Ideas Doc](https://docs.google.com/document/d/1UgD2fHtVyIMwNG-qXJRv-gcY7nCdYxokbMsLTs32Em4/edit?usp=sharing) before being committed to GitHub. The Steering Committee has created supplemntary resources the [Architectural Decisions](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Curb-Architectural-Decisions), [Curbs Use Cases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Curbs-Use-Cases), and [Pilot Project Guide](https://docs.google.com/document/d/1Mb1wpy4AFJ1MLvDpSIJsii4_1j2JC16NxNUVPI5BMNM/edit?usp=sharing) pages. The goal is to release a beta version of the spec by the end of 2021 and incorporate feedback from pilot programs into future versions. -## Structure +[Top][toc] -CDS contains a series of connected endpoints and fields beneath each interconnected API. +# Get Involved -![CDS Structure](https://i.imgur.com/L44996v.gif) +The OMF’s [Curb Management Working Group](https://github.com/openmobilityfoundation/curb-data-specification/wiki), led by a steering committee of individuals representing public agencies and private sector companies, is developing this data specification for curb usage. The CDS will encompass digitized curb regulations, real time and historic event information, and utilization metrics. The specification will allow sharing of this data between cities, commercial companies, and the public. Get involoved by siging up to the [Curb Mailing List](https://groups.google.com/a/openmobilityfoundation.org/g/wg-curb). + +The Curb Data Specification is an open source project with all development taking place on GitHub. Read our **[Community Wiki](https://github.com/openmobilityfoundation/curb-data-specification/wiki)** to get started. Comments and ideas can be shared by [starting a discussion](https://github.com/openmobilityfoundation/curb-data-specification/discussions), [creating an issue](https://github.com/openmobilityfoundation/curb-data-specification/issues), and specific changes can be suggested by [opening a pull request](https://github.com/openmobilityfoundation/curb-data-specification/pulls). Before contributing, please review our OMF [CONTRIBUTING page](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) and our [CODE OF CONDUCT page](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md) to understand guidelines and policies for participation. + +For questions about CDS please contact by email at [info@openmobilityfoundation.org](mailto:info@openmobilityfoundation.org) or [on our website](https://www.openmobilityfoundation.org/get-in-touch/). Media inquiries to [media@openmobilityfoundation.org](mailto:media@openmobilityfoundation.org). [Top][toc] @@ -75,7 +78,7 @@ CDS has a **current release**, and an **upcoming releases** in development. For The latest CDS release is in the [`main`](https://github.com/openmobilityfoundation/curb-data-specification/tree/main) branch, and development for the next release occurs in the [`dev`](https://github.com/openmobilityfoundation/curb-data-specification/tree/dev) branch. -The CDS specification is versioned using Git tags and [semantic versioning](https://semver.org/). +The CDS specification is versioned using Git tags and [semantic versioning](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md#versioning). * [Latest Release Branch](https://github.com/openmobilityfoundation/curb-data-specification/tree/main) (main) * [Development Branch](https://github.com/openmobilityfoundation/curb-data-specification/tree/dev) (dev) From c2ec6da3f560f751d4f64fd8402ce01f124f4975 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 13:34:54 -0500 Subject: [PATCH 046/173] Added link to provider id guide --- events/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index c4759fd6..a7f98e04 100644 --- a/events/README.md +++ b/events/README.md @@ -104,7 +104,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | | `source_operator_id` | [UUID][uuid] | Required | Unique identifier of the entity responsible for operating the event source. This can be generated outside of CDS beforhand for each source operator. Different than `provider_id`. | | `source_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as the external `vehicle_id`. | -| `provider_id` | [UUID][uuid] | Optional | Unique ID of the provider/operator/company responsible for operating the vehicle at the time of the event, if any. IDs are global and come from the [providers.csv](/providers.csv) file here in the CDS repo. An agency a their discretion may allow a small, local company to simply provide a consistent `provider_name` string instead of a `provider_id` from the global `providers.csv` file. | +| `provider_id` | [UUID][uuid] | Optional | Unique ID of the provider/operator/company responsible for operating the vehicle at the time of the event, if any. IDs are global and come from the [providers.csv](/providers.csv) file here in the CDS repo. Read our [How to Get a Provider ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Provider-ID) guide. An agency a their discretion may allow a small, local company to simply provide a consistent `provider_name` string instead of a `provider_id` from the global `providers.csv` file. | | `provider_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `provider_id` or on its own. | | `sensor_id` | [UUID][uuid] | Optional | If a sensor was used, the globally unique identifier of the sensor that recorded the event. Not needed if data is coming from a provider directly. | | `sensor_status` | Object | Optional | The status of the sensor that reported the event at the time that the event was reported. _is_commissioned_: Boolean, required. Indicates whether the sensor is currently in a state where it should be reporting data. _is_online_: Boolean, required. Indicates whether the sensor is currently online and reporting data. | From 3dc2e83ef26265e064b7f7afe579f1a24ef1ed85 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 15:43:21 -0500 Subject: [PATCH 047/173] TOC fix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f5993476..ff67009c 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,11 @@ ## Table of Contents - [Overview](#overview) -- [Work in Progress](#work-in-progress) - [Curb Data Specification APIs](#curb-data-specification-apis) - [Structure](#structure) - [Modularity](#modularity) - [MDS Overlap](#mds-overlap) +- [Work in Progress](#work-in-progress) - [Get Involved](#get-involved) - [Versions](#versions) - [Technical Information](#technical-information) From 2d67eaa2a1f3e2b12aeaae53553fb28f6dea1813 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 16:07:19 -0500 Subject: [PATCH 048/173] Formatting update on Curbs --- curbs/README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 2990e220..82c4cdd4 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -340,7 +340,7 @@ A Policy is represented as a JSON object whose fields are as follows: | ------ | ------ | ------------------- | ------------- | | `curb_policy_id` | UUID | Required | An ID that uniquely identifies this exact regulation across Curb Zones. Two Policy objects containing the same `curb_policy_id` MUST be completely identical. A `curb_policy_id` MUST NOT be reused -- once created, it must continue to refer to the identical policy forever. | | `published_date` | [Timestamp][ts] | Required | The date/time that this policy was first published in this data feed. | -| `priority` | Integer | Required | Specifies which other policies this one takes precedence over. If two Policies on the same Curb Zone have overlapping [Time Spans](#time-span) and apply to the same user class, the one that applies at a given time is the one with the **lowest** priority. Two Policies that apply to the same Curb Zone with overlapping Time Spans and user classes MUST NOT have the same priority. | +| `priority` | Integer | Required | Specifies which other policies this one takes precedence over. If two Policies on the same Curb Zone have overlapping [Time Spans](#time-span) and apply to the same user class, the one that applies at a given time is the one with the **lowest** priority. E.g., a priority of `1` takes precedence over a priority of `3`. Two Policies that apply to the same Curb Zone with overlapping Time Spans and user classes MUST NOT have the same priority. | | `rules` | Array of [Rules](#rule) | Required | The rule(s) that this policy applies. If a Policy specifies multiple rules, each rule MUST specify disjoint lists of user classes. | | `time_spans` | Array of [Time Spans](#time-span) | Optional | If specified, this regulation only applies at the times defined within. | @@ -349,14 +349,15 @@ A Policy is represented as a JSON object whose fields are as follows: ### Rule A rule defines who is allowed to do what, and for how long, on a curb, per the policy. + It is a JSON object with the following fields: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `activity` | String | Required | The activity that is forbidden or permitted by this regulation. Value MUST be one of the [activities below](#activities). | +| `activity` | String | Required | The activity that is forbidden or permitted by this regulation. Value MUST be one of the [activities](#activities). | | `max_stay` | Integer | Optional | The length of time (in minutes) for which the curb may be used under this regulation. | | `no_return` | Integer | Optional | The length of time (in minutes) that a user must vacate a Curb Zone before allowed to return for another stay. | -| `user_classes` | Array of Strings | If specified, this regulation only applies to users matching the [user classes](#user-classes) contained within. If not specified, this regulation applies to everyone. | +| `user_classes` | Array of Strings | Optional | If specified, this regulation only applies to users matching the [user classes](#user-classes) contained within. If not specified, this regulation applies to everyone. | | `rate` | Array of [Rates](#rate) | Optional | The cost of using this Curb Zone when this regulation applies. Rates are repeated to allow for prices that change over time. For instance, a regulation may have a price of $1 for the first hour but $2 for every subsequent hour. | [Top][toc] @@ -470,7 +471,7 @@ A Rate defines the amount a user of the curb needs to pay when a given rule appl | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `per_hour` | Integer | Required | The rate per hour for this space in cents (or the smallest denomination of local currency). | +| `per_hour` | Integer | Required | The rate per hour for this space in the smallest denomination of local currency. | | `increment_minutes` | Integer | Optional | If specified, this is the smallest amount of time a user can pay for (e.g., if `increment_minutes` is `15`, a user can pay for 15, 30, 45, etc. minutes). | | `increment_amount` | Integer | Optional | If specified, the rate for this space is rounded up to the nearest increment of this amount, specified in the same units as `per_hour`. | | `start_minutes` | Integer | Optional | The amount of time the vehicle must have already been present in the Curb Zone before this rate starts applying. If not specified, this rate starts when the vehicle arrives. | @@ -486,7 +487,7 @@ A Location Reference is a JSON object with the following fields: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `source` | URL | Required | An identifier for the source of the linear reference. This MUST be URL pointing to more information about the underlying map or reference system. Values include (but other can be used):
  • `https://sharedstreets.io`: SharedStreets
  • `http://openlr.org`: OpenLR
  • `https://coord.com`: Coord
  • `https://yourcityname.gov`: custom city LR, direct link if possible
    • | +| `source` | URL | Required | An identifier for the source of the linear reference. This MUST be a URL pointing to more information about the underlying map or reference system. Values include (but other can be used):
    • `https://sharedstreets.io`: SharedStreets
    • `http://openlr.org`: OpenLR
    • `https://coord.com`: Coord
    • `https://yourcityname.gov`: custom city LR, direct link if possible
      • | | `ref_id` | String | Required | The linear feature being referenced (usually a street or curb segment). For OpenLR, this is the Base64-encoded OpenLR line location for the street segment of which this Curb Zone is part, and the start and end offsets below are relative to this segment. | | `start` | Integer | Required | The distance (in centimeters) from the start of the referenced linear feature to the start of the Curb Zone. | | `end` | Integer | Required | The distance (in centimeters) from the start of the referenced linear feature to the end of the Curb Zone. end MAY be smaller than start, implying that the direction of the Curb Zone is opposite to the direction of the referenced linear feature. | From 3b026773e661748115e46712a4cacc001b19aa97 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 16:14:56 -0500 Subject: [PATCH 049/173] Typo fix --- curbs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 82c4cdd4..a94cbc80 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -287,7 +287,7 @@ of interest that includes one or more [Curb Zones](#curb-zone). Important notes - Curb Areas MAY overlap with other Curb Areas - Curb Areas are not meant to be city-wide, and instead should be an area of interest around one or more Curb Zones that is no bigger than a neighborhood. - - Unline Zones, Areas may be updated as needed, with a new `curb_area_id` being optionally assigned by the city + - Unlike Zones, Areas may be updated as needed, with a new `curb_area_id` being optionally assigned by the city A Curb Area is represented as a JSON object, whose fields are as follows: @@ -308,7 +308,7 @@ Defines individual demarcated spaces within a Curb Zone. Important notes about C - Curb Spaces may NOT overlap with other Curb Spaces - Curb Spaces must be wholly contained within a single Curb Zone - - Unline Zones, Spaces may be updated as needed, with a new `curb_space_id` being optionally assigned by the city + - Unlike Zones, Spaces may be updated as needed, with a new `curb_space_id` being optionally assigned by the city A Curb Space is represented as a JSON object whose fields are as follows: From 6d4824ed5087c5d28aad213deab8b8243a476db0 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 16:24:12 -0500 Subject: [PATCH 050/173] Added provider_ids in Policy as optional --- curbs/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/curbs/README.md b/curbs/README.md index a94cbc80..9493f0c9 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -343,6 +343,7 @@ A Policy is represented as a JSON object whose fields are as follows: | `priority` | Integer | Required | Specifies which other policies this one takes precedence over. If two Policies on the same Curb Zone have overlapping [Time Spans](#time-span) and apply to the same user class, the one that applies at a given time is the one with the **lowest** priority. E.g., a priority of `1` takes precedence over a priority of `3`. Two Policies that apply to the same Curb Zone with overlapping Time Spans and user classes MUST NOT have the same priority. | | `rules` | Array of [Rules](#rule) | Required | The rule(s) that this policy applies. If a Policy specifies multiple rules, each rule MUST specify disjoint lists of user classes. | | `time_spans` | Array of [Time Spans](#time-span) | Optional | If specified, this regulation only applies at the times defined within. | +| `provider_ids` | Array of [UUIDs][uuid] | Optional | An array of provider IDs that this policy only applies to. IDs come from [providers.csv](/providers.csv) file here in the CDS repo. Read our [How to Get a Provider ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Provider-ID) guide. | [Top][toc] From 3b71a0f5c28856c02211b1ab672ad0766baca1e0 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 21:34:55 -0500 Subject: [PATCH 051/173] Multiple spelling fixes --- events/README.md | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/events/README.md b/events/README.md index a7f98e04..b7077ace 100644 --- a/events/README.md +++ b/events/README.md @@ -1,6 +1,6 @@ # Curb Data Specification: Events API -The Events API is a REST API allowing real-time and historic events at the curb to be sent to cities, and the ability to check on the status of any sensors. Events can come from company data feeds, sensors, payments, check-ins, enforcement, and/or other city data sources. Data sent in the Events API can be connected to the Curbs API over time and space, and events are used for calcuations in the Metrics API. +The Events API is a REST API allowing real-time and historic events at the curb to be sent to cities, and the ability to check on the status of any sensors. Events can come from company data feeds, sensors, payments, check-ins, enforcement, and/or other city data sources. Data sent in the Events API can be connected to the Curbs API over time and space, and events are used for calculations in the Metrics API. ## ⚠ Beta > **This feature is current a draft of the initial CDS beta release. It will change as development and real-world feedback happens.** @@ -63,9 +63,9 @@ All query parameters are optional. | Name | Type | Description | | ------------ | --------- | ---------------------------------------------- | -| `curb_area_id` | [UUID][uuid] | The ID of a [Curb Area](#curb-area). If specified, only return events occuring within this area. | -| `curb_zone_id` | [UUID][uuid] | The ID of a [Curb Zone](#curb-zone). If specified, only return events occuring within this zone. | -| `curb_space_id` | [UUID][uuid] | The ID of a [Curb Space](#curb-space). If specified, only return events occuring within this space. | +| `curb_area_id` | [UUID][uuid] | The ID of a [Curb Area](#curb-area). If specified, only return events occurring within this area. | +| `curb_zone_id` | [UUID][uuid] | The ID of a [Curb Zone](#curb-zone). If specified, only return events occurring within this zone. | +| `curb_space_id` | [UUID][uuid] | The ID of a [Curb Space](#curb-space). If specified, only return events occurring within this space. | [Top][toc] @@ -102,9 +102,9 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `event_id` | [UUID][uuid] | Required | The globally unique identifier of the event that occurred. | | `event_type` | [Event Type](#event-type) | Required | The event_type that happened for this event. | | `source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | -| `source_operator_id` | [UUID][uuid] | Required | Unique identifier of the entity responsible for operating the event source. This can be generated outside of CDS beforhand for each source operator. Different than `provider_id`. | +| `source_operator_id` | [UUID][uuid] | Required | Unique identifier of the entity responsible for operating the event source. This can be generated outside of CDS beforehand for each source operator. Different than `provider_id`. | | `source_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as the external `vehicle_id`. | -| `provider_id` | [UUID][uuid] | Optional | Unique ID of the provider/operator/company responsible for operating the vehicle at the time of the event, if any. IDs are global and come from the [providers.csv](/providers.csv) file here in the CDS repo. Read our [How to Get a Provider ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Provider-ID) guide. An agency a their discretion may allow a small, local company to simply provide a consistent `provider_name` string instead of a `provider_id` from the global `providers.csv` file. | +| `provider_id` | [UUID][uuid] | Optional | Unique ID of the provider/operator/company responsible for operating the vehicle at the time of the event, if any. IDs are global and come from the [providers.csv](/providers.csv) file here in the CDS repo. Read our [How to Get a Provider ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Provider-ID) guide. An agency at their discretion may allow a small, local company to simply provide a consistent `provider_name` string instead of a `provider_id` from the global `providers.csv` file. | | `provider_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `provider_id` or on its own. | | `sensor_id` | [UUID][uuid] | Optional | If a sensor was used, the globally unique identifier of the sensor that recorded the event. Not needed if data is coming from a provider directly. | | `sensor_status` | Object | Optional | The status of the sensor that reported the event at the time that the event was reported. _is_commissioned_: Boolean, required. Indicates whether the sensor is currently in a state where it should be reporting data. _is_online_: Boolean, required. Indicates whether the sensor is currently online and reporting data. | @@ -115,7 +115,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `curb_area_ids` | [UUID][uuid] | Conditionally Required | Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area for these event_types: _enter_area, exit_area, park_start, park_end_ | | `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space for these event_types: _park_start, park_end, enter_area, exit_area_ | | `vehicle_id` | String | Optional | A vehicle identifier visible on the vehicle itself. | -| `license_plate` | String | Optional | The consistently placed vehicle license plate, usable by ALPR systems, when required for curb use. This field is potentially sensitive (depending on local, state, and national laws) and a data privacy framework is recommended for collecting, retention, deletion, obsfucation, and security. | +| `license_plate` | String | Optional | The consistently placed vehicle license plate, usable by ALPR systems, when required for curb use. This field is potentially sensitive (depending on local, state, and national laws) and a data privacy framework is recommended for collecting, retention, deletion, obfuscation, and security. | | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | | `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | | `propulsion_types` | Array of [Propulsion Type](#propulsion-type) | Conditionally Required | List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type. | @@ -131,16 +131,16 @@ A Curb Event is represented as a JSON object, whose fields are as follows: `event_type`. Curb Event Type enumerates the set of possible types of Curb Event. The values that it can assume are listed below: -| `event_type` | Description | -|----------------| ----------- | -| `comms_lost` | communications with the event source were lost | -| `comms_restored` | communications with the event source were restored | -| `decommissioned` | event source was decommissioned | -| `park_start` | a vehicle stopped, parked, or double parked | -| `park_end` | a parked vehicle leaving a parked or stopped state and resuming movement | -| `scheduled_report` | event source reported status status at a scheduled interval | -| `enter_area` | vehicle enters the relevant geographic area | -| `exit_area` | vehicle exits the relevant geographic area | +| `event_type` | Description | +|--------------------|-------------| +| `comms_lost` | communications with the event source were lost | +| `comms_restored` | communications with the event source were restored | +| `decommissioned` | event source was decommissioned | +| `park_start` | a vehicle stopped, parked, or double parked | +| `park_end` | a parked vehicle leaving a parked or stopped state and resuming movement | +| `scheduled_report` | event source reported status at a scheduled interval | +| `enter_area` | vehicle enters the relevant geographic area | +| `exit_area` | vehicle exits the relevant geographic area | [Top][toc] @@ -156,7 +156,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `in_ground` | sensor deployed in the ground | | `meter` | a smart parking meter | | `in_person` | an individual on site recording the event digitally or otherwise | -| `other` | sources not ennumerated above | +| `other` | sources not enumerated above | [Top][toc] @@ -197,7 +197,7 @@ A vehicle may have one or more values from the `propulsion`, depending on the nu ### Event Purpose -General purpose that the vehicle performed during its event, discernible by observation, sensors, or self-reported in company data feeds. New event purposes MAY be generated to reflect local curb uses, but when possible, the following well-known recommended values should be used. It may not always be knowable, but where it is possible this information should be conveyed. If multile purposes apply, then use the more descriptive/specific value. +General purpose that the vehicle performed during its event, discernible by observation, sensors, or self-reported in company data feeds. New event purposes MAY be generated to reflect local curb uses, but when possible, the following well-known recommended values should be used. It may not always be knowable, but where it is possible this information should be conveyed. If multiple purposes apply, then use the more descriptive/specific value. | `event_purpose` | Description | | --------------------- | ------------------------------------------------------ | @@ -228,14 +228,14 @@ General purpose that the vehicle performed during its event, discernible by obse ### Lane Type -`lane_type`. Type(s) of lane used or blocked by the vehicle performing the event, ouside of curb zones. E.g., double parking. +`lane_type`. Type(s) of lane used or blocked by the vehicle performing the event, outside of curb zones. E.g., double parking. | `lane_type` | Description | | -------------- | ------------------------------------------------------ | | `travel_lane` | A standard vehicle travel lane. | | `turn_lane` | A dedicated turn lane. | | `bike_lane` | A lane dedicated for usage by cyclists. | -| `bus_lane` | A lane dedicated for usage by busses. | +| `bus_lane` | A lane dedicated for usage by buses. | | `parking` | A lane used for parking, not allowed for travel. | | `shoulder` | A portion of the roadway that is outside (either right or left) of the main travel lanes. A shoulder can have many uses but is not intended for general traffic. | | `median` | An often unpaved, non-drivable area that separates sections of the roadway. | From 022ceddecf38b03c9c5df4a85db5e64be854bb67 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 21:43:16 -0500 Subject: [PATCH 052/173] Spelling in Curbs --- curbs/README.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 9493f0c9..f80df2d9 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -245,10 +245,10 @@ A Curb Zone is represented as a JSON object, whose fields are as follows: | `curb_zone_id` | [UUID][uuid] | Required | The ID of this Curb Zone. | | `geometry` | [Polygon][polygon] | Required | The spatial extent of this curb zone. A new `curb_zone_id` is required if this geometry changes. | | `curb_policy_ids` | Array of [UUIDs][uuid] | Required | An array of IDs of [Policy objects](#policy). Together, these define the regulations of this Curb Zone. | -| `prev_policies` | Array of [Previous Policy](#previous-policy) objects | Optional | An array of information about previous policies that have applied to this curb zone. The are listed in order with the most recent ones first. | +| `prev_policies` | Array of [Previous Policy](#previous-policy) objects | Optional | An array of information about previous policies that have applied to this curb zone. They are listed in order with the most recent ones first. | | `published_date` | [Timestamp][ts] | Required | The date/time that this curb zone was first published in this data feed. | | `last_updated_date` | [Timestamp][ts] | Required | The date/time that the properties of ths curb zone were last updated. This helps consumers know that some curb objects fields may have changed. | -| `prev_curb_zone_ids` | Array of [UUIDs][uuid] | Optional | An array of IDs of previous curb zone objects. The are listed in order with the most recent ones first. | +| `prev_curb_zone_ids` | Array of [UUIDs][uuid] | Optional | An array of IDs of previous curb zone objects. They are listed in order with the most recent ones first. | | `start_date` | [Timestamp][ts] | Required | The earliest time that the data for this curb location is known to be valid. This could be the date on which the data was collected, for instance. This MUST never change for a given id. | | `end_date` | [Timestamp][ts] | Optional | The time at which the data for this curb location ceases to be valid. If not present, the data will be presumed to be valid indefinitely. | | `location_references` | Array of [Location Reference](#location-reference) objects | Optional | One or more linear references for this Curb Zone. | @@ -357,7 +357,7 @@ It is a JSON object with the following fields: | ------ | ------ | ------------------- | ------------- | | `activity` | String | Required | The activity that is forbidden or permitted by this regulation. Value MUST be one of the [activities](#activities). | | `max_stay` | Integer | Optional | The length of time (in minutes) for which the curb may be used under this regulation. | -| `no_return` | Integer | Optional | The length of time (in minutes) that a user must vacate a Curb Zone before allowed to return for another stay. | +| `no_return` | Integer | Optional | The length of time (in minutes) that a user must vacate a Curb Zone before being allowed to return for another stay. | | `user_classes` | Array of Strings | Optional | If specified, this regulation only applies to users matching the [user classes](#user-classes) contained within. If not specified, this regulation applies to everyone. | | `rate` | Array of [Rates](#rate) | Optional | The cost of using this Curb Zone when this regulation applies. Rates are repeated to allow for prices that change over time. For instance, a regulation may have a price of $1 for the first hour but $2 for every subsequent hour. | @@ -371,14 +371,14 @@ is due to priorities: a `loading` rule that is higher priority than a `no loadin for instance, implies that the Curb Zone does allow loading at the time in question, while a `no parking` rule would not. -- `parking` (implies that loading and stopping are also permitted) +- `parking` - implies that loading and stopping are also permitted - `no parking` -- `loading` (of goods; implies that stopping is also permitted) -- `no loading` (implies that parking is also prohibited) -- `stopping` (stopping briefly to pick up or drop off passengers) -- `no stopping` (stopping, loading, and parking are all prohibited) -- `travel`: represents curbside lanes intended for moving vehicles, like bus lanes, bike lanes, - and rush-hour-only travel lanes; implies that parking, loading, and stopping are prohibited). +- `loading` - of goods; implies that stopping is also permitted +- `no loading` - implies that parking is also prohibited +- `stopping` - stopping briefly to pick up or drop off passengers +- `no stopping` - stopping, loading, and parking are all prohibited +- `travel` - represents curbside lanes intended for moving vehicles, like bus lanes, bike lanes, + and rush-hour-only travel lanes; implies that parking, loading, and stopping are prohibited. [Top][toc] @@ -392,13 +392,13 @@ intent or destination of the driver, for things like hotel or school unloading z These are not meant to be a mirror to similarly named items in the Events API, but instead serve a unique purpose of describing locally defined regulations at a curb. -This array of user classes serves as an 'AND' function. A vehcile must have all the properties listed +This array of user classes serves as an 'AND' function. A vehicle must have all the properties listed in the array to use the curb. For example, an accessible EV bus will use `handicap-accessible` AND `electric` AND `bus`. To create 'OR' values at the same curb, you must create a new rule with the new array of values. New user classes MAY be generated to reflect local regulations, but when possible, -the following well-known recommended values should be used. If multile similar values apply, then use the more +the following well-known recommended values should be used. If multiple similar values apply, then use the more descriptive/specific value when possible. **Well-known values:** @@ -491,7 +491,7 @@ A Location Reference is a JSON object with the following fields: | `source` | URL | Required | An identifier for the source of the linear reference. This MUST be a URL pointing to more information about the underlying map or reference system. Values include (but other can be used):
      • `https://sharedstreets.io`: SharedStreets
      • `http://openlr.org`: OpenLR
      • `https://coord.com`: Coord
      • `https://yourcityname.gov`: custom city LR, direct link if possible
        • | | `ref_id` | String | Required | The linear feature being referenced (usually a street or curb segment). For OpenLR, this is the Base64-encoded OpenLR line location for the street segment of which this Curb Zone is part, and the start and end offsets below are relative to this segment. | | `start` | Integer | Required | The distance (in centimeters) from the start of the referenced linear feature to the start of the Curb Zone. | -| `end` | Integer | Required | The distance (in centimeters) from the start of the referenced linear feature to the end of the Curb Zone. end MAY be smaller than start, implying that the direction of the Curb Zone is opposite to the direction of the referenced linear feature. | +| `end` | Integer | Required | The distance (in centimeters) from the start of the referenced linear feature to the end of the Curb Zone. 'end' MAY be smaller than start, implying that the direction of the Curb Zone is opposite to the direction of the referenced linear feature. | | `side` | String | Optional | If the referenced linear feature is a roadway, the side of the roadway on which the Curb Zone may be found, when heading from the start to the end of the feature in its native orientation. Values are `left` and `right`. MUST be absent for features where `entire_roadway` is true. | [Top][toc] From b16e6003cd5a0a58b18ea4de04fc6d7bd1e9cbc3 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 21:46:15 -0500 Subject: [PATCH 053/173] Spelling in Metrics file --- metrics/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index dee4c4c0..cd9c1804 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -27,7 +27,7 @@ There are two different endpoints that are part of the Metrics API: # Representative Sample Data -All data returned by the Metrics API should be viewed as using representative sample data, and not neccessarily a 100% accurate picture of what happens at every defined curb space. This is because CDS Events can come from multiple sources (company data feeds, sensors, video analysis, payments, check-ins, enforcement, and/or other city data sources), cities may implement only one or more of these sources, each source returns different types and accuracy of data, and sources may not be easily cross-comparible. It is up to the city consuming Events and producing Metrics to determine accuracy and methodology details within their circumstances, and we welcome feedback, refinement, clarification, and more defined methodology per source type for future CDS releases. +All data returned by the Metrics API should be viewed as using representative sample data, and not necessarily a 100% accurate picture of what happens at every defined curb space. This is because CDS Events can come from multiple sources (company data feeds, sensors, video analysis, payments, check-ins, enforcement, and/or other city data sources), cities may implement only one or more of these sources, each source returns different types and accuracy of data, and sources may not be easily cross-comparible. It is up to the city consuming Events and producing Metrics to determine accuracy and methodology details within their circumstances, and we welcome feedback, refinement, clarification, and more defined methodology per source type for future CDS releases. # REST Endpoints @@ -134,7 +134,7 @@ For `session_type` of `area`: - **enter_area**: vehicle enters the relevant geographic area - **exit_area**: vehicle exits the relevant geographic area -**Note:** It is prefereable to return both start/end or enter/exit pairs of events. However, even if only one of these is present, the available data should be returned with the corresponding missing values of `event_id_X`, `event_location_X`, `event_time_X` returned as _null_. +**Note:** It is preferable to return both start/end or enter/exit pairs of events. However, even if only one of these is present, the available data should be returned with the corresponding missing values of `event_id_X`, `event_location_X`, `event_time_X` returned as _null_. A "session duration" or "dwell time" can be calculated by calculating the difference between the `event_time_start` and `event_time_end`. @@ -142,7 +142,7 @@ A "session duration" or "dwell time" can be calculated by calculating the differ ## Aggregate -Aggregates are historic pre-computed counts and metrics of Events occuring in curb places, aggregated to the hour. All Aggregates can be calculated from the data included in [Session](#session). +Aggregates are historic pre-computed counts and metrics of Events occurring in curb places, aggregated to the hour. All Aggregates can be calculated from the data included in [Session](#session). An Aggregate is represented as a CSV object, whose fields are as follows, as calculated from the Metrics [Methodology](#methodology): @@ -153,7 +153,7 @@ An Aggregate is represented as a CSV object, whose fields are as follows, as cal | `metric_type` | Enum | Required | The metric this aggregate applies to from the [Methodology](#methodology): `total_sessions`, `turnover`, `average_dwell_time`, `occupancy_percent`. | | `date` | date | Required | The date the event occured in ISO 8601 format, local timezone, in "YYYY-MM-DD" format. E.g. "2021-10-31" | | `hour` | integer | Required | The hour of the day the event occured in ISO 8601 format, local timezone, in "hh" format. E.g. "23" | -| `value` | number | Required | The results of the calculations for this metric from the [Methodology](#methodology). Note that "-1" means the the sensor/source was offline for the majority of the time. E.g. "6", "2.9", "-1", or "0.05" | +| `value` | number | Required | The results of the calculations for this metric from the [Methodology](#methodology). Note that "-1" means that the sensor/source was offline for the majority of the time. E.g. "6", "2.9", "-1", or "0.05" | ### Methodology From 02a122b9cbe466feb23cd3fa6e7a0c51c7af723e Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 21:48:49 -0500 Subject: [PATCH 054/173] Spelling in main page --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ff67009c..a45858a3 100644 --- a/README.md +++ b/README.md @@ -50,19 +50,19 @@ CDS is designed to be a modular and flexible specification. Regulatory agencies ## MDS Overlap -Like the [Mobility Data Specification](https://github.com/openmobilityfoundation/mobility-data-specification/) (MDS), the CDS will be consumed by both cities and transportation providers operating in the public right of way. In many cases, the same mobility providers using curbs with CDS may also be interacting with other OMF [MDS Policy](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/policy), [MDS Provider](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/provider), and [MDS Agency](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/agency) data objects within the same [MDS Jurisdiction](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/jurisdiction) or [MDS Geography](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/geography), and using similar [MDS Metrics](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/metrics). Consistent with the Technology Design Principles codified in the [Technology Council's](https://github.com/openmobilityfoundation/governance/wiki/Technology-Council) OMF [Architectural Landscape Document](https://github.com/openmobilityfoundation/governance/blob/main/documents/OMF-MDS-Architectural-Landscape.pdf), the members of this working group are making reasonable best efforts to ensure that work is both _modular_ and _interoperable_ with other technology managed by the OMF as to avoid duplication and downstream implementation complexity. +Like the [Mobility Data Specification](https://github.com/openmobilityfoundation/mobility-data-specification/) (MDS), the CDS will be consumed by both cities and transportation providers operating in the public right of way. In many cases, the same mobility providers using curbs with CDS may also be interacting with other OMF [MDS Policy](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/policy), [MDS Provider](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/provider), and [MDS Agency](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/agency) data objects within the same [MDS Jurisdiction](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/jurisdiction) or [MDS Geography](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/geography), and using similar [MDS Metrics](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/metrics). Consistent with the Technology Design Principles codified in the [Technology Council's](https://github.com/openmobilityfoundation/governance/wiki/Technology-Council) OMF [Architectural Landscape Document](https://github.com/openmobilityfoundation/governance/blob/main/documents/OMF-MDS-Architectural-Landscape.pdf), the members of this working group are making reasonable best efforts to ensure that work is both _modular_ and _inter operable_ with other technology managed by the OMF as to avoid duplication and downstream implementation complexity. [Top][toc] # Work in Progress -The CDS is a work in progress and is under ongoing development by the community under the guidance of the [Working Group Steering Committee](https://github.com/openmobilityfoundation/curb-data-specification/wiki) on specific [discussion topics](https://github.com/openmobilityfoundation/curb-data-specification/discussions) and bi-weekly [public meetings](https://github.com/openmobilityfoundation/curb-data-specification/wiki#meeting-agendas) around a specific [Scope of Work](https://docs.google.com/document/d/1yY5pRiiei8seVxXOmcYiqCA7wx7DueeatJnjbZoV3hU/). Work and dicussion is also happening in the [Curb Data Specification - Draft and Ideas Doc](https://docs.google.com/document/d/1UgD2fHtVyIMwNG-qXJRv-gcY7nCdYxokbMsLTs32Em4/edit?usp=sharing) before being committed to GitHub. The Steering Committee has created supplemntary resources the [Architectural Decisions](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Curb-Architectural-Decisions), [Curbs Use Cases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Curbs-Use-Cases), and [Pilot Project Guide](https://docs.google.com/document/d/1Mb1wpy4AFJ1MLvDpSIJsii4_1j2JC16NxNUVPI5BMNM/edit?usp=sharing) pages. The goal is to release a beta version of the spec by the end of 2021 and incorporate feedback from pilot programs into future versions. +The CDS is a work in progress and is under ongoing development by the community under the guidance of the [Working Group Steering Committee](https://github.com/openmobilityfoundation/curb-data-specification/wiki) on specific [discussion topics](https://github.com/openmobilityfoundation/curb-data-specification/discussions) and bi-weekly [public meetings](https://github.com/openmobilityfoundation/curb-data-specification/wiki#meeting-agendas) around a specific [Scope of Work](https://docs.google.com/document/d/1yY5pRiiei8seVxXOmcYiqCA7wx7DueeatJnjbZoV3hU/). Work and discussion is also happening in the [Curb Data Specification - Draft and Ideas Doc](https://docs.google.com/document/d/1UgD2fHtVyIMwNG-qXJRv-gcY7nCdYxokbMsLTs32Em4/edit?usp=sharing) before being committed to GitHub. The Steering Committee has created supplementary resources the [Architectural Decisions](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Curb-Architectural-Decisions), [Curbs Use Cases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Curbs-Use-Cases), and [Pilot Project Guide](https://docs.google.com/document/d/1Mb1wpy4AFJ1MLvDpSIJsii4_1j2JC16NxNUVPI5BMNM/edit?usp=sharing) pages. The goal is to release a beta version of the spec by the end of 2021 and incorporate feedback from pilot programs into future versions. [Top][toc] # Get Involved -The OMF’s [Curb Management Working Group](https://github.com/openmobilityfoundation/curb-data-specification/wiki), led by a steering committee of individuals representing public agencies and private sector companies, is developing this data specification for curb usage. The CDS will encompass digitized curb regulations, real time and historic event information, and utilization metrics. The specification will allow sharing of this data between cities, commercial companies, and the public. Get involoved by siging up to the [Curb Mailing List](https://groups.google.com/a/openmobilityfoundation.org/g/wg-curb). +The OMF’s [Curb Management Working Group](https://github.com/openmobilityfoundation/curb-data-specification/wiki), led by a steering committee of individuals representing public agencies and private sector companies, is developing this data specification for curb usage. The CDS will encompass digitized curb regulations, real time and historic event information, and utilization metrics. The specification will allow sharing of this data between cities, commercial companies, and the public. Get involved by siging up to the [Curb Mailing List](https://groups.google.com/a/openmobilityfoundation.org/g/wg-curb). The Curb Data Specification is an open source project with all development taking place on GitHub. Read our **[Community Wiki](https://github.com/openmobilityfoundation/curb-data-specification/wiki)** to get started. Comments and ideas can be shared by [starting a discussion](https://github.com/openmobilityfoundation/curb-data-specification/discussions), [creating an issue](https://github.com/openmobilityfoundation/curb-data-specification/issues), and specific changes can be suggested by [opening a pull request](https://github.com/openmobilityfoundation/curb-data-specification/pulls). Before contributing, please review our OMF [CONTRIBUTING page](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) and our [CODE OF CONDUCT page](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md) to understand guidelines and policies for participation. From f41aec6ecc59b83e06083c3722736bc51ffe71ce Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 21:53:09 -0500 Subject: [PATCH 055/173] Create pull_request_template.md --- .github/pull_request_template.md | 41 ++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..6dfeffe8 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,41 @@ +--- +name: Default +about: Suggest changes to CDS +title: + +--- + +# CDS Pull Request + +Thank you for your contribution! Please review our OMF [contributing page](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) to understand guidelines and policies for participation, and our [Code of Conduct page](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md). + +To avoid complications and help make the Review process as smooth as possible, make sure to: + +1. Target [**`dev`**](https://github.com/openmobilityfoundation/curb-data-specification/tree/dev) branch. Please ensure you are targeting **`dev`**, not **`main`**. +1. Keep the *"Allow edits from maintainers"* button checked to help us resolve some issues for you. +1. Be ready to resolve any merge conflicts before we approve your Pull Request. +1. Have an up to date profile, per our Github [community profile](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md#community-profile) guildance. + +## Explain pull request + +Please provide a clear and concise reason for this pull request and the impact of the change + +## Is this a breaking change + +A breaking change would require consumers or implementors of the API to modify their code for it to continue to function (ex: renaming of a required field or the change in data type of an existing field). A non-breaking change would allow existing code to continue to function (ex: addition of an optional field or the creation of a new optional endpoint). + +* Yes, breaking +* No, not breaking +* I'm not sure + +## Impacted Spec + +Which API(s) will this pull request impact? + +* `Curbs` +* `Events` +* `Metrics` + +## Additional context + +Add any other context or screenshots about the feature request here. From e09dbcc31f64182eb614ced248eff90766084c48 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 21:54:47 -0500 Subject: [PATCH 056/173] Create feature-request.md --- .github/ISSUE_TEMPLATE/feature-request.md | 40 +++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/feature-request.md diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md new file mode 100644 index 00000000..30801d77 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -0,0 +1,40 @@ +--- +name: Feature request / proposal +about: Suggest an idea for this project +title: '' +labels: '' +assignees: '' + +--- + +### Is your feature request related to a problem? Please describe. + +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +### Describe the solution you'd like + +A clear and concise description of what you want to happen. + +### Is this a breaking change + +A breaking change would require consumers or implementors of an API to modify their code for it to continue to function (ex: renaming of a required field or the change in data type of an existing field). A non-breaking change would allow existing code to continue to function (ex: addition of an optional field or the creation of a new optional endpoint). + + * Yes, breaking + * No, not breaking + * I'm not sure + +### Impacted Spec + +For which spec is this feature being requested? + + * `Curbs` + * `Events` + * `Metrics` + +### Describe alternatives you've considered + +A clear and concise description of any alternative solutions or features you've considered. + +### Additional context + +Add any other context or screenshots about the feature request here. From 1bac461f6acd18cc529bce2d2d52a0f653b8aa03 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 21:57:29 -0500 Subject: [PATCH 057/173] Create add-provider-id.md --- .github/ISSUE_TEMPLATE/add-provider-id.md | 24 +++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/add-provider-id.md diff --git a/.github/ISSUE_TEMPLATE/add-provider-id.md b/.github/ISSUE_TEMPLATE/add-provider-id.md new file mode 100644 index 00000000..12aadba3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/add-provider-id.md @@ -0,0 +1,24 @@ +--- +name: Add Provider ID +about: Create Provider ID for use in CDS +title: 'Add Provider ID: [Provider Name]' +labels: admin,identifier change +assignees: '' + +--- + +**Note:** See the [Adding a CDS Provider ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Provider-ID) page for more help. + +Opening this issue will allow you as a mobility service provider get an official provider ID for use across CDS globally. + +**Fields needed from you for the [providers.csv file](https://github.com/openmobilityfoundation/curb -data-specification/blob/main/providers.csv).** + +_All fields are required._ + +1. **provider_name** - Short name of your company. + - ... +1. **provider_id** - A random UUID version 4. There are lots of way to generate a unique UUID, like using this [website](https://www.uuidgenerator.net/version4). + - ... +1. **url** - URL to the home page of your company. + +Additionally, please provide your name and role within your agency to help with verification. From d99afe9b9daa143f864e1a67f0e7534f352c7a83 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Dec 2021 21:58:28 -0500 Subject: [PATCH 058/173] Update CODEOWNERS --- CODEOWNERS | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/CODEOWNERS b/CODEOWNERS index fafbc932..4457a92b 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1,4 +1,7 @@ -## Below is the MDS CODEOWNERS file, which dictates who is required for review on any given file. +## Below is the CDS CODEOWNERS file, which dictates who is required for review on any given file. -## All MDS approvals +## All CDS approvals * @openmobilityfoundation/omf-admin + +## CDS Working Group +* @openmobilityfoundation/cds-maintainers @openmobilityfoundation/omf-admin From 73805a62b657b7cb617daf001b2f1b036516d78c Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 21 Dec 2021 11:04:38 -0500 Subject: [PATCH 059/173] Reworked field names for Event Object Per discussions at https://github.com/openmobilityfoundation/curb-data-specification/discussions/42 --- events/README.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/events/README.md b/events/README.md index b7077ace..ce45ad68 100644 --- a/events/README.md +++ b/events/README.md @@ -101,26 +101,28 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | ------ | ------ | ------------------- | ------------- | | `event_id` | [UUID][uuid] | Required | The globally unique identifier of the event that occurred. | | `event_type` | [Event Type](#event-type) | Required | The event_type that happened for this event. | -| `source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | -| `source_operator_id` | [UUID][uuid] | Required | Unique identifier of the entity responsible for operating the event source. This can be generated outside of CDS beforehand for each source operator. Different than `provider_id`. | -| `source_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as the external `vehicle_id`. | -| `provider_id` | [UUID][uuid] | Optional | Unique ID of the provider/operator/company responsible for operating the vehicle at the time of the event, if any. IDs are global and come from the [providers.csv](/providers.csv) file here in the CDS repo. Read our [How to Get a Provider ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Provider-ID) guide. An agency at their discretion may allow a small, local company to simply provide a consistent `provider_name` string instead of a `provider_id` from the global `providers.csv` file. | -| `provider_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `provider_id` or on its own. | -| `sensor_id` | [UUID][uuid] | Optional | If a sensor was used, the globally unique identifier of the sensor that recorded the event. Not needed if data is coming from a provider directly. | -| `sensor_status` | Object | Optional | The status of the sensor that reported the event at the time that the event was reported. _is_commissioned_: Boolean, required. Indicates whether the sensor is currently in a state where it should be reporting data. _is_online_: Boolean, required. Indicates whether the sensor is currently online and reporting data. | +| `event_purpose` | [Event Purpose](#event-purpose) | Conditionally Required | General curb usage purpose that the vehicle performed during the event. Required for sources capable of determining activity type for relevant event_types. | | `event_location` | GeoJSON | Required | The geographic point location where the event occurred. | | `event_time` | [Timestamp][ts] | Required | Time at which the event occurred. | -| `publication_time` | [Timestamp][ts] | Required | Time at which the event became available for consumption by this API. | +| `event_publication_time` | [Timestamp][ts] | Required | Time at which the event became available for consumption by this API. | | `curb_zone_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Zone where the event occurred. Required for events that occurred at a known Curb Zone for ALL _event_types_. | | `curb_area_ids` | [UUID][uuid] | Conditionally Required | Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area for these event_types: _enter_area, exit_area, park_start, park_end_ | | `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space for these event_types: _park_start, park_end, enter_area, exit_area_ | -| `vehicle_id` | String | Optional | A vehicle identifier visible on the vehicle itself. | -| `license_plate` | String | Optional | The consistently placed vehicle license plate, usable by ALPR systems, when required for curb use. This field is potentially sensitive (depending on local, state, and national laws) and a data privacy framework is recommended for collecting, retention, deletion, obfuscation, and security. | +| `data_source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | +| `data_source_operator_id` | [UUID][uuid] | Conditionally Required | Unique identifier of the entity responsible for operating the event data source. IDs can identify the fleet operator sending a data feed, the organization (company or city) operating the sensor. IDs for fleet operators are required and global and come from the [providers.csv](/providers.csv) file, and optional for others. Read our [How to Get a Provider ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Provider-ID) guide. An agency at their discretion may allow a small, local company to simply provide a consistent `data_source_operator_name` string instead of this field. | +| `data_source_operator_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `data_source_operator_id` or on its own for small operators at the discresion of the city. | +| `data_source_device_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as the external `vehicle_id`. | +| `data_source_manufacturer` | String | Optional | Manufacturer of the data source hardware or vehicle reporting event data. | +| `data_source_model` | String | Optional | Model of the data source hardware or vehicle reporting event data. | +| `sensor_status_is_commissioned` | Boolean | Optional | If a sensor was used to capture this event, the commissioned status at the time that the event was reported. Indicates whether the sensor is currently in a state where it should be reporting data. | +| `sensor_status_is_online` | Boolean | Optional | If a sensor was used to capture this event, the online status at the time that the event was reported. Indicates whether the sensor is currently online and reporting data. | +| `vehicle_id` | String | Optional | A vehicle identifier visible externally on the vehicle itself. | +| `vehicle_license_plate` | String | Optional | The consistently placed vehicle license plate, usable by ALPR systems, when required for curb use. This field is potentially sensitive (depending on local, state, and national laws) and a data privacy framework is recommended for collecting, retention, deletion, obfuscation, and security. | +| `vehicle_permit_number` | String | Optional | If applicable, the assigned permit number for this vehicle from the city agency. | | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | | `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | -| `propulsion_types` | Array of [Propulsion Type](#propulsion-type) | Conditionally Required | List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type. | -| `event_purpose` | [Event Purpose](#event-purpose) | Conditionally Required | General curb usage purpose that the vehicle performed during the event. Required for sources capable of determining activity type for relevant event_types. | -| `blocked_lane_types` | Array of [Lane Type](#lane-type) | Conditionally Required | Type(s) of lane blocked by the vehicle performing the event. If no lanes are blocked by the vehicle performing the event, the array should be empty. Required for the following event_types: _park_start_ | +| `vehicle_propulsion_types` | Array of [Propulsion Type](#propulsion-type) | Conditionally Required | List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type. | +| `vehicle_blocked_lane_types` | Array of [Lane Type](#lane-type) | Conditionally Required | Type(s) of lane blocked by the vehicle performing the event. If no lanes are blocked by the vehicle performing the event, the array should be empty. Required for the following event_types: _park_start_ | | `curb_occupants` | Array of [Curb Occupant](#curb-occupants) | Conditionally Required | Current occupants of the Curb Zone. If the sensor is capable of identifying the linear location of the vehicle, then elements are sorted in ascending order according to the start property of the linear reference. Otherwise, elements appear in no particular order. Required for the following event_types: _park_start, park_end, scheduled_report_ | | `currency` | String | Optional | Fields specifying a monetary cost use a currency as specified in ISO 4217. All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of 100 (for 100 cents). If the currency field is null, USD cents is implied. | | `actual_cost` | Integer | Optional | If available from the source, the actual cost, in the currency defined in currency, paid by the curb user for this event. | From 7a84e9b79936576aaa75da4dacc52a8620e982e4 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 21 Dec 2021 11:12:00 -0500 Subject: [PATCH 060/173] Type in word --- events/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index ce45ad68..91f17a4c 100644 --- a/events/README.md +++ b/events/README.md @@ -110,7 +110,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space for these event_types: _park_start, park_end, enter_area, exit_area_ | | `data_source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | | `data_source_operator_id` | [UUID][uuid] | Conditionally Required | Unique identifier of the entity responsible for operating the event data source. IDs can identify the fleet operator sending a data feed, the organization (company or city) operating the sensor. IDs for fleet operators are required and global and come from the [providers.csv](/providers.csv) file, and optional for others. Read our [How to Get a Provider ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Provider-ID) guide. An agency at their discretion may allow a small, local company to simply provide a consistent `data_source_operator_name` string instead of this field. | -| `data_source_operator_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `data_source_operator_id` or on its own for small operators at the discresion of the city. | +| `data_source_operator_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `data_source_operator_id` or on its own for small operators at the discretion of the city. | | `data_source_device_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as the external `vehicle_id`. | | `data_source_manufacturer` | String | Optional | Manufacturer of the data source hardware or vehicle reporting event data. | | `data_source_model` | String | Optional | Model of the data source hardware or vehicle reporting event data. | From d08ab5a264c6bfbb69f6dca9292e808336ddcafd Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 21 Dec 2021 11:37:38 -0500 Subject: [PATCH 061/173] Renamed Curb Status fields --- events/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/events/README.md b/events/README.md index 91f17a4c..39aea979 100644 --- a/events/README.md +++ b/events/README.md @@ -260,17 +260,17 @@ General purpose that the vehicle performed during its event, discernible by obse ## Status -The Curb Status is the current status of a curb monitoring source. +The Curb Status is the current status of sensors that are monitoring curb places. -A Curb Status is represented as a JSON object array of all deployed sources and/or sensors, whose fields are as follows: +A Curb Status is represented as a JSON object array of all deployed sensors, whose fields are as follows: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `sensor_id` | [UUID][uuid] | Required | If a sensor was used, the globally unique identifier of the sensor that records events. | -| `sensor_status` | Object | Required | The status of the sensor that reported the event at the time that the event was reported. _is_commissioned_: Boolean, required. Indicates whether the sensor is currently in a state where it should be reporting data. _is_online_: Boolean, required. Indicates whether the sensor is currently online and reporting data. | -| `event_source_category` | Enum [Sensor Category](#sensor-category) | Optional | General category of the source creating the event. | -| `source_operator_id` | [UUID][uuid] | Optional | Unique identifier of the entity responsible for operating the event source. | -| `source_id` | [UUID][uuid] | Optional | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded. | +| `data_source_device_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. | +| `data_source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | +| `data_source_operator_id` | [UUID][uuid] | Conditionally Required | Unique identifier of the entity responsible for operating the event data source. Can be global from [providers.csv](/providers.csv) or defined per city. | +| `sensor_status_is_commissioned` | Boolean | Optional | If a sensor was used to capture this event, the commissioned status at the time that the event was reported. Indicates whether the sensor is currently in a state where it should be reporting data. | +| `sensor_status_is_online` | Boolean | Optional | If a sensor was used to capture this event, the online status at the time that the event was reported. Indicates whether the sensor is currently online and reporting data. | [Top][toc] From 5ab0dd2d37322d39a2cd650ea1484b4220ff4094 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 21 Dec 2021 16:00:41 -0500 Subject: [PATCH 062/173] Updated start/end dates in Time Span --- curbs/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index f80df2d9..95d661ee 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -454,8 +454,8 @@ A Time Span is represented as a JSON object whose fields are as follows: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `from` | [Timestamp][ts] | Optional | The earliest point in time that this Time Span could apply. If unspecified, the Time Span applies to all matching periods arbitrarily far in the past. | -| `to` | [Timestamp][ts] | Optional | The latest point in time that this Time Span could apply. If unspecified, the Time Span applies to all matching periods arbitrarily far in the future. | +| `start_date` | [Timestamp][ts] | Optional | The earliest point in time that this Time Span could apply. If unspecified, the Time Span applies to all matching periods arbitrarily far in the past. See note below for more details. | +| `end_date` | [Timestamp][ts] | Optional | The latest point in time that this Time Span could apply. If unspecified, the Time Span applies to all matching periods arbitrarily far in the future. See note below for more details. | | `days_of_week` | Array of strings | Optional | An array of days of the week when this Time Span applies, specified as 3-character strings (`"sun"`, `"mon"`, `"tue"`, `"wed"`, `"thu"`, `"fri"`, `"sat"`). | | `days_of_month` | Array of integers | Optional | An array of days of the month when this Time Span applies, specified as integers (1-31). Note that, in order to specify, e.g., the "2nd Monday of the month", you can use `days_of_month` combined with `days_of_week` (in this example, `days_of_week = ["mon"]` and `days_of_month = [8,9,10,11,12,13,14]`). | | `months` | Array of integers | Optional | If specified, this Time Span applies only during these months (1=January, 12=December). | @@ -464,6 +464,8 @@ A Time Span is represented as a JSON object whose fields are as follows: | `designated_period` | String | Optional | A string representing an arbitrarily-named, externally-defined period of time. Any values MAY be specified but the following known values SHOULD be used when possible:
        • `snow emergency`
        • `holidays`
        • `school days`
        • `game days`
        | | `designated_period_except` | `Boolean` | `Optional` | If specified and `true`, this Time Span applies at all times not matching the named designated period. (e.g., if `designated_period` is `snow emergency` and `designated_period_except` is `true`, this Time Span does not apply on snow days). | +**Note about `start_date` and `end_date` in _Time Span_:** these fields are optional but useful for defining policies that will be used once and won't be reused later, like around a specific, temporary event. If used, they are only applicable in any connected Curb Zone during their overlapping time frames. + [Top][toc] ### Rate From 352d190047633e3b1a7dc8096917a9fc5c22893a Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 21 Dec 2021 16:28:56 -0500 Subject: [PATCH 063/173] Create examples.md --- curbs/examples.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 curbs/examples.md diff --git a/curbs/examples.md b/curbs/examples.md new file mode 100644 index 00000000..decc4f61 --- /dev/null +++ b/curbs/examples.md @@ -0,0 +1 @@ +JSON examples for Curbs endpoint query results will go here and get linked to in the spec. From 20a2b5100a4838e8c15e9e4c326ddb8c58abfb56 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 12:02:30 -0500 Subject: [PATCH 064/173] Renamed data_source_operators --- curbs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/curbs/README.md b/curbs/README.md index 95d661ee..cff2c2f4 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -343,7 +343,7 @@ A Policy is represented as a JSON object whose fields are as follows: | `priority` | Integer | Required | Specifies which other policies this one takes precedence over. If two Policies on the same Curb Zone have overlapping [Time Spans](#time-span) and apply to the same user class, the one that applies at a given time is the one with the **lowest** priority. E.g., a priority of `1` takes precedence over a priority of `3`. Two Policies that apply to the same Curb Zone with overlapping Time Spans and user classes MUST NOT have the same priority. | | `rules` | Array of [Rules](#rule) | Required | The rule(s) that this policy applies. If a Policy specifies multiple rules, each rule MUST specify disjoint lists of user classes. | | `time_spans` | Array of [Time Spans](#time-span) | Optional | If specified, this regulation only applies at the times defined within. | -| `provider_ids` | Array of [UUIDs][uuid] | Optional | An array of provider IDs that this policy only applies to. IDs come from [providers.csv](/providers.csv) file here in the CDS repo. Read our [How to Get a Provider ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Provider-ID) guide. | +| `data_source_operator_id` | Array of [UUIDs][uuid] | Optional | An array of Data Source Operator IDs that this policy only applies to. IDs come from [data_source_operators.csv](/data_source_operators.csv) file here in the CDS repo. Read our [How to Get a Data Source Operator ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Data-Source-Operator-ID) guide. | [Top][toc] From 9869b8e8fb0dc4deeeaaaf131c87da8878d62d34 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 12:04:33 -0500 Subject: [PATCH 065/173] Updated data_source_operators name --- events/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/events/README.md b/events/README.md index 39aea979..7932c1a6 100644 --- a/events/README.md +++ b/events/README.md @@ -109,7 +109,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `curb_area_ids` | [UUID][uuid] | Conditionally Required | Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area for these event_types: _enter_area, exit_area, park_start, park_end_ | | `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space for these event_types: _park_start, park_end, enter_area, exit_area_ | | `data_source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | -| `data_source_operator_id` | [UUID][uuid] | Conditionally Required | Unique identifier of the entity responsible for operating the event data source. IDs can identify the fleet operator sending a data feed, the organization (company or city) operating the sensor. IDs for fleet operators are required and global and come from the [providers.csv](/providers.csv) file, and optional for others. Read our [How to Get a Provider ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Provider-ID) guide. An agency at their discretion may allow a small, local company to simply provide a consistent `data_source_operator_name` string instead of this field. | +| `data_source_operator_id` | [UUID][uuid] | Conditionally Required | Unique identifier of the entity responsible for operating the event data source. IDs can identify the fleet operator sending a data feed, or the organization (company or city) operating the sensor. IDs for fleet operators are required and global and come from the [data_source_operators.csv](/data_source_operators.csv) file, and optional for others. Read our [How to Get a Data Source Operator ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Data-Source-Operator-ID) guide. An agency at their discretion may allow a small, local company to simply provide a consistent `data_source_operator_name` string instead of this field. | | `data_source_operator_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `data_source_operator_id` or on its own for small operators at the discretion of the city. | | `data_source_device_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as the external `vehicle_id`. | | `data_source_manufacturer` | String | Optional | Manufacturer of the data source hardware or vehicle reporting event data. | @@ -268,7 +268,7 @@ A Curb Status is represented as a JSON object array of all deployed sensors, who | ------ | ------ | ------------------- | ------------- | | `data_source_device_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. | | `data_source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | -| `data_source_operator_id` | [UUID][uuid] | Conditionally Required | Unique identifier of the entity responsible for operating the event data source. Can be global from [providers.csv](/providers.csv) or defined per city. | +| `data_source_operator_id` | [UUID][uuid] | Conditionally Required | Unique identifier of the entity responsible for operating the event data source. Can be global from [data_source_operators.csv](/data_source_operators.csv) or defined per city. | | `sensor_status_is_commissioned` | Boolean | Optional | If a sensor was used to capture this event, the commissioned status at the time that the event was reported. Indicates whether the sensor is currently in a state where it should be reporting data. | | `sensor_status_is_online` | Boolean | Optional | If a sensor was used to capture this event, the online status at the time that the event was reported. Indicates whether the sensor is currently online and reporting data. | From 1d805ed9fe1793b6e2cf40885a43f245edb5b02c Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 12:06:00 -0500 Subject: [PATCH 066/173] Updated to data_source_operators --- data_source_operators.csv | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 data_source_operators.csv diff --git a/data_source_operators.csv b/data_source_operators.csv new file mode 100644 index 00000000..46571dae --- /dev/null +++ b/data_source_operators.csv @@ -0,0 +1,2 @@ +data_source_operator_name,data_source_operator_id,url +SAMPLE COMPANY NAME,d548b89f-a76d-45f7-9e07-c2aae304031b,https://www.companywebsitename.com From 42b65ad130ecdbf31920b67e72675150cdffc2b8 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 12:06:09 -0500 Subject: [PATCH 067/173] Delete providers.csv --- providers.csv | 2 -- 1 file changed, 2 deletions(-) delete mode 100644 providers.csv diff --git a/providers.csv b/providers.csv deleted file mode 100644 index 35e33cad..00000000 --- a/providers.csv +++ /dev/null @@ -1,2 +0,0 @@ -provider_name,provider_id,url -SAMPLE COMPANY NAME,d548b89f-a76d-45f7-9e07-c2aae304031b,https://www.companywebsitename.com From 550772379207139030b96297f40c04f0562be90b Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 12:44:58 -0500 Subject: [PATCH 068/173] Changed per_hour to rate_units instead --- curbs/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/curbs/README.md b/curbs/README.md index cff2c2f4..94b4c3cc 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -474,7 +474,8 @@ A Rate defines the amount a user of the curb needs to pay when a given rule appl | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `per_hour` | Integer | Required | The rate per hour for this space in the smallest denomination of local currency. | +| `rate` | Integer | Required | The rate for this space in cents (or the smallest denomination of local currency) per `rate_unit`. | +| `rate_unit` | Enum | Required | The unit of time associated with the rate. One of "second", "minute", "hour", "day", "week", "month", "year". | | `increment_minutes` | Integer | Optional | If specified, this is the smallest amount of time a user can pay for (e.g., if `increment_minutes` is `15`, a user can pay for 15, 30, 45, etc. minutes). | | `increment_amount` | Integer | Optional | If specified, the rate for this space is rounded up to the nearest increment of this amount, specified in the same units as `per_hour`. | | `start_minutes` | Integer | Optional | The amount of time the vehicle must have already been present in the Curb Zone before this rate starts applying. If not specified, this rate starts when the vehicle arrives. | From 83d12f6afb66b40f428c4ce7fb93702dbee1f79f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 13:29:03 -0500 Subject: [PATCH 069/173] Updated release candidate language --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a45858a3..43e970dd 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Curb Data Specification -## Beta -> ⚠ **This repository is current a draft of the initial CDS beta, and not an official release. It will be changed and updated as development and real-world feedback happens and we head for a 1.0 beta release. See our current [timeline](https://github.com/openmobilityfoundation/curb-data-specification/wiki#timeline) and watch the [CDS Releases](https://github.com/openmobilityfoundation/curb-data-specification/releases) page for updates.** +## Release Candidate +> ⚠ **This repository is a release candidate for CDS 1.0. It has been approved by the [Working Group Steering Committee](https://github.com/openmobilityfoundation/curb-data-specification/wiki). You may start to use it in your development and production environments for real world use cases. The release is going through the final [OMF approval process](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md#approval-by-the-open-mobility-foundation), where it may be tweaked or enhanced with more guidance and resourse. See the [Release Plan](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Release-1.0.0) page for updates.** ## Table of Contents From 8c2745b738742de34c2643afd0212c1e44f9ec8e Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 13:29:53 -0500 Subject: [PATCH 070/173] Remove beta language in Curbs --- curbs/README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 94b4c3cc..ef0d99ef 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -7,9 +7,6 @@ Curbs API can be connected to event and metrics data, and can be shared with com purposes such as routing, finding legal parking, loading, and pick-up/drop-off spots, or analyzing curb utilization over time. -## ⚠ Beta -> **This feature is current a draft of the initial CDS beta. It will be change as development and real-world feedback happens.** - # Endpoints There are four different endpoints that are part of the Curbs API: From 032d593208a02dca9799d5c12387635591dfecd8 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 13:30:12 -0500 Subject: [PATCH 071/173] Remove beta language in Events --- events/README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/events/README.md b/events/README.md index 7932c1a6..9ccb9fd2 100644 --- a/events/README.md +++ b/events/README.md @@ -2,9 +2,6 @@ The Events API is a REST API allowing real-time and historic events at the curb to be sent to cities, and the ability to check on the status of any sensors. Events can come from company data feeds, sensors, payments, check-ins, enforcement, and/or other city data sources. Data sent in the Events API can be connected to the Curbs API over time and space, and events are used for calculations in the Metrics API. -## ⚠ Beta -> **This feature is current a draft of the initial CDS beta release. It will change as development and real-world feedback happens.** - # Endpoints There are two different endpoints that are part of the Events API: From 5b85b39b1d96c109ef3ce9b8266cb660c1034b77 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 13:30:32 -0500 Subject: [PATCH 072/173] Remove beta language in Metrics --- metrics/README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index cd9c1804..6ff5d309 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -2,9 +2,6 @@ The Metrics API is a REST API allowing historic metrics calculations based on Event activity that happened at defined Curb places. -## ⚠ Beta -> **This feature is current a draft of the initial CDS beta release. It will change as development and real-world feedback happens.** - # Endpoints There are two different endpoints that are part of the Metrics API: From 1aa53160417cacd76605b4bc4ed171d2378d38ac Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 13:31:30 -0500 Subject: [PATCH 073/173] Remove beta language in General Info --- general-information.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/general-information.md b/general-information.md index 6a5b1a86..661fa2d6 100644 --- a/general-information.md +++ b/general-information.md @@ -21,8 +21,6 @@ Beta features may be suitable for enabling some new tools and analysis, but may Working Groups and their Steering Committees are expected to review beta designated features and feedback with each release cycle and determine whether the feature has reached the level of stability and maturity needed to remove the beta designation. In a case where a beta feature fails to reach substantial adoption after an extended time, Working Group Steering Committees should discuss whether or not the feature should remain in the specification. -> **This CDS repository is currently wholly in the beta state. It will be change as development and real-world feedback happens. See our current [timeline](https://github.com/openmobilityfoundation/curb-data-specification/wiki#timeline) and watch the [CDS Releases](https://github.com/openmobilityfoundation/curb-data-specification/releases) page for updates.** - [Top][toc] # Costs and currencies From 4a881fba2bf1d07bd3107a8896f48155f6446542 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 13:37:18 -0500 Subject: [PATCH 074/173] Improved versions section --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 43e970dd..06b59397 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,9 @@ For questions about CDS please contact by email at [info@openmobilityfoundation. # Versions -CDS has a **current release**, and an **upcoming releases** in development. For a full list of releases, their status, recommended versions, and timelines, see the [Official CDS Releases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Releases) page. +CDS has a **current release** (version 1.0.0), and an **upcoming releases** in development. For a full list of releases, their status, recommended versions, and timelines, see the [Official CDS Releases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Releases) page. + +The OMF provides guidance on upgrading for cities, providers, and software companies, and sample permit language for cities. See our [CDS Version Guidance](https://github.com/openmobilityfoundation/governance/blob/main/technical/OMF-CDS-Version-Guidance.md) for best practices on how and when to upgrade CDS as new versions become available. Our complimentary [CDS Policy Language Guidance](https://github.com/openmobilityfoundation/governance/blob/main/technical/OMF-CDS-Policy-Language-Guidance.md) document is for cities writing CDS into their operating policy and includes sample policy language. ## Technical Information @@ -84,6 +86,7 @@ The CDS specification is versioned using Git tags and [semantic versioning](http * [Development Branch](https://github.com/openmobilityfoundation/curb-data-specification/tree/dev) (dev) * [All GitHub Releases](https://github.com/openmobilityfoundation/curb-data-specification/releases) * [CDS Releases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Releases) - current/recommended versions, timeline +* [Release Guidelines](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md) [Top][toc] From 0ba02bd5d1feeab0f956407b5bd9ce0648ede07a Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 13:58:24 -0500 Subject: [PATCH 075/173] Format APIs --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 06b59397..792afda6 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Curb Data Specification ## Release Candidate -> ⚠ **This repository is a release candidate for CDS 1.0. It has been approved by the [Working Group Steering Committee](https://github.com/openmobilityfoundation/curb-data-specification/wiki). You may start to use it in your development and production environments for real world use cases. The release is going through the final [OMF approval process](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md#approval-by-the-open-mobility-foundation), where it may be tweaked or enhanced with more guidance and resourse. See the [Release Plan](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Release-1.0.0) page for updates.** +> ⚠ **This repository is a release candidate for CDS 1.0. It has been approved by the [Working Group Steering Committee](https://github.com/openmobilityfoundation/curb-data-specification/wiki). You may start to use it in your development and production environments for real world use cases. The release is going through the final [OMF approval process](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md#approval-by-the-open-mobility-foundation), where it may be tweaked or enhanced with more guidance and resources. See the [Release Plan](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Release-1.0.0) page for updates.** ## Table of Contents @@ -30,9 +30,11 @@ Urban curb is a valuable, limited, and often under-managed part of the public ri CDS is at its core a set of Application Programming Interfaces (APIs) and endpoints within those APIs, which allow information to flow between organizations managing and using curb places. It includes the following APIs and their associated endpoints: -1. **[Curbs API](/curbs)** - communicate curb locations and policies publicly -1. **[Events API](/events)** - capture activity at Curbs from sensors and curb users -1. **[Metrics API](/metrics)** - methodology and metrics to understand Events at Curbs +| API | Description | +|---|---| +| **[Curbs](/curbs)** | communicate curb locations and policies publicly | +| **[Events](/events)** | capture activity at Curbs from sensors and curb users | +| **[Metrics](/metrics)** | methodology and metrics to understand Events at Curbs | CDS is a data exchange format and a translation layer between internal systems and external entities using data feeds. It is not expected that CDS will be the format used internally to store curb regulations in a city. The internal storage format is something different, and a subset of that data should be able to be converted to CDS for publishing out to the public and curb users. From 607e8d1544fbf7f2c930f06ce5f0ef0a2ba1eac2 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 15:49:51 -0500 Subject: [PATCH 076/173] First Curbs example --- curbs/examples.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-) diff --git a/curbs/examples.md b/curbs/examples.md index decc4f61..b299d610 100644 --- a/curbs/examples.md +++ b/curbs/examples.md @@ -1 +1,68 @@ -JSON examples for Curbs endpoint query results will go here and get linked to in the spec. +# Curbs Examples + +This file presents a series of CDS [Curbs](/curbs) endpoint examples to use as templates. + +## Table of Contents + +- [Curb Zones Minimum](#curb-zones-minimum) + +## Curb Zones Minimum + +A [Query Curb Zones](https://github.com/openmobilityfoundation/curb-data-specification/tree/feature-release-work-1/curbs#query-curb-zones) example at `/curbs/zone` with minimum required fields returned, plus a max parking stay of 60 minutes, and some parameters passed in. + +**Query**: + +`/curbs/zone?include_geometry=true&include_policies=true×tamp=1552678594427` + +**Payload**: + +```json +{ + "version": "39a653be-7180-4188-b1a6-cae33c280343", + "time_zone": "US/Eastern", + "last_updated": 1552678594428, + "currency": "USD", + "author": "City of Metropolis", + "license_url": "https://creativecommons.org/licenses/by/4.0/", + "data": [ + { + "zones": [ + { + "curb_zone_id": "7d8a5885-e949-4ac9-afb7-fa4d43b68530", + "geometry": { + "type": "Polygon", + "coordinates": [[ + [-73.982105, 40.767932], + [-73.973694, 40.764551], + [-73.949318, 40.796918], + [-73.958416, 40.800686], + [-73.982105, 40.767932] + ]] + }, + "curb_policy_ids": [ + "cd0996d7-3765-4f0b-a72e-7caf7cf3fe21" + ], + "published_date": 1552678594428, + "last_updated_date": 1552678594428, + "start_date": 1552678594428 + } + ], + "policies": [ + { + "curb_policy_id": "cd0996d7-3765-4f0b-a72e-7caf7cf3fe21", + "published_date": 1552678594428, + "priority": 1, + "rules": [ + { + "activity": "parking", + "max_stay": 60 + } + ] + } + ] + } + ] +} +``` + +[Top](#table-of-contents) From b6a3964406626efe00ffe158622603c2c0257211 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 15:56:22 -0500 Subject: [PATCH 077/173] Added link to examples page --- curbs/README.md | 44 +++++++++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index ef0d99ef..ccdb6b5b 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -25,27 +25,27 @@ There are four different endpoints that are part of the Curbs API: # Table of Contents - - [REST Endpoints](#rest-endpoints) - * [Query Curb Zones](#query-curb-zones) - * [Query Curb Areas](#query-curb-areas) - * [Query Curb Spaces](#query-curb-spaces) - * [Query Curb Policies](#query-curb-policies) - * [Fetch a Curb Zone](#fetch-a-curb-zone) - * [Fetch a Curb Area](#fetch-a-curb-area) - * [Fetch a Curb Space](#fetch-a-curb-space) - * [Fetch a Curb Policy](#fetch-a-curb-policy) + - [Query Curb Zones](#query-curb-zones) + - [Query Curb Areas](#query-curb-areas) + - [Query Curb Spaces](#query-curb-spaces) + - [Query Curb Policies](#query-curb-policies) + - [Fetch a Curb Zone](#fetch-a-curb-zone) + - [Fetch a Curb Area](#fetch-a-curb-area) + - [Fetch a Curb Space](#fetch-a-curb-space) + - [Fetch a Curb Policy](#fetch-a-curb-policy) - [Data Objects](#data-objects) - * [Curb Zone](#curb-zone) - * [Curb Area](#curb-area) - * [Curb Space](#curb-space) - * [Policy](#policy) - * [Rule](#rule) - * [Activities](#activities) - * [User Classes](#user-classes) - * [Time Span](#time-span) - * [Rate](#rate) - * [Location Reference](#location-reference) + - [Curb Zone](#curb-zone) + - [Curb Area](#curb-area) + - [Curb Space](#curb-space) + - [Policy](#policy) + - [Rule](#rule) + - [Activities](#activities) + - [User Classes](#user-classes) + - [Time Span](#time-span) + - [Rate](#rate) + - [Location Reference](#location-reference) +- [Examples](#examples) # REST Endpoints @@ -508,6 +508,12 @@ A Previous Policy is a JSON object with the following fields: | `start_date` | [Timestamp][ts] | Required | The date/time that this policy started being active for this curb location. | | `end_date` | [Timestamp][ts] | Required | The date/time that this policy ended being active for this curb location. | +[Top][toc] + +# Examples + +See a series of [CDS Curbs endpoint examples](examples.md) to use as templates. + [Top][toc] [toc]: #table-of-contents From 807aa9985ba8d1ac0fc254a80accf95ed9c4b3c2 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 16:00:02 -0500 Subject: [PATCH 078/173] Add link to home page --- curbs/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/curbs/README.md b/curbs/README.md index ccdb6b5b..75f078f2 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -7,6 +7,8 @@ Curbs API can be connected to event and metrics data, and can be shared with com purposes such as routing, finding legal parking, loading, and pick-up/drop-off spots, or analyzing curb utilization over time. +**See [other CDS APIs](/) on the homepage.** + # Endpoints There are four different endpoints that are part of the Curbs API: From bed5f70ac9ab223c4dcba1435df2dec8f87086ab Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 16:00:30 -0500 Subject: [PATCH 079/173] Add link to home page --- events/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/events/README.md b/events/README.md index 9ccb9fd2..4c8c7932 100644 --- a/events/README.md +++ b/events/README.md @@ -2,6 +2,8 @@ The Events API is a REST API allowing real-time and historic events at the curb to be sent to cities, and the ability to check on the status of any sensors. Events can come from company data feeds, sensors, payments, check-ins, enforcement, and/or other city data sources. Data sent in the Events API can be connected to the Curbs API over time and space, and events are used for calculations in the Metrics API. +**See [other CDS APIs](/) on the homepage.** + # Endpoints There are two different endpoints that are part of the Events API: From 7d7195b29e648a2422c85a3102ce9564fccd3056 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 3 Jan 2022 16:00:47 -0500 Subject: [PATCH 080/173] Added link to home page --- metrics/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/metrics/README.md b/metrics/README.md index 6ff5d309..cd45d43d 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -2,6 +2,8 @@ The Metrics API is a REST API allowing historic metrics calculations based on Event activity that happened at defined Curb places. +**See [other CDS APIs](/) on the homepage.** + # Endpoints There are two different endpoints that are part of the Metrics API: From e02066d3cefe10222ac515788ed964b6d12c572a Mon Sep 17 00:00:00 2001 From: zaneclark Date: Tue, 4 Jan 2022 12:39:44 -0700 Subject: [PATCH 081/173] docs: clarify effective minute coverage requirements --- curbs/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 75f078f2..0f5004c4 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -352,13 +352,13 @@ A rule defines who is allowed to do what, and for how long, on a curb, per the p It is a JSON object with the following fields: -| Name | Type | Required/Optional | Description | -| ------ | ------ | ------------------- | ------------- | -| `activity` | String | Required | The activity that is forbidden or permitted by this regulation. Value MUST be one of the [activities](#activities). | -| `max_stay` | Integer | Optional | The length of time (in minutes) for which the curb may be used under this regulation. | -| `no_return` | Integer | Optional | The length of time (in minutes) that a user must vacate a Curb Zone before being allowed to return for another stay. | -| `user_classes` | Array of Strings | Optional | If specified, this regulation only applies to users matching the [user classes](#user-classes) contained within. If not specified, this regulation applies to everyone. | -| `rate` | Array of [Rates](#rate) | Optional | The cost of using this Curb Zone when this regulation applies. Rates are repeated to allow for prices that change over time. For instance, a regulation may have a price of $1 for the first hour but $2 for every subsequent hour. | +| Name | Type | Required/Optional | Description | +|----------------|-------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `activity` | String | Required | The activity that is forbidden or permitted by this regulation. Value MUST be one of the [activities](#activities). | +| `max_stay` | Integer | Optional | The length of time (in minutes) for which the curb may be used under this regulation. | +| `no_return` | Integer | Optional | The length of time (in minutes) that a user must vacate a Curb Zone before being allowed to return for another stay. | +| `user_classes` | Array of Strings | Optional | If specified, this regulation only applies to users matching the [user classes](#user-classes) contained within. If not specified, this regulation applies to everyone. | +| `rate` | Array of [Rates](#rate) | Optional | The cost of using this Curb Zone when this regulation applies. Rates are repeated to allow for prices that change over time. For instance, a regulation may have a price of $1 for the first hour but $2 for every subsequent hour. The complete set of [Rates](#rate) must span from `start_minutes` = `0` or `null` to `end_minutes` = `max_stay` without overlap of effective minutes (range created by rate `start_minutes` and `end_minutes`) | [Top][toc] From 71584dc6fe88266a9521a591db6c8d0758a3167b Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 6 Jan 2022 10:37:36 -0500 Subject: [PATCH 082/173] Minor rate text update --- curbs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/curbs/README.md b/curbs/README.md index 0f5004c4..35b0ac8c 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -358,7 +358,7 @@ It is a JSON object with the following fields: | `max_stay` | Integer | Optional | The length of time (in minutes) for which the curb may be used under this regulation. | | `no_return` | Integer | Optional | The length of time (in minutes) that a user must vacate a Curb Zone before being allowed to return for another stay. | | `user_classes` | Array of Strings | Optional | If specified, this regulation only applies to users matching the [user classes](#user-classes) contained within. If not specified, this regulation applies to everyone. | -| `rate` | Array of [Rates](#rate) | Optional | The cost of using this Curb Zone when this regulation applies. Rates are repeated to allow for prices that change over time. For instance, a regulation may have a price of $1 for the first hour but $2 for every subsequent hour. The complete set of [Rates](#rate) must span from `start_minutes` = `0` or `null` to `end_minutes` = `max_stay` without overlap of effective minutes (range created by rate `start_minutes` and `end_minutes`) | +| `rate` | Array of [Rates](#rate) | Optional | The cost of using this Curb Zone when this regulation applies. Rates are repeated to allow for prices that change over time. For instance, a regulation may have a price of $1 for the first hour but $2 for every subsequent hour. The complete set of the [Rates](#rate) array must span **from** `start_minutes` = `0` or `null` **to** `end_minutes` = `max_stay` without overlap of effective minutes (i.e. the range created by rate `start_minutes` and `end_minutes`). | [Top][toc] From e4bdfc20590082739ae8df0f1ffd8d8d717115ff Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 7 Jan 2022 15:16:39 -0500 Subject: [PATCH 083/173] Updated curb policy links --- curbs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 35b0ac8c..a5ee28fc 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -139,7 +139,7 @@ All query parameters are optional. Endpoint: `/curb/policy` Method: `GET` -`data` Payload: a JSON object with a `policies` field containing an array of [Curb Policy](#curb-policy) objects. +`data` Payload: a JSON object with a `policies` field containing an array of [Curb Policy](#policy) objects. _Optional endpoint; if not implemented, the server should reply with `501 Not Implemented`._ @@ -206,7 +206,7 @@ All query parameters are optional. Endpoint: `/curb/policy/` Method: `GET` -`data` Payload: the [Curb Policy](#curb-policy) object with the ID provided in the path. +`data` Payload: the [Curb Policy](#policy) object with the ID provided in the path. ### Query Parameters From 228bde79e5735d2f0652b9c7644581de863894dc Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 7 Jan 2022 15:59:27 -0500 Subject: [PATCH 084/173] Added curb policy example --- curbs/examples.md | 85 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 83 insertions(+), 2 deletions(-) diff --git a/curbs/examples.md b/curbs/examples.md index b299d610..b7206b59 100644 --- a/curbs/examples.md +++ b/curbs/examples.md @@ -5,10 +5,11 @@ This file presents a series of CDS [Curbs](/curbs) endpoint examples to use as t ## Table of Contents - [Curb Zones Minimum](#curb-zones-minimum) +- [Curb Policies](#curb-policies) ## Curb Zones Minimum -A [Query Curb Zones](https://github.com/openmobilityfoundation/curb-data-specification/tree/feature-release-work-1/curbs#query-curb-zones) example at `/curbs/zone` with minimum required fields returned, plus a max parking stay of 60 minutes, and some parameters passed in. +A [Query Curb Zones](https://github.com/openmobilityfoundation/curb-data-specification/tree/feature-release-work-1/curbs#query-curb-zones) example of `/curbs/zone` with minimum required fields returned, plus a max parking stay of 60 minutes, and some parameters passed in. **Query**: @@ -18,7 +19,7 @@ A [Query Curb Zones](https://github.com/openmobilityfoundation/curb-data-specifi ```json { - "version": "39a653be-7180-4188-b1a6-cae33c280343", + "version": "1.0", "time_zone": "US/Eastern", "last_updated": 1552678594428, "currency": "USD", @@ -66,3 +67,83 @@ A [Query Curb Zones](https://github.com/openmobilityfoundation/curb-data-specifi ``` [Top](#table-of-contents) + +## Curb Policies + +A [Query Curb Policies](https://github.com/openmobilityfoundation/curb-data-specification/tree/feature-release-work-1/curbs#query-curb-policies) example of `/curbs/policy` showing policies giving 3 fleet operators using electric vehicles operating rideshare curb access for max 15 minute drop-offs on weekdays from 10am to 4pm, other commerical activity for up to 60 minutes between 8am and 10pm, but otherwise no stopping (eg overnight). No query parameters passed in. + +**Query**: + +`/curbs/policy` + +**Payload**: + +```json +{ + "version": "1.0", + "time_zone": "US/Eastern", + "last_updated": 1552678594428, + "currency": "USD", + "author": "City of Metropolis", + "license_url": "https://creativecommons.org/licenses/by/4.0/", + "data": [ + { + "policies": [ + { + "curb_policy_id": "cd0996d7-3765-4f0b-a72e-7caf7cf3fe21", + "published_date": 1552678594428, + "priority": 1, + "data_source_operator_id": [ + "b2046faf-2bc2-4f0e-b784-7cc746138555", + "aba63473-351c-4624-93ab-456db34f83a6", + "984cae91-3a11-49eb-b68c-d325a6cc8970" + ], + "time_spans": [ + { + "days_of_week": ["mon", "tue", "wed", "thu", "fri"], + "time_of_day_start": "10:00", + "time_of_day_end": "16:00" + } + ], + "rules": [ + { + "activity": "parking", + "max_stay": 15, + "user_classes": [ + "rideshare", "electric" + ] + } + ] + },{ + "curb_policy_id": "51f58575-1042-4254-b5fc-fed97124a6c7", + "published_date": 1552678857362, + "priority": 2, + "time_spans": [ + { + "time_of_day_start": "08:00", + "time_of_day_end": "22:00" + } + ], + "rules": [ + { + "activity": "parking", + "max_stay": 60 + } + ] + },{ + "curb_policy_id": "8c0abb35-b8d2-469e-bdb1-b6de52c430ac", + "published_date": 1552678857362, + "priority": 3, + "rules": [ + { + "activity": "no stopping" + } + ] + } + ] + } + ] +} +``` + +[Top](#table-of-contents) From 3b5e60c18f214b89593cc8191bdd9c799ea000f1 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 7 Jan 2022 16:28:41 -0500 Subject: [PATCH 085/173] Added REST Endpoints to general info --- general-information.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/general-information.md b/general-information.md index 661fa2d6..804f57f0 100644 --- a/general-information.md +++ b/general-information.md @@ -62,6 +62,27 @@ A polygon is a GeoJSON geometry of type `"Polygon"` as defined in [Top][toc] +# REST Endpoints + +All dynamic REST endpoints will return a JSON object containing the following fields: + +| Name | Type | Required/Optional | Description | +| ------ | ------ | ------------------- | ------------- | +| `data` | _Endpoint-dependent_ | Required | The requested data objects. | +| `version` | String | Required | The specification version that the API conforms to (currently, `0.0`) | +| `time_zone` | String | Required | The time zone that applies to parking regulations in this dataset. MUST be a valid [TZ database](https://www.iana.org/time-zones) time zone name (e.g. `"US/Eastern"` or `"Europe/Paris"`). | +| `last_updated` | [Timestamp][ts] | Required | The last time the data in this API was updated. | +| `currency` | String | Required | The ISO 4217 3-letter code for the currency in which rates for curb usage are denominated. | +| `author` | String | Optional | The name of the organization that produces and maintains this data. | +| `license_url` | URL | Optional | The licensing terms under which this data is provided. | + +Servers MUST set the `Content-Type` header to `application/vnd.cds+json;version=1.0` to support +versioning in the future. Clients SHOULD specify an `Accept` header containing +`application/vnd.cds+json;version=1.0`. If the server receives a request that contains an `Accept` +header but does not include this value; it MUST respond with a status of `406 Not Acceptable`. + +[Top][toc] + # UUID A UUID is a 128-bit, globally unique identifier represented as a string using the format defined in From d04e5b1c80255ef493eb691ef5e3b2d95fd81dc3 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 7 Jan 2022 16:40:24 -0500 Subject: [PATCH 086/173] Added Authorization info --- general-information.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/general-information.md b/general-information.md index 804f57f0..2f3236a5 100644 --- a/general-information.md +++ b/general-information.md @@ -5,12 +5,52 @@ This document contains specifications that are shared between the various CDS AP # Table of Contents +- [Authorization](#authorization) - [Beta Features](#beta-features) - [Costs and Currencies](#costs-and-currencies) - [Polygon](#polygon) +- [REST Endpoints](#rest-endpoints) - [UUID](#uuid) - [Timestamp](#timestamp) +# Authorization + +CDS implementers **SHALL** provide authorization for API endpoints via a bearer token based auth system, when required. + +For example, the `Authorization` header sent as part of an HTTP request: + +``` +GET /events/event HTTP/1.1 +Host: api.operator.com +Authorization: Bearer +``` + +More info on how to document [Bearer Auth in swagger](https://swagger.io/docs/specification/authentication/bearer-authentication/) + +## JSON Web Tokens + +JSON Web Token ([JWT](https://jwt.io/introduction/)) is **RECOMMENDED** as the token format. + +JWTs provide a safe, secure way to verify the identity of an agency and provide access to MDS resources without providing access to other, potentially sensitive data. + +> JSON Web Token (JWT) is an open standard ([RFC 7519](https://tools.ietf.org/html/rfc7519)) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA. + +Implementers **MAY** include any metadata in the JWT they wish that helps to route, log, permission, or debug agency requests, leaving their internal implementation flexible. + +JWT provides a helpful [debugger](https://jwt.io/#debugger) for testing your token and verifying security. + +## OAuth 2.0 + +OAuth 2.0's `client_credentials` grant type (outlined in [RFC6749](https://tools.ietf.org/html/rfc6749#section-4.4)) is **RECOMMENDED** as the authentication and authorization scheme. + +OAuth 2.0 is an industry standard authorization framework with a variety of existing tooling. The `client_credentials` grant type facilitates generation of tokens that can be used for access by agencies and distributed to data partners. + +If implementers use this auth scheme, they **MAY** choose to specify token scopes that define access parameters like allowable time ranges. These guidelines **SHOULD** be encoded into the returned token in a parseable way. + +## Endpoint Authentication Requirements + +All endpoints marked authenticated **SHALL** be authenticated, to protect potentially sensitive information. + # Beta Features In some cases, features within CDS may be marked as "beta." These are typically recently added endpoints or fields. Because beta features are new, they may not yet be fully mature and proven in real-world operation. The design of beta features may have undiscovered gaps, ambiguities, or inconsistencies. Implementations of those features are typically also quite new and are more likely to contain bugs or other flaws. Beta features are likely to evolve more rapidly than other parts of the specification. From 0387f3f29ef03f452c1384a1ee35a4c3a5d00d2d Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 7 Jan 2022 16:46:25 -0500 Subject: [PATCH 087/173] Linked to rest endpoint and auth info --- curbs/README.md | 22 +++++++--------------- 1 file changed, 7 insertions(+), 15 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index a5ee28fc..33ec6da1 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -28,6 +28,7 @@ There are four different endpoints that are part of the Curbs API: # Table of Contents - [REST Endpoints](#rest-endpoints) + - [Authorization](#authorization) - [Query Curb Zones](#query-curb-zones) - [Query Curb Areas](#query-curb-areas) - [Query Curb Spaces](#query-curb-spaces) @@ -51,22 +52,13 @@ There are four different endpoints that are part of the Curbs API: # REST Endpoints -All endpoints return a JSON object containing the following fields: +All endpoints return a JSON object containing the fields as specified in the [REST Endpoint](/general-information.md#rest-endpoints) details. -| Name | Type | Required/Optional | Description | -| ------ | ------ | ------------------- | ------------- | -| `data` | _Endpoint-dependent_ | Required | The requested data objects. | -| `version` | String | Required | The specification version that the API conforms to (currently, `0.0`) | -| `time_zone` | String | Required | The time zone that applies to parking regulations in this dataset. MUST be a valid [TZ database](https://www.iana.org/time-zones) time zone name (e.g. `"US/Eastern"` or `"Europe/Paris"`). | -| `last_updated` | [Timestamp][ts] | Required | The last time the data in this API was updated. | -| `currency` | String | Required | The ISO 4217 3-letter code for the currency in which rates for curb usage are denominated. | -| `author` | String | Optional | The name of the organization that produces and maintains this data. | -| `license_url` | URL | Optional | The licensing terms under which this data is provided. | - -Servers MUST set the `Content-Type` header to `application/vnd.cds+json;version=0.0` to support -versioning in the future. Clients SHOULD specify an `Accept` header containing -`application/vnd.cds+json;version=0.0`. If the server receives a request that contains an `Accept` -header but does not include this value; it MUST respond with a status of `406 Not Acceptable`. +[Top][toc] + +## Authorization + +[Authorization](/general-information.md#authorization) is not required for any of the Curbs endpoints, as this information should be made public and easily accessible. [Top][toc] From f0145953f5f3770504b295dff94e984eaee86d91 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 7 Jan 2022 16:48:39 -0500 Subject: [PATCH 088/173] Linked to rest endpoint and auth info --- events/README.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/events/README.md b/events/README.md index 4c8c7932..b812cd01 100644 --- a/events/README.md +++ b/events/README.md @@ -14,6 +14,7 @@ There are two different endpoints that are part of the Events API: # Table of Contents - [REST Endpoints](#rest-endpoints) + - [Authorization](#authorization) * [Query Event](#query-event) * [Query Status](#query-status) - [Data Objects](#data-objects) @@ -29,21 +30,13 @@ There are two different endpoints that are part of the Events API: # REST Endpoints -All endpoints return a JSON object containing the following fields: +All endpoints return a JSON object containing the fields as specified in the [REST Endpoint](/general-information.md#rest-endpoints) details. -| Name | Type | Required/Optional | Description | -| ------ | ------ | ------------------- | ------------- | -| `data` | _Endpoint-dependent_ | Required | The requested data objects. | -| `version` | String | Required | The specification version that the API conforms to (currently, `0.0`) | -| `time_zone` | String | Required | The time zone that applies to parking regulations in this dataset. MUST be a valid [TZ database](https://www.iana.org/time-zones) time zone name (e.g. `"US/Eastern"` or `"Europe/Paris"`). | -| `last_updated` | [Timestamp][ts] | Required | The last time the data in this API was updated. | -| `author` | String | Optional | The name of the organization that produces and maintains this data. | -| `license_url` | URL | Optional | The licensing terms under which this data is provided. | - -Servers MUST set the `Content-Type` header to `application/vnd.cds+json;version=0.0` to support -versioning in the future. Clients SHOULD specify an `Accept` header containing -`application/vnd.cds+json;version=0.0`. If the server receives a request that contains an `Accept` -header but does not include this value; it MUST respond with a status of `406 Not Acceptable`. +[Top][toc] + +## Authorization + +[Authorization](/general-information.md#authorization) is **required** for all of the Events endpoints, since depending on implementation, use cases, and fields required it may contain information only city transporation agencies should have access to. [Top][toc] From 1ae115df509d81a2fc4c77615fd16aebdaef7c40 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 7 Jan 2022 17:01:07 -0500 Subject: [PATCH 089/173] Linked to rest endpoint and auth info --- metrics/README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/metrics/README.md b/metrics/README.md index cd45d43d..325d7c46 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -15,6 +15,7 @@ There are two different endpoints that are part of the Metrics API: - [Representative Sample Data](#representative-sample-data) - [REST Endpoints](#rest-endpoints) + - [Authorization](#authorization) * [Update Frequency](#update-frequency) * [Query Session](#query-session) * [Query Aggregate](#query-aggregate) @@ -30,6 +31,25 @@ All data returned by the Metrics API should be viewed as using representative sa # REST Endpoints +All endpoints return a CSV file that can either be pre-computed or created on demand dynamically. + +If returning data from a static CSV file directly (e.g, from a web-based file system, service, or data portal), then adding header information is not required. + +If returning data from a dynamic server, they MUST set the `Content-Type` header to `application/vnd.cds+csv;version=1.0` to support +versioning in the future. Clients SHOULD specify an `Accept` header containing +`application/vnd.cds+csv;version=1.0`. If the server receives a request that contains an `Accept` +header but does not include this value; it MUST respond with a status of `406 Not Acceptable`. + +[Top][toc] + +## Authorization + +[Authorization](/general-information.md#authorization) is **optionally required** for all the Metrics endpoints, since depending on implementation, use cases, fields required, local laws, and audience it may contain information only city transportation agencies should have access to. It is recommended to authenticate when in doubt, though the information in [Query Aggregate](#query-aggregate) is aggregated report level data suitable for data analysis and public release. + +[Top][toc] + +# REST Endpoints + All endpoints return a CSV file that can either be pre-computed or created on demand. If returning data from a dynamic server, they MUST set the `Content-Type` header to `application/vnd.cds+csv;version=0.0` to support From 64a8726e0aa20fdd3809a7621dcdd1526e45ca03 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 7 Jan 2022 17:05:48 -0500 Subject: [PATCH 090/173] Start of events example --- events/examples.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 events/examples.md diff --git a/events/examples.md b/events/examples.md new file mode 100644 index 00000000..ef8cf3a9 --- /dev/null +++ b/events/examples.md @@ -0,0 +1,39 @@ +# Events Examples + +This file presents a series of CDS [Events](/events) endpoint examples to use as templates. + +## Table of Contents + +- [Curb Event Minimum](#curb-event-minimum) + +## Curb Event Minimum + +A [Query Event](/events#query-event) example of `/events/event` with minimum required fields returned, and no parameters passed in. + +**Query**: + +`/events/event` + +**Payload**: + +```json +{ + "version": "1.0", + "time_zone": "US/Eastern", + "last_updated": 1552678594428, + "currency": "USD", + "author": "City of Metropolis", + "license_url": "https://creativecommons.org/licenses/by/4.0/", + "data": [ + { + "events": [ + { + "event_id": "7d8a5885-e949-4ac9-afb7-fa4d43b68530" + } + ] + } + ] +} +``` + +[Top](#table-of-contents) From f5b3729b503bb8de7d6671d79edbf967990b418d Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 7 Jan 2022 17:06:29 -0500 Subject: [PATCH 091/173] Curbs link from examples --- curbs/examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/curbs/examples.md b/curbs/examples.md index b7206b59..ce8af600 100644 --- a/curbs/examples.md +++ b/curbs/examples.md @@ -9,7 +9,7 @@ This file presents a series of CDS [Curbs](/curbs) endpoint examples to use as t ## Curb Zones Minimum -A [Query Curb Zones](https://github.com/openmobilityfoundation/curb-data-specification/tree/feature-release-work-1/curbs#query-curb-zones) example of `/curbs/zone` with minimum required fields returned, plus a max parking stay of 60 minutes, and some parameters passed in. +A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with minimum required fields returned, plus a max parking stay of 60 minutes, and some parameters passed in. **Query**: From cf601616ce205f8d8e958db9c597d677792b45c9 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 7 Jan 2022 17:08:05 -0500 Subject: [PATCH 092/173] Link to examples from Events --- events/README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/events/README.md b/events/README.md index b812cd01..4a9b0769 100644 --- a/events/README.md +++ b/events/README.md @@ -27,6 +27,7 @@ There are two different endpoints that are part of the Events API: * [Lane Type](#lane-type) * [Curb Occupant](#curb-occupant) * [Status](#status) +- [Examples](#examples) # REST Endpoints @@ -266,6 +267,12 @@ A Curb Status is represented as a JSON object array of all deployed sensors, who [Top][toc] +# Examples + +See a series of [CDS Events endpoint examples](examples.md) to use as templates. + +[Top][toc] + [toc]: #table-of-contents [uuid]: /general-information.md#uuid [ts]: /general-information.md#timestamp From 4549920af524d7cc4ca102dc976d1d0d5adfbcb6 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 10 Jan 2022 20:36:35 -0500 Subject: [PATCH 093/173] First Event example --- events/examples.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/events/examples.md b/events/examples.md index ef8cf3a9..acc33a41 100644 --- a/events/examples.md +++ b/events/examples.md @@ -8,7 +8,7 @@ This file presents a series of CDS [Events](/events) endpoint examples to use as ## Curb Event Minimum -A [Query Event](/events#query-event) example of `/events/event` with minimum required fields returned, and no parameters passed in. +A [Query Event](/events#query-event) example of `/events/event` with minimum required fields returned showing the start of a `park_start` event at a specific curb zone detected by an above ground sensor, and no parameters passed in. **Query**: @@ -28,7 +28,21 @@ A [Query Event](/events#query-event) example of `/events/event` with minimum req { "events": [ { - "event_id": "7d8a5885-e949-4ac9-afb7-fa4d43b68530" + "event_id": "7d8a5885-e949-4ac9-afb7-fa4d43b68530", + "event_type": "park_start", + "event_location": { + "type": "Feature", + "properties": {}, + "geometry": { + "type": "Point", + "coordinates": [ -85.7629808, 38.257341 ] + } + }, + "event_time": "1552678578632", + "event_publication_time": "1552678594428", + "curb_zone_id": "02885f6f-ef93-441b-9e74-487279380656", + "data_source_type": "above_ground", + "data_source_device_id": "0fcb51b0-4529-4d28-a339-81e9a9bbcdb3" } ] } From 6e6a1eb5b2b4aee300c49869265750053b9bd825 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 10 Jan 2022 20:39:31 -0500 Subject: [PATCH 094/173] Removed redundant currency field --- events/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/events/README.md b/events/README.md index 4a9b0769..99ee1c81 100644 --- a/events/README.md +++ b/events/README.md @@ -117,8 +117,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `vehicle_propulsion_types` | Array of [Propulsion Type](#propulsion-type) | Conditionally Required | List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type. | | `vehicle_blocked_lane_types` | Array of [Lane Type](#lane-type) | Conditionally Required | Type(s) of lane blocked by the vehicle performing the event. If no lanes are blocked by the vehicle performing the event, the array should be empty. Required for the following event_types: _park_start_ | | `curb_occupants` | Array of [Curb Occupant](#curb-occupants) | Conditionally Required | Current occupants of the Curb Zone. If the sensor is capable of identifying the linear location of the vehicle, then elements are sorted in ascending order according to the start property of the linear reference. Otherwise, elements appear in no particular order. Required for the following event_types: _park_start, park_end, scheduled_report_ | -| `currency` | String | Optional | Fields specifying a monetary cost use a currency as specified in ISO 4217. All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of 100 (for 100 cents). If the currency field is null, USD cents is implied. | -| `actual_cost` | Integer | Optional | If available from the source, the actual cost, in the currency defined in currency, paid by the curb user for this event. | +| `actual_cost` | Integer | Optional | If available from the source, the actual cost, in the currency defined in currency, paid by the curb user for this event. The currency type is sent in with the [REST Endpoints](#rest-endpoints) JSON object. | [Top][toc] From bbf77d0453833e65ae1faa907017d8d3a1673eb3 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 10 Jan 2022 20:41:32 -0500 Subject: [PATCH 095/173] Updated currency description --- general-information.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/general-information.md b/general-information.md index 2f3236a5..fdaddca4 100644 --- a/general-information.md +++ b/general-information.md @@ -111,8 +111,8 @@ All dynamic REST endpoints will return a JSON object containing the following fi | `data` | _Endpoint-dependent_ | Required | The requested data objects. | | `version` | String | Required | The specification version that the API conforms to (currently, `0.0`) | | `time_zone` | String | Required | The time zone that applies to parking regulations in this dataset. MUST be a valid [TZ database](https://www.iana.org/time-zones) time zone name (e.g. `"US/Eastern"` or `"Europe/Paris"`). | -| `last_updated` | [Timestamp][ts] | Required | The last time the data in this API was updated. | -| `currency` | String | Required | The ISO 4217 3-letter code for the currency in which rates for curb usage are denominated. | +| `last_updated` | [Timestamp][#timestamp] | Required | The last time the data in this API was updated. | +| `currency` | String | Required | The ISO 4217 3-letter code for the currency in which rates for curb usage are denominated. All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of 100 (for 100 cents). | | `author` | String | Optional | The name of the organization that produces and maintains this data. | | `license_url` | URL | Optional | The licensing terms under which this data is provided. | From 9d404604ace8f1a7718e9135c654967b3bba86c0 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 10 Jan 2022 20:42:05 -0500 Subject: [PATCH 096/173] Clarified actual_cost description --- events/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index 99ee1c81..93cc480e 100644 --- a/events/README.md +++ b/events/README.md @@ -117,7 +117,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `vehicle_propulsion_types` | Array of [Propulsion Type](#propulsion-type) | Conditionally Required | List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type. | | `vehicle_blocked_lane_types` | Array of [Lane Type](#lane-type) | Conditionally Required | Type(s) of lane blocked by the vehicle performing the event. If no lanes are blocked by the vehicle performing the event, the array should be empty. Required for the following event_types: _park_start_ | | `curb_occupants` | Array of [Curb Occupant](#curb-occupants) | Conditionally Required | Current occupants of the Curb Zone. If the sensor is capable of identifying the linear location of the vehicle, then elements are sorted in ascending order according to the start property of the linear reference. Otherwise, elements appear in no particular order. Required for the following event_types: _park_start, park_end, scheduled_report_ | -| `actual_cost` | Integer | Optional | If available from the source, the actual cost, in the currency defined in currency, paid by the curb user for this event. The currency type is sent in with the [REST Endpoints](#rest-endpoints) JSON object. | +| `actual_cost` | Integer | Optional | If available from the source, the actual cost, in the currency defined in currency, paid by the curb user for this event. The currency type is sent in with the [REST Endpoints](#rest-endpoints) JSON object. All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of 100 (for 100 cents). | [Top][toc] From 1da1ade82c47c6f5f565007d402c2ab3f4ca128f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 10 Jan 2022 21:03:02 -0500 Subject: [PATCH 097/173] Added geographic data --- general-information.md | 54 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/general-information.md b/general-information.md index fdaddca4..bce7147a 100644 --- a/general-information.md +++ b/general-information.md @@ -8,7 +8,10 @@ This document contains specifications that are shared between the various CDS AP - [Authorization](#authorization) - [Beta Features](#beta-features) - [Costs and Currencies](#costs-and-currencies) -- [Polygon](#polygon) +- [Geographic Data][#geographic-data] + - [Geographic Telemetry Data](geographic-telemetry-data) + - [Polygon](#polygon) + - [Intersection Operation](#intersection-operation) - [REST Endpoints](#rest-endpoints) - [UUID](#uuid) - [Timestamp](#timestamp) @@ -82,7 +85,46 @@ Defining terminology and abbreviations used throughout CDS. - Curb Zone - A geographically and policy defined area where transactions may happen at curb space. - Curb Space - A geographically defined area within a Curb Zone for a single vehicle. -# Polygon +# Geographic Data + +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]. + +## Geographic Telemetry Data + +Whenever a vehicle or device 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, + "accuracy": 10, + "speed": 1.21 + }, + "geometry": { + "type": "Point", + "coordinates": [ + -118.46710503101347, + 33.9909333514159 + ] + } +} +``` + +## Polygon A polygon is a GeoJSON geometry of type `"Polygon"` as defined in [RFC 7946 3.1.6](https://www.ietf.org/rfc/rfc7946.txt). An example polygon is: @@ -100,6 +142,14 @@ A polygon is a GeoJSON geometry of type `"Polygon"` as defined in } ``` +## Intersection Operation + +For the purposes of this specification, the intersection of two geographic datatypes is defined according to the [`ST_Intersects` PostGIS operation][st-intersects] + +> If a geometry or geography shares any portion of space then they intersect. For geography -- tolerance is 0.00001 meters (so any points that are close are considered to intersect). +> +> 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] # REST Endpoints From f40171b5fd168d54698c8e46ddfd544f68ea638e Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 10 Jan 2022 21:12:25 -0500 Subject: [PATCH 098/173] Added responses, versions, pagination --- general-information.md | 85 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) diff --git a/general-information.md b/general-information.md index bce7147a..71137a80 100644 --- a/general-information.md +++ b/general-information.md @@ -8,13 +8,16 @@ This document contains specifications that are shared between the various CDS AP - [Authorization](#authorization) - [Beta Features](#beta-features) - [Costs and Currencies](#costs-and-currencies) -- [Geographic Data][#geographic-data] +- [Geographic Data](#geographic-data) - [Geographic Telemetry Data](geographic-telemetry-data) - [Polygon](#polygon) - [Intersection Operation](#intersection-operation) +- [Responses](#responses) - [REST Endpoints](#rest-endpoints) +- [Pagination](#pagination) - [UUID](#uuid) - [Timestamp](#timestamp) +- [Versioning](#versioning) # Authorization @@ -152,6 +155,36 @@ For the purposes of this specification, the intersection of two geographic datat [Top][toc] +# Responses + +* **200:** OK: operation successful. +* **201:** Created: `POST` operations, new object created +* **400:** Bad request. +* **401:** Unauthorized: Invalid, expired, or insufficient scope of token. +* **404:** Not Found: Object does not exist, returned on `GET` or `POST` operations if the object does not exist. +* **406:** Not Acceptable. Invalid response. +* **409:** Conflict: `POST` operations when an object already exists and an update is not possible. +* **500:** Internal server error: In this case, the answer may contain a `text/plain` body with an error message for troubleshooting. +* **501:** Not Implemented. + +## Error Messages + +```json +{ + "error": "...", + "error_description": "...", + "error_details": [ "...", "..." ] +} +``` + +| Field | Type | Field Description | +| ------------------- | -------- | ---------------------- | +| `error` | String | Error message string | +| `error_description` | String | Human readable error description (can be localized) | +| `error_details` | String[] | Array of error details | + +[Top][toc] + # REST Endpoints All dynamic REST endpoints will return a JSON object containing the following fields: @@ -173,6 +206,38 @@ header but does not include this value; it MUST respond with a status of `406 No [Top][toc] +# Pagination + +Endpoints may use pagination, which must comply with the [JSON API][json-api-pagination] specification. + +The following keys must be used for pagination links: + +* `first`: url to the first page of data +* `last`: url to the last page of data +* `prev`: url to the previous page of data +* `next`: url to the next page of data + +At a minimum, payloads that use pagination must include a `next` key, which must be set to `null` to indicate the last page of data. + +```json +{ + "version": "x.y.z", + "data": { + "endpoint": [{ + "field_name": "..." + }] + }, + "links": { + "first": "https://...", + "last": "https://...", + "prev": "https://...", + "next": "https://..." + } +} +``` + +[Top][toc] + # UUID A UUID is a 128-bit, globally unique identifier represented as a string using the format defined in @@ -189,4 +254,22 @@ A timestamp is an integer representing a number of milliseconds since midnight, [Top][toc] +# Versioning + +CDS APIs must handle requests for specific versions of the specification from clients. + +Versioning must be implemented through the use of a custom media-type, `application/vnd.cds+json`, combined with a required `version` parameter. + +The version parameter specifies the dot-separated combination of major and minor versions from a published version of the specification. For example, the media-type for version `1.0.1` would be specified as `application/vnd.cds+json;version=1.0` + +Clients must specify the version they are targeting through the `Accept` header. For example: + +```http +Accept: application/vnd.cds+json;version=1.2.0 +``` + +If an unsupported or invalid version is requested, the API must respond with a status of `406 Not Acceptable`. + +[Top][toc] + [toc]: #table-of-contents From 6e13c3ccef4dc839a7be8ad4c2fed1561ea01424 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 10 Jan 2022 21:51:00 -0500 Subject: [PATCH 099/173] Added second Events example --- events/examples.md | 61 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 2 deletions(-) diff --git a/events/examples.md b/events/examples.md index acc33a41..dcb410fc 100644 --- a/events/examples.md +++ b/events/examples.md @@ -5,10 +5,11 @@ This file presents a series of CDS [Events](/events) endpoint examples to use as ## Table of Contents - [Curb Event Minimum](#curb-event-minimum) +- [Fleet Operator](#fleet-operator) ## Curb Event Minimum -A [Query Event](/events#query-event) example of `/events/event` with minimum required fields returned showing the start of a `park_start` event at a specific curb zone detected by an above ground sensor, and no parameters passed in. +A [Query Event](/events#query-event) example of `/events/event` with minimum required fields showing the start of a `park_start` event at a specific curb zone detected by an above ground sensor, and no parameters passed in. **Query**: @@ -32,7 +33,7 @@ A [Query Event](/events#query-event) example of `/events/event` with minimum req "event_type": "park_start", "event_location": { "type": "Feature", - "properties": {}, + "properties": { "timestamp": 1552678574581 }, "geometry": { "type": "Point", "coordinates": [ -85.7629808, 38.257341 ] @@ -50,4 +51,60 @@ A [Query Event](/events#query-event) example of `/events/event` with minimum req } ``` +## Fleet Operator + +A [Query Event](/events#query-event) example of `/events/event` from a fleet operator's data feed with many optional fields showing the start of a `park_start` with event details and vehicle properties, and the curb_zone_id parameter passed in. + +**Query**: + +`/events/event?curb_zone_id=02885f6f-ef93-441b-9e74-487279380656` + +**Payload**: + +```json +{ + "version": "1.0", + "time_zone": "US/Eastern", + "last_updated": 1552678594428, + "currency": "USD", + "author": "City of Metropolis", + "license_url": "https://creativecommons.org/licenses/by/4.0/", + "data": [ + { + "events": [ + { + "event_id": "7d8a5885-e949-4ac9-afb7-fa4d43b68530", + "event_type": "park_start", + "event_purpose": "parcel_delivery", + "event_location": { + "type": "Feature", + "properties": { "timestamp": 1552678574581 }, + "geometry": { + "type": "Point", + "coordinates": [ -85.7629808, 38.257341 ] + } + }, + "event_time": "1552678578632", + "event_publication_time": "1552678594428", + "curb_zone_id": "02885f6f-ef93-441b-9e74-487279380656", + "data_source_type": "above_ground", + "data_source_operator_id": "16a85550-51d3-4f52-8ea9-e8a10306cab2", + "data_source_operator_name": "USPS", + "data_source_device_id": "618e92a4-e557-42a9-8f0a-0273545f7f49", + "data_source_manufacturer": "Grumman", + "data_source_model": "LLV", + "vehicle_id": "USDOT 33213", + "vehicle_permit_number": "KYVID-319380-A", + "vehicle_length": "670", + "vehicle_type": "truck", + "vehicle_propulsion_types": ["electric"], + "vehicle_blocked_lane_types": "parking" + } + ] + } + ] +} +``` + + [Top](#table-of-contents) From dd64f3cb230161beab55026427deb660bc3f2c07 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 10 Jan 2022 21:57:41 -0500 Subject: [PATCH 100/173] Updated event object field names --- events/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/events/README.md b/events/README.md index 93cc480e..d846f81a 100644 --- a/events/README.md +++ b/events/README.md @@ -140,9 +140,9 @@ A Curb Event is represented as a JSON object, whose fields are as follows: ### Source Type -`source_type`. Curb Source Type enumerates the set of possible categories of sources that are sending this event. The values that it can assume are listed below: +`data_source_type`. Curb Data Source Type enumerates the set of possible categories of sources that are sending this event. The values that it can assume are listed below: -| `source_type` | Description | +| `data_source_type` | Description | |----------------| ----------- | | `data_feed` | directly from a provider data feed sent to the agency | | `camera` | video or static image processing source | @@ -178,14 +178,14 @@ Type of vehicle, similar to vehicle_type in MDS. For this CDS release the list w Propulsion type of the vehicle, similar to propulsion_type in MDS. For this CDS release the list will be developed independently here to accommodate CDS and MDS use cases, while still aligning to the MDS design principles. In the next major MDS 2.0 release and next CDS release, alignment between CDS and MDS propulsion types can occur. -| `propulsion` | Description | +| `vehicle_propulsion_types` | Description | | ----------------- | ------------------------------------------------------ | | `human` | Pedal or foot propulsion | | `electric_assist` | Provides power only alongside human propulsion | | `electric` | Contains throttle mode with a battery-powered motor | | `combustion` | Contains throttle mode with a gas engine-powered motor | -A vehicle may have one or more values from the `propulsion`, depending on the number of modes of operation. For example, a scooter that can be powered by foot or by electric motor would have the `propulsion` represented by the array `['human', 'electric']`. A bicycle with pedal-assist would have the `propulsion` represented by the array `['human', 'electric_assist']` if it can also be operated as a traditional bicycle. +A vehicle may have one or more values from the `vehicle_propulsion_types`, depending on the number of modes of operation. For example, a scooter that can be powered by foot or by electric motor would have the `vehicle_propulsion_types` represented by the array `["human", "electric"]`. A bicycle with pedal-assist would have the `vehicle_propulsion_types` represented by the array `["human", "electric_assist"]` if it can also be operated as a traditional bicycle. A hybrid vehicle may use `["combustion", "electric"]`. [Top][toc] @@ -222,9 +222,9 @@ General purpose that the vehicle performed during its event, discernible by obse ### Lane Type -`lane_type`. Type(s) of lane used or blocked by the vehicle performing the event, outside of curb zones. E.g., double parking. +`vehicle_blocked_lane_types`. Type(s) of lane used or blocked by the vehicle performing the event, outside of curb zones. E.g., double parking. -| `lane_type` | Description | +| `vehicle_blocked_lane_types` | Description | | -------------- | ------------------------------------------------------ | | `travel_lane` | A standard vehicle travel lane. | | `turn_lane` | A dedicated turn lane. | From 7567843d1a4931af7905275a7e037721f5d6bb1f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 10 Jan 2022 21:58:56 -0500 Subject: [PATCH 101/173] Example update for array --- events/examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/examples.md b/events/examples.md index dcb410fc..5b542ddf 100644 --- a/events/examples.md +++ b/events/examples.md @@ -98,7 +98,7 @@ A [Query Event](/events#query-event) example of `/events/event` from a fleet ope "vehicle_length": "670", "vehicle_type": "truck", "vehicle_propulsion_types": ["electric"], - "vehicle_blocked_lane_types": "parking" + "vehicle_blocked_lane_types": ["parking"] } ] } From 88e43d83951d7085ab0ef597ae7fb5e5e7a29965 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 10 Jan 2022 22:23:21 -0500 Subject: [PATCH 102/173] Update to Rule table --- curbs/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 33ec6da1..7af63383 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -344,13 +344,13 @@ A rule defines who is allowed to do what, and for how long, on a curb, per the p It is a JSON object with the following fields: -| Name | Type | Required/Optional | Description | -|----------------|-------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `activity` | String | Required | The activity that is forbidden or permitted by this regulation. Value MUST be one of the [activities](#activities). | -| `max_stay` | Integer | Optional | The length of time (in minutes) for which the curb may be used under this regulation. | -| `no_return` | Integer | Optional | The length of time (in minutes) that a user must vacate a Curb Zone before being allowed to return for another stay. | -| `user_classes` | Array of Strings | Optional | If specified, this regulation only applies to users matching the [user classes](#user-classes) contained within. If not specified, this regulation applies to everyone. | -| `rate` | Array of [Rates](#rate) | Optional | The cost of using this Curb Zone when this regulation applies. Rates are repeated to allow for prices that change over time. For instance, a regulation may have a price of $1 for the first hour but $2 for every subsequent hour. The complete set of the [Rates](#rate) array must span **from** `start_minutes` = `0` or `null` **to** `end_minutes` = `max_stay` without overlap of effective minutes (i.e. the range created by rate `start_minutes` and `end_minutes`). | +| Name | Type | Required/Optional | Description | +| ------ | ------ | ------------------- | ------------- | +| `activity` | [Activity](#activities) String | Required | The activity that is forbidden or permitted by this regulation. Value MUST be one of the [activities](#activities). | +| `max_stay` | Integer | Optional | The length of time (in minutes) for which the curb may be used under this regulation. | +| `no_return` | Integer | Optional | The length of time (in minutes) that a user must vacate a Curb Zone before being allowed to return for another stay. | +| `user_classes` | Array of [user class](#user-classes) Strings | Optional | If specified, this regulation only applies to users matching the [user classes](#user-classes) contained within. If not specified, this regulation applies to everyone. | +| `rate` | Array of [Rates](#rate) | Optional | The cost of using this Curb Zone when this regulation applies. Rates are repeated to allow for prices that change over time. For instance, a regulation may have a price of $1 for the first hour but $2 for every subsequent hour. The complete set of the [Rates](#rate) array must span **from** `start_minutes` = `0` or `null` **to** `end_minutes` = `max_stay` without overlap of effective minutes (i.e. the range created by rate `start_minutes` and `end_minutes`). If a "negative" [activity](#activities) is used, this array should be empty. | [Top][toc] @@ -360,7 +360,7 @@ The following activities may be specified for rules within a policy. The reason "positive" and "negative" versions of the same activities (like `loading` and `no parking`) is due to priorities: a `loading` rule that is higher priority than a `no loading` rule, for instance, implies that the Curb Zone does allow loading at the time in question, while a -`no parking` rule would not. +`no parking` rule would not. If "negative", `rate` array should be empty. - `parking` - implies that loading and stopping are also permitted - `no parking` From 7093003be6e365b2ca5176f18a1c4b9bcbb9103c Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 11 Jan 2022 09:56:45 -0500 Subject: [PATCH 103/173] Add Metrics example --- metrics/examples.md | 71 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 metrics/examples.md diff --git a/metrics/examples.md b/metrics/examples.md new file mode 100644 index 00000000..b1e0b04d --- /dev/null +++ b/metrics/examples.md @@ -0,0 +1,71 @@ +# Metrics Examples + +This file presents a series of CDS [Metrics](/metrics) endpoint examples to use as templates. + +## Table of Contents + +- [Static Aggregate Metrics](#static-aggregate-metrics) + +## Static Aggregate Metrics + +A [Query Aggregate](/metrics#query-aggregate) example of `/metrics/aggregate` with 2 aggregate metrics in 2 places over a 1 day period. Static endpoint so no parameters passed in. + +**Query**: + +`/metrics/aggregate` + +**Payload**: + +```csv +curb_place_type,curb_place_id,metric_type,date,hour,value +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,0,3 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,1,7 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,2,2 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,3,7 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,4,9 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,5,10 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,6,13 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,7,16 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,8,17 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,9,13 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,10,15 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,11,19 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,12,29 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,13,27 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,14,26 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,15,38 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,16,34 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,17,35 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,18,33 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,19,20 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,20,16 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,21,12 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,22,-1 +Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,23,8 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,0,10.5 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,1,5.0 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,2,3.0 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,3,2.9 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,4,8.3 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,5,14.5 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,6,15.3 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,7,16.2 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,8,18.1 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,9,21.3 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,10,15.2 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,11,12.1 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,12,11.8 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,13,9.3 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,14,5.7 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,15,6.7 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,16,9.2 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,17,6.4 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,18,8.3 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,19,10.3 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,20,13.5 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,21,14.2 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,22,12.1 +Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,23,9.6 +``` + +[Top](#table-of-contents) From 7339a50606830ada351b473658e38da8858e22de Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 11 Jan 2022 09:59:20 -0500 Subject: [PATCH 104/173] Link to Examples from Metrics --- metrics/README.md | 64 ++++++----------------------------------------- 1 file changed, 7 insertions(+), 57 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index 325d7c46..c81904f9 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -2,7 +2,7 @@ The Metrics API is a REST API allowing historic metrics calculations based on Event activity that happened at defined Curb places. -**See [other CDS APIs](/) on the homepage.** +**See [other CDS APIs](/README.md#curb-data-specification-apis) on the homepage.** # Endpoints @@ -11,6 +11,8 @@ There are two different endpoints that are part of the Metrics API: - [Session](#session) is information about an activity that occurs near, at, or within a pre-defined curb area. Sessions is a subset of items from the Events API. Sessions is *optional* within Metrics. - [Aggregate](#aggregate) is aggregated counts and methodology of curb events. Aggregates is *optional* within Metrics. +**See [examples](examples.md) for these endpoints.** + # Table of Contents - [Representative Sample Data](#representative-sample-data) @@ -23,7 +25,7 @@ There are two different endpoints that are part of the Metrics API: * [Session](#session) * [Aggregate](#aggregate) * [Methodology](#methodology) - * [Examples](#examples) +- [Examples](#examples) # Representative Sample Data @@ -220,61 +222,9 @@ Occupancy is a metric from parking that cities would like to apply to curbs. Wit [Top][toc] -### Examples - -Example of available for 2 aggregate metrics in 2 places over a 1 day period. - -``` -curb_place_type,curb_place_id,metric_type,date,hour,value -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,0,3 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,1,7 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,2,2 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,3,7 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,4,9 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,5,10 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,6,13 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,7,16 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,8,17 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,9,13 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,10,15 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,11,19 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,12,29 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,13,27 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,14,26 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,15,38 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,16,34 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,17,35 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,18,33 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,19,20 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,20,16 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,21,12 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,22,-1 -Zone,0f6a052d-f934-4159-8da4-3135e453b968,total_sessions,2021-10-31,23,8 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,0,10.5 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,1,5.0 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,2,3.0 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,3,2.9 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,4,8.3 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,5,14.5 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,6,15.3 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,7,16.2 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,8,18.1 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,9,21.3 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,10,15.2 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,11,12.1 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,12,11.8 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,13,9.3 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,14,5.7 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,15,6.7 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,16,9.2 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,17,6.4 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,18,8.3 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,19,10.3 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,20,13.5 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,21,14.2 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,22,12.1 -Space,7e6be807-ff61-4f12-85c8-0fb740b24436,average_dwell_time,2021-10-31,23,9.6 -``` +# Examples + +See a series of [CDS Metrics endpoint examples](examples.md) to use as templates. [Top][toc] From c8a851a45521a7bebaf0f82da5945de269c7d668 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 11 Jan 2022 10:00:11 -0500 Subject: [PATCH 105/173] Update links to examples and homepage --- curbs/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/curbs/README.md b/curbs/README.md index 7af63383..88f193d8 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -7,7 +7,7 @@ Curbs API can be connected to event and metrics data, and can be shared with com purposes such as routing, finding legal parking, loading, and pick-up/drop-off spots, or analyzing curb utilization over time. -**See [other CDS APIs](/) on the homepage.** +**See [other CDS APIs](/README.md#curb-data-specification-apis) on the homepage.** # Endpoints @@ -23,6 +23,8 @@ There are four different endpoints that are part of the Curbs API: - A [Curb Policy](#policy) A Policy object is a rule that allows or prohibits a particular set of users from using a particular curb at a particular time or times. Curb policies are *optional*. +**See [examples](examples.md) for these endpoints.** + ![Curb Places](https://i.imgur.com/YQ7P243.jpg) # Table of Contents From 7aa81d2abc576a4b0dafccf5be3d3ab1356de711 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 11 Jan 2022 10:00:41 -0500 Subject: [PATCH 106/173] Update links to examples and homepage --- events/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index d846f81a..9024d732 100644 --- a/events/README.md +++ b/events/README.md @@ -2,7 +2,7 @@ The Events API is a REST API allowing real-time and historic events at the curb to be sent to cities, and the ability to check on the status of any sensors. Events can come from company data feeds, sensors, payments, check-ins, enforcement, and/or other city data sources. Data sent in the Events API can be connected to the Curbs API over time and space, and events are used for calculations in the Metrics API. -**See [other CDS APIs](/) on the homepage.** +**See [other CDS APIs](/README.md#curb-data-specification-apis) on the homepage.** # Endpoints @@ -11,6 +11,8 @@ There are two different endpoints that are part of the Events API: - A [Curb Event](#curb-event) is an activity that occurs near, at, or within a pre-defined curb area. Defining events is *required* as part of the Events API. - A [Status](#status) is the current status of a curb monitoring source. Event status is *optional*. +**See [examples](examples.md) for these endpoints.** + # Table of Contents - [REST Endpoints](#rest-endpoints) From be597112fcfc4d67cd99957a0ec981b0c1053000 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 11 Jan 2022 11:00:18 -0500 Subject: [PATCH 107/173] Placeholder for metrics session example --- metrics/examples.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/metrics/examples.md b/metrics/examples.md index b1e0b04d..43e7641c 100644 --- a/metrics/examples.md +++ b/metrics/examples.md @@ -4,11 +4,28 @@ This file presents a series of CDS [Metrics](/metrics) endpoint examples to use ## Table of Contents +- [Dynamic Sessions](#dynamic-sessions) - [Static Aggregate Metrics](#static-aggregate-metrics) +## Dynamic Sessions + +A [Query Session](/metrics#query-session) example of `/metrics/session` with . Dynamic endpoint with parameters passed in. + +**Query**: + +`/metrics/session?curb_place_type=zone&metric_type=average_dwell_time&start_time=&end_time=` + +**Payload**: + +```csv + +``` + +[Top](#table-of-contents) + ## Static Aggregate Metrics -A [Query Aggregate](/metrics#query-aggregate) example of `/metrics/aggregate` with 2 aggregate metrics in 2 places over a 1 day period. Static endpoint so no parameters passed in. +A [Query Aggregate](/metrics#query-aggregate) example of `/metrics/aggregate` that collects 2 aggregate metrics in 2 places over a 1 day period. Static endpoint so no parameters passed in. **Query**: From 6e56702e59f52ceb76fea38d8fa2dd1b19027538 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 11 Jan 2022 11:30:44 -0500 Subject: [PATCH 108/173] Fixed link to vehicle type --- metrics/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/metrics/README.md b/metrics/README.md index c81904f9..2494963a 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -141,7 +141,7 @@ A Session is represented as a CSV object, whose fields are as follows, pulled fr | `curb_area_ids` | [UUID][uuid] | Conditionally Required | Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area for these event_types: _enter_area, exit_area, park_start, park_end_ | | `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space for these event_types: _park_start, park_end, enter_area, exit_area_ | | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | -| `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | +| `vehicle_type` | [Vehicle Type](/events#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | ### Event Types From b61baf4ea8db25f65f9d214ee0179d77a42510bc Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 11 Jan 2022 11:33:00 -0500 Subject: [PATCH 109/173] metric_type not needed as Session query --- metrics/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/metrics/README.md b/metrics/README.md index 2494963a..a45bb6e8 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -84,7 +84,6 @@ An agency may choose to make this endpoint static (and return all the available | ------------ | --------- | ----------------- | ---------------------------------------------- | | `curb_place_type` | Enum | Optional | The type of curb place this aggregate applies to from the Curbs API: `area`, `zone`, `space`. Required with `curb_place_id`. | | `curb_place_id` | [UUID][uuid] | Optional | The ID of this single curb place. If specified, only return data contained within this area. Required with `curb_place_type`. | -| `metric_type` | Enum | Optional | The single metric to return from the [Methodology](#methodology): `total_sessions`, `turnover`, `average_dwell_time`, `occupancy_percent`. | | `min_lat`
        `min_lng`
        `max_lat`
        `max_lng` | Numeric | Optional | Specifies a latitude and longitude bounding box. If one of these parameters is specified, all four MUST be. If specified only return Curb Zones that intersect the supplied bounding box. | | `lat`
        `lng`
        `radius` | Numeric | Optional | Specifies a latitude and longitude bounding point and a radius away from that point. If one of these parameters is specified, all three MUST be. Returns only Curb Zones that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Zones in the response MUST be ordered ascending by distance from the center point. | | `start_time` | [Timestamp][ts] | Optional | The start of the time period to return data | From 98c8da79a0ea71fced060fc67ac536b5dbfdf51f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 11 Jan 2022 11:40:22 -0500 Subject: [PATCH 110/173] Second Metrics example --- metrics/examples.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/metrics/examples.md b/metrics/examples.md index 43e7641c..f39c4dc6 100644 --- a/metrics/examples.md +++ b/metrics/examples.md @@ -9,16 +9,20 @@ This file presents a series of CDS [Metrics](/metrics) endpoint examples to use ## Dynamic Sessions -A [Query Session](/metrics#query-session) example of `/metrics/session` with . Dynamic endpoint with parameters passed in. +A [Query Session](/metrics#query-session) example of `/metrics/session` with all fields returned for parking events in a specific zone over a short time period. Dynamic endpoint with parameters passed in. **Query**: -`/metrics/session?curb_place_type=zone&metric_type=average_dwell_time&start_time=&end_time=` +`/metrics/session?curb_place_type=zone&curb_place_id=d3c862b1-5404-4635-a90b-056537c50e81&start_time=1641738460&end_time=1642119064` **Payload**: ```csv - +session_type,event_id_start,event_id_end,event_location_start_latitude,event_location_start_longitude,event_location_end_latitude,event_location_end_longitude,event_time_start,event_time_end,curb_zone_id,vehicle_length,vehicle_type +parking,f49333b2-d693-4f5b-b187-1a1acd720eae,4cfa75aa-d044-436f-951f-0f3037de0d29,38.257341,-85.7629702,38.256330,-85.7629111,1641738560,1641918255,d3c862b1-5404-4635-a90b-056537c50e81,120,cargo_bicycle +parking,0843d2e7-ce60-44da-a609-fb4317ef15c6,d8599307-27b4-4161-be9a-c0d097cef54d,38.257352,-85.7629804,38.257331,-85.7629810,1641839464,1641919041,d3c862b1-5404-4635-a90b-056537c50e81,670,truck +parking,74e9d1d4-9037-4347-9135-f72010311ef7,f31f1615-adad-4542-83c8-9c858f9ecd0f,38.257349,-85.7629763,38.257836,-85.7630018,1641940456,1642019039,d3c862b1-5404-4635-a90b-056537c50e81,380,van +parking,35c923fd-78f5-471d-a548-efb0dabca3b7,c702915e-9b2e-45a5-ab30-f4413cdb1a1b,38.257359,-85.7629518,38.258139,-85.7629615,1642140839,1642119050,d3c862b1-5404-4635-a90b-056537c50e81,980,freight ``` [Top](#table-of-contents) From 621d6cf330bdfeb58554d133e166d72ff68701d2 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 11 Jan 2022 12:58:21 -0500 Subject: [PATCH 111/173] Updated example source type to data_feed --- events/examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/examples.md b/events/examples.md index 5b542ddf..c223ad20 100644 --- a/events/examples.md +++ b/events/examples.md @@ -87,7 +87,7 @@ A [Query Event](/events#query-event) example of `/events/event` from a fleet ope "event_time": "1552678578632", "event_publication_time": "1552678594428", "curb_zone_id": "02885f6f-ef93-441b-9e74-487279380656", - "data_source_type": "above_ground", + "data_source_type": "data_feed", "data_source_operator_id": "16a85550-51d3-4f52-8ea9-e8a10306cab2", "data_source_operator_name": "USPS", "data_source_device_id": "618e92a4-e557-42a9-8f0a-0273545f7f49", From 0732328c242dec131cdcbdfe16724248c97a3336 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 13 Jan 2022 10:55:01 -0500 Subject: [PATCH 112/173] Cleanup on Curb page --- events/README.md | 51 ++++++++++++++++++++++++------------------------ 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/events/README.md b/events/README.md index 9024d732..112bfb72 100644 --- a/events/README.md +++ b/events/README.md @@ -101,10 +101,10 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `event_time` | [Timestamp][ts] | Required | Time at which the event occurred. | | `event_publication_time` | [Timestamp][ts] | Required | Time at which the event became available for consumption by this API. | | `curb_zone_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Zone where the event occurred. Required for events that occurred at a known Curb Zone for ALL _event_types_. | -| `curb_area_ids` | [UUID][uuid] | Conditionally Required | Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area for these event_types: _enter_area, exit_area, park_start, park_end_ | -| `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space for these event_types: _park_start, park_end, enter_area, exit_area_ | +| `curb_area_ids` | [UUID][uuid] | Conditionally Required | Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area, if known and used, for these event_types: _enter_area, exit_area, park_start, park_end_ | +| `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space, if known and used, for these event_types: _park_start, park_end, enter_area, exit_area_ | | `data_source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | -| `data_source_operator_id` | [UUID][uuid] | Conditionally Required | Unique identifier of the entity responsible for operating the event data source. IDs can identify the fleet operator sending a data feed, or the organization (company or city) operating the sensor. IDs for fleet operators are required and global and come from the [data_source_operators.csv](/data_source_operators.csv) file, and optional for others. Read our [How to Get a Data Source Operator ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Data-Source-Operator-ID) guide. An agency at their discretion may allow a small, local company to simply provide a consistent `data_source_operator_name` string instead of this field. | +| `data_source_operator_id` | [UUID][uuid] | Conditionally Required | Unique identifier of the entity responsible for operating the event data source. IDs can identify the fleet operator sending a data feed, or the organization (company or city) operating the sensor. IDs for fleet operators are required and global and come from the [data_source_operators.csv](/data_source_operators.csv) file, and optional for others. Read our [How to Get a Data Source Operator ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Data-Source-Operator-ID) guide. An agency at their discretion may allow a small, local company to simply provide a consistent `data_source_operator_name` string instead of this field, otherwise this field is required. | | `data_source_operator_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `data_source_operator_id` or on its own for small operators at the discretion of the city. | | `data_source_device_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as the external `vehicle_id`. | | `data_source_manufacturer` | String | Optional | Manufacturer of the data source hardware or vehicle reporting event data. | @@ -117,17 +117,17 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | | `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | | `vehicle_propulsion_types` | Array of [Propulsion Type](#propulsion-type) | Conditionally Required | List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type. | -| `vehicle_blocked_lane_types` | Array of [Lane Type](#lane-type) | Conditionally Required | Type(s) of lane blocked by the vehicle performing the event. If no lanes are blocked by the vehicle performing the event, the array should be empty. Required for the following event_types: _park_start_ | -| `curb_occupants` | Array of [Curb Occupant](#curb-occupants) | Conditionally Required | Current occupants of the Curb Zone. If the sensor is capable of identifying the linear location of the vehicle, then elements are sorted in ascending order according to the start property of the linear reference. Otherwise, elements appear in no particular order. Required for the following event_types: _park_start, park_end, scheduled_report_ | +| `vehicle_blocked_lane_types` | Array of [Lane Type](#lane-type) | Conditionally Required | Type(s) of lane blocked by the vehicle performing the event. If no lanes are blocked by the vehicle performing the event, the array should be empty. Required for sources capable of determining it for the following event_types: _park_start_ | +| `curb_occupants` | Array of [Curb Occupant](#curb-occupants) | Conditionally Required | Current occupants of the Curb Zone. If the sensor is capable of identifying the linear location of the vehicle, then elements are sorted in ascending order according to the start property of the linear reference. Otherwise, elements appear in no particular order. Required for sources capable of determining it for the following event_types: _park_start, park_end, scheduled_report_ | | `actual_cost` | Integer | Optional | If available from the source, the actual cost, in the currency defined in currency, paid by the curb user for this event. The currency type is sent in with the [REST Endpoints](#rest-endpoints) JSON object. All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of 100 (for 100 cents). | [Top][toc] ### Event Type -`event_type`. Curb Event Type enumerates the set of possible types of Curb Event. The values that it can assume are listed below: +Curb Event Type `event_type` enumerates the set of possible types of Curb Event. The values that it can assume are listed below: -| `event_type` | Description | +| Name | Description | |--------------------|-------------| | `comms_lost` | communications with the event source were lost | | `comms_restored` | communications with the event source were restored | @@ -142,15 +142,16 @@ A Curb Event is represented as a JSON object, whose fields are as follows: ### Source Type -`data_source_type`. Curb Data Source Type enumerates the set of possible categories of sources that are sending this event. The values that it can assume are listed below: +Curb Data Source Type `data_source_type` enumerates the set of possible categories of sources that are sending this event. The values that it can assume are listed below: -| `data_source_type` | Description | +| Name | Description | |----------------| ----------- | | `data_feed` | directly from a provider data feed sent to the agency | | `camera` | video or static image processing source | -| `above_ground` | sensor deployed above ground | +| `above_ground` | sensor deployed above ground | | `in_ground` | sensor deployed in the ground | | `meter` | a smart parking meter | +| `payment` | from payment system or app | | `in_person` | an individual on site recording the event digitally or otherwise | | `other` | sources not enumerated above | @@ -158,10 +159,10 @@ A Curb Event is represented as a JSON object, whose fields are as follows: ### Vehicle Type -Type of vehicle, similar to vehicle_type in MDS. For this CDS release the list will be developed independently here to accommodate CDS and MDS use cases, while still aligning to the MDS design principles. In the next major MDS 2.0 release and next CDS release, alignment between CDS and MDS vehicle types can occur. +Type of vehicle `vehicle_type` similar to vehicle_type in MDS. For this CDS release the list will be developed independently here to accommodate CDS and MDS use cases, while still aligning to the MDS design principles. In the next major MDS 2.0 release and next CDS release, alignment between CDS and MDS vehicle types can occur. -| `vehicle_type` | Description | -|------------------| ----------- | +| Name | Description | +|----------------- | ----------- | | `bicycle` | A two-wheeled mobility device intended for personal transportation that can be operated via pedals, with or without a motorized assist (includes e-bikes, recumbents, and tandems) | | `cargo_bicycle` | A two- or three-wheeled bicycle intended for transporting larger, heavier cargo than a standard bicycle (such as goods or passengers), with or without motorized assist (includes bakfiets/front-loaders, cargo trikes, and long-tails) | | `car` | A passenger car or similar light-duty vehicle | @@ -178,9 +179,9 @@ Type of vehicle, similar to vehicle_type in MDS. For this CDS release the list w ### Propulsion Type -Propulsion type of the vehicle, similar to propulsion_type in MDS. For this CDS release the list will be developed independently here to accommodate CDS and MDS use cases, while still aligning to the MDS design principles. In the next major MDS 2.0 release and next CDS release, alignment between CDS and MDS propulsion types can occur. +Propulsion type `vehicle_propulsion_types` of the vehicle, similar to propulsion_type in MDS. For this CDS release the list will be developed independently here to accommodate CDS and MDS use cases, while still aligning to the MDS design principles. In the next major MDS 2.0 release and next CDS release, alignment between CDS and MDS propulsion types can occur. -| `vehicle_propulsion_types` | Description | +| Name | Description | | ----------------- | ------------------------------------------------------ | | `human` | Pedal or foot propulsion | | `electric_assist` | Provides power only alongside human propulsion | @@ -193,9 +194,9 @@ A vehicle may have one or more values from the `vehicle_propulsion_types`, depen ### Event Purpose -General purpose that the vehicle performed during its event, discernible by observation, sensors, or self-reported in company data feeds. New event purposes MAY be generated to reflect local curb uses, but when possible, the following well-known recommended values should be used. It may not always be knowable, but where it is possible this information should be conveyed. If multiple purposes apply, then use the more descriptive/specific value. +General event purpose `event_purpose` that the vehicle performed during its event, discernible by observation, sensors, or self-reported in company data feeds. New event purposes MAY be generated to reflect local curb uses, but when possible, the following well-known recommended values should be used. It may not always be knowable, but where it is possible this information should be conveyed. If multiple purposes apply, then use the more descriptive/specific value. -| `event_purpose` | Description | +| Name | Description | | --------------------- | ------------------------------------------------------ | | `construction` | Construction of hard assets including buildings and roadside infrastructure | | `delivery` | General delivery of parcels, goods, freight | @@ -224,9 +225,9 @@ General purpose that the vehicle performed during its event, discernible by obse ### Lane Type -`vehicle_blocked_lane_types`. Type(s) of lane used or blocked by the vehicle performing the event, outside of curb zones. E.g., double parking. +Type(s) of lane used or blocked `vehicle_blocked_lane_types` by the vehicle performing the event, outside of curb zones. E.g., double parking. -| `vehicle_blocked_lane_types` | Description | +| Name | Description | | -------------- | ------------------------------------------------------ | | `travel_lane` | A standard vehicle travel lane. | | `turn_lane` | A dedicated turn lane. | @@ -242,13 +243,13 @@ General purpose that the vehicle performed during its event, discernible by obse ### Curb Occupants -`curb_occupants`. A Curb Occupant object represents a specific vehicle’s occupancy in a curb region at a specific point in time. Curb Occupant objects contain the following fields: +A Curb Occupant `curb_occupants` object represents a specific vehicle’s occupancy in a curb region at a specific point in time. Curb Occupant objects contain the following fields: -| Name | Type | Required/Optional | Description | -| ------ | ------ | ------------------- | ------------- | -| `type` | [Vehicle Type](#vehicle-type) | Required | The vehicle type of the occupant. When the event source is not capable of distinguishing vehicle type, this property must take the value "unspecified". -| `length` | Float | Conditionally required | The approximate length in centimeters of the vehicle. Required when the event source is capable of determining vehicle length. -| `linear_location` | Array of Float | Conditionally required | A two-element array that specifies the start and end of the occupant’s linear location relative to the start of the Curb Zone in that order. Required when the event source is capable of determining the linear location of occupants. +| Name | Type | Required/Optional | Description | +| ----------------- | -------------- | ----------------------- | ----------- | +| `type` | [Vehicle Type](#vehicle-type) | Required | The vehicle type of the occupant. When the event source is not capable of distinguishing vehicle type, this property must take the value "unspecified". +| `length` | Float | Conditionally required | The approximate length in centimeters of the vehicle. Required when the event source is capable of determining vehicle length. +| `linear_location` | Array of Float | Conditionally required | A two-element array that specifies the start and end of the occupant’s linear location relative to the start of the Curb Zone in that order. Required when the event source is capable of determining the linear location of occupants. [Top][toc] From 2fdbac10b705759324bf49fcc8fab4ea471c609b Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 13 Jan 2022 11:07:16 -0500 Subject: [PATCH 113/173] Added session_id --- events/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/events/README.md b/events/README.md index 112bfb72..c151c09c 100644 --- a/events/README.md +++ b/events/README.md @@ -100,6 +100,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `event_location` | GeoJSON | Required | The geographic point location where the event occurred. | | `event_time` | [Timestamp][ts] | Required | Time at which the event occurred. | | `event_publication_time` | [Timestamp][ts] | Required | Time at which the event became available for consumption by this API. | +| `event_session_id` | [UUID][uuid] | Optional | May be provided to tie known connected `park_start` and `park_end` event types together by a unique session ID. If _not_ confident of being able to determine a `park_end` event at some time after `park_start` is recorded (i.e., you cannot detect when a vehicle departs), then do _not_ use session_id. This field may be most useful to payment companies who provide their source data as sessions (typical for transaction data). _Note also_: the use of the term "session" across CDS means the start and end of curb usage of a vehicle, not necessarily a financial or payment session or transaction. | | `curb_zone_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Zone where the event occurred. Required for events that occurred at a known Curb Zone for ALL _event_types_. | | `curb_area_ids` | [UUID][uuid] | Conditionally Required | Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area, if known and used, for these event_types: _enter_area, exit_area, park_start, park_end_ | | `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space, if known and used, for these event_types: _park_start, park_end, enter_area, exit_area_ | From 3448d79ccce12b1bdf1fef2679b3a534d056be1f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 13 Jan 2022 11:10:15 -0500 Subject: [PATCH 114/173] Added session ID to Metrics --- metrics/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/metrics/README.md b/metrics/README.md index a45bb6e8..ba859649 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -128,6 +128,7 @@ A Session is represented as a CSV object, whose fields are as follows, pulled fr | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | | `session_type` | Enum | Required | The type of session that happened for this event: `parking` or `area` | +| `session_id` | [UUID][uuid] | Optional | If known and recorded to tie two Events together, then include the `event_session_id` recorded in the [Curb Event](/events#curb-event). | | `event_id_start` | [UUID][uuid] | Conditionally Required | The globally unique identifier of the **start/enter** event that occurred. | | `event_id_end` | [UUID][uuid] | Conditionally Required | The globally unique identifier of the **end/exit** event that occurred. | | `event_location_start_latitude` | Number | Conditionally Required | The geographic latitude point location where the **start/enter** of the event occurred. | From 82a0a76a9026a4ff83336948d2fc965a7d8c4b26 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 13 Jan 2022 11:21:00 -0500 Subject: [PATCH 115/173] Updated name to event_session_id --- metrics/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/metrics/README.md b/metrics/README.md index ba859649..04835bf3 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -128,7 +128,7 @@ A Session is represented as a CSV object, whose fields are as follows, pulled fr | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | | `session_type` | Enum | Required | The type of session that happened for this event: `parking` or `area` | -| `session_id` | [UUID][uuid] | Optional | If known and recorded to tie two Events together, then include the `event_session_id` recorded in the [Curb Event](/events#curb-event). | +| `event_session_id` | [UUID][uuid] | Optional | If known and recorded to tie two Events together, then include the `event_session_id` from the [Curb Event](/events#curb-event). | | `event_id_start` | [UUID][uuid] | Conditionally Required | The globally unique identifier of the **start/enter** event that occurred. | | `event_id_end` | [UUID][uuid] | Conditionally Required | The globally unique identifier of the **end/exit** event that occurred. | | `event_location_start_latitude` | Number | Conditionally Required | The geographic latitude point location where the **start/enter** of the event occurred. | From 9f9f13a246f467ea801019c33384d778d991f063 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 13 Jan 2022 11:31:10 -0500 Subject: [PATCH 116/173] Added anchor shortcuts --- general-information.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/general-information.md b/general-information.md index 71137a80..933d3cab 100644 --- a/general-information.md +++ b/general-information.md @@ -272,4 +272,12 @@ If an unsupported or invalid version is requested, the API must respond with a s [Top][toc] +[decimal-degrees]: https://en.wikipedia.org/wiki/Decimal_degrees +[hdop]: https://en.wikipedia.org/wiki/Dilution_of_precision_(navigation) +[geo]: #geographic-data +[geojson-feature]: https://tools.ietf.org/html/rfc7946#section-3.2 +[geojson-point]: https://tools.ietf.org/html/rfc7946#section-3.1.2 +[st-intersects]: https://postgis.net/docs/ST_Intersects.html [toc]: #table-of-contents +[ts]: /general-information.md#timestamps +[wgs84]: https://en.wikipedia.org/wiki/World_Geodetic_System From 4cd36c3e072ed7d23e4346cf7e38513ed9e69d25 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 13 Jan 2022 11:40:29 -0500 Subject: [PATCH 117/173] Note about Event Times order Very similar to MDS guidance --- general-information.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/general-information.md b/general-information.md index 933d3cab..15e82b48 100644 --- a/general-information.md +++ b/general-information.md @@ -88,6 +88,12 @@ Defining terminology and abbreviations used throughout CDS. - Curb Zone - A geographically and policy defined area where transactions may happen at curb space. - Curb Space - A geographically defined area within a Curb Zone for a single vehicle. +# Event Times + +Return data in the order of timestamps of the events on the ground, with most recent items returned first to construct as accurate a timeline as possible. + +Because of unreliability of some device clocks and other factors, sensors and operators are unlikely to know with total confidence what time an event occurred at. However, endpoint producers are responsible for constructing as accurate a timeline as possible. Most importantly, the order of the timestamps for a particular vehicle's events must reflect the producer's best understanding of the order in which those events occurred. + # Geographic Data 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]. @@ -157,6 +163,8 @@ For the purposes of this specification, the intersection of two geographic datat # Responses +List of acceptable endpoint responses. + * **200:** OK: operation successful. * **201:** Created: `POST` operations, new object created * **400:** Bad request. @@ -208,7 +216,7 @@ header but does not include this value; it MUST respond with a status of `406 No # Pagination -Endpoints may use pagination, which must comply with the [JSON API][json-api-pagination] specification. +Endpoints may use pagination, which must comply with the [JSON API][json-api-pagination] specification. See [Event Times](/general-information.md#event-times) guideance about the order of data returned. The following keys must be used for pagination links: From d300080d545c5d9c0b78b5daefa47730900f3783 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 13 Jan 2022 11:41:10 -0500 Subject: [PATCH 118/173] Added Event Times to TOC --- general-information.md | 1 + 1 file changed, 1 insertion(+) diff --git a/general-information.md b/general-information.md index 15e82b48..4f80cd1f 100644 --- a/general-information.md +++ b/general-information.md @@ -8,6 +8,7 @@ This document contains specifications that are shared between the various CDS AP - [Authorization](#authorization) - [Beta Features](#beta-features) - [Costs and Currencies](#costs-and-currencies) +- [Event Times](#event-times) - [Geographic Data](#geographic-data) - [Geographic Telemetry Data](geographic-telemetry-data) - [Polygon](#polygon) From e997da50ba19ecdd99e24f002388a36123ac04bd Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 13 Jan 2022 11:42:40 -0500 Subject: [PATCH 119/173] Added event order --- events/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index c151c09c..bf71a21a 100644 --- a/events/README.md +++ b/events/README.md @@ -48,7 +48,7 @@ All endpoints return a JSON object containing the fields as specified in the [RE Endpoint: `/events/event` Method: `GET` `data` Payload: a JSON object with the following fields: - - `events`: an array of [Curb Event](#curb-event) objects + - `events`: an array of [Curb Event](#curb-event) objects. See [Event Times](/general-information.md#event-times) guidance about the order of data returned. _This endpoint must be implemented by every Events API server._ From 9411272f6aa9cee105c85f104646b78b2c46d6b1 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 13 Jan 2022 11:43:12 -0500 Subject: [PATCH 120/173] Guidance typo --- general-information.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/general-information.md b/general-information.md index 4f80cd1f..6f74bff3 100644 --- a/general-information.md +++ b/general-information.md @@ -217,7 +217,7 @@ header but does not include this value; it MUST respond with a status of `406 No # Pagination -Endpoints may use pagination, which must comply with the [JSON API][json-api-pagination] specification. See [Event Times](/general-information.md#event-times) guideance about the order of data returned. +Endpoints may use pagination, which must comply with the [JSON API][json-api-pagination] specification. See [Event Times](/general-information.md#event-times) guidance about the order of data returned. The following keys must be used for pagination links: From c25792a426af3f10e90b0eb2cbdcd30d50fb5559 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 13 Jan 2022 13:34:17 -0500 Subject: [PATCH 121/173] Update API summaries --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 792afda6..06c15bbf 100644 --- a/README.md +++ b/README.md @@ -32,9 +32,9 @@ CDS is at its core a set of Application Programming Interfaces (APIs) and endpoi | API | Description | |---|---| -| **[Curbs](/curbs)** | communicate curb locations and policies publicly | -| **[Events](/events)** | capture activity at Curbs from sensors and curb users | -| **[Metrics](/metrics)** | methodology and metrics to understand Events at Curbs | +| **[Curbs](/curbs)** | A standard way for cities to digitally publish curb locations and regulations, which can be shared with the public and with companies using curb space. | +| **[Events](/events)** | A standard way to transmit real-time and historic commercial events happening at the curb to cities. Event data can be derived from company data feeds, sensors, payments, check-ins, enforcement, and other city data sources. | +| **[Metrics](/metrics)** | Track curb usage session details and define common calculation methodologies to measure historic dwell time, occupancy, usage and other aggregated statistics. | CDS is a data exchange format and a translation layer between internal systems and external entities using data feeds. It is not expected that CDS will be the format used internally to store curb regulations in a city. The internal storage format is something different, and a subset of that data should be able to be converted to CDS for publishing out to the public and curb users. From 1e7342ec64d732fc3fe13cd6ba543d0147d2be85 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 14 Jan 2022 12:57:54 -0500 Subject: [PATCH 122/173] Added privacy and use case home page sections --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index 06c15bbf..c3f781f6 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,8 @@ - [Versions](#versions) - [Technical Information](#technical-information) - [Membership](#membership) +- [Data Privacy](#data-privacy) +- [Use Cases](#use-cases) # Overview @@ -109,4 +111,26 @@ Read about [how to become an OMF member](https://www.openmobilityfoundation.org/ [Top][toc] +# Data Privacy + +CDS includes information about commercial vehicles using select curb zones in a city to allow agencies to regulate curb use and policy in the public right of way and to conduct analysis for program improvements. While CDS is not designed to convey any personal information and is focused on commerical curb activity, some uses of some fields can be sensitive. The OMF community has created a number of resources to help cities, fleet operators, and software companies handle vehicle data safely: + +* [CDS Privacy Guidance](https://docs.google.com/document/d/117kJhXp6ldv7KHq7k9wHONHVVHw00xweaHpORVu_c10/edit?usp=sharing) - identifies relevant data in CDS, use cases, and provides suggestions on the safe handling of this data. +* [Privacy Guide for Cities](https://github.com/openmobilityfoundation/governance/raw/main/documents/OMF-MDS-Privacy-Guide-for-Cities.pdf) - guide that covers essential privacy topics and best practices +* [The Privacy Principles for Mobility Data](https://www.mobilitydataprivacyprinciples.org/) - principles endorsed by the OMF and other mobility organizations to guide the mobility ecosystem in the responsible use of data and the protection of individual privacy +* [Mobility Data State of Practice](https://github.com/openmobilityfoundation/privacy-committee/blob/main/products/state-of-the-practice.md) - real-world examples related to the handling and protection of MDS and other types of mobility data +* [CDS Use Cases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Curbs-Use-Cases) - outlines real-world use cases, and how to use CDS to make them happen and why. + +The OMF’s [Privacy, Security, and Transparency Committee](https://github.com/openmobilityfoundation/privacy-committee#welcome-to-the-privacy-security-and-transparency-committee) creates many of these resources, and advises the OMF on principles and practices that ensure the secure handling of mobility data. The committee – which is composed of both private and public sector OMF members – also holds regular public meetings, which provide additional resources and an opportunity to discuss issues related to privacy and mobility data. Learn more [here](https://github.com/openmobilityfoundation/privacy-committee#welcome-to-the-privacy-security-and-transparency-committee). + +[Top][toc] + +# Use Cases + +How cities use CDS depends on a variety of factors: their transportation goals, existing services and infrastructure, and the unique needs of their communities. Cities are using CDS to create policy, manage curbs, and ensure the safe operation of vehicles in the public right of way. + +A list of use cases is useful to show what's possible with CDS, to see many use cases up front for privacy considerations, and to use for policy discussions and policy language. More details and examples can be seen on the [CDS Use Cases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Curbs-Use-Cases). + +[Top][toc] + [toc]: #table-of-contents From de80381144c7aa1a4d3a280ef5b82a188869ab39 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 17 Jan 2022 10:39:37 -0500 Subject: [PATCH 123/173] Seeding data source with members --- data_source_operators.csv | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/data_source_operators.csv b/data_source_operators.csv index 46571dae..bef4b4a5 100644 --- a/data_source_operators.csv +++ b/data_source_operators.csv @@ -1,2 +1,7 @@ data_source_operator_name,data_source_operator_id,url -SAMPLE COMPANY NAME,d548b89f-a76d-45f7-9e07-c2aae304031b,https://www.companywebsitename.com +Automotus,6ee362db-b059-43ac-83d4-3d634ec7a22c,https://www.automotus.co/ +Bird,2411d395-04f2-47c9-ab66-d09e9e3c3251,https://www.bird.co +Kiwibot,5f19acae-d7e9-4b57-96bd-f6406712d654,https://www.kiwibot.com/ +Passport,55b617b9-730e-485e-83de-5e1a35fdc352,https://www.passportinc.com/ +Spin,70aa475d-1fcd-4504-b69c-2eeb2107f7be,https://www.spin.app +Waymo,288e70d7-fa0b-499d-ab20-a686ec4ee2cb,https://waymo.com/ From 260d6467d585e4fc8fb03ad9849a00b207c8a781 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 17 Jan 2022 10:47:48 -0500 Subject: [PATCH 124/173] Added no parking definition --- curbs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/curbs/README.md b/curbs/README.md index 88f193d8..7bc34399 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -365,7 +365,7 @@ for instance, implies that the Curb Zone does allow loading at the time in quest `no parking` rule would not. If "negative", `rate` array should be empty. - `parking` - implies that loading and stopping are also permitted -- `no parking` +- `no parking` - may not stop and leave vehicle unattended - `loading` - of goods; implies that stopping is also permitted - `no loading` - implies that parking is also prohibited - `stopping` - stopping briefly to pick up or drop off passengers From 32d681cfeab7db8a9cf3eddafb6bdbcd76f0e4e6 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 17 Jan 2022 10:59:58 -0500 Subject: [PATCH 125/173] Remove policy objects from /curbs/zone endpoint --- curbs/README.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 7bc34399..8cd5942d 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -21,7 +21,8 @@ There are four different endpoints that are part of the Curbs API: could be used to show proximity, approaches, conflicts, circling, or other activity. Curb areas are *optional*. - A [Curb Policy](#policy) A Policy object is a rule that allows or prohibits a particular set of - users from using a particular curb at a particular time or times. Curb policies are *optional*. + users from using a particular curb at a particular time or times. Curb policies are *optional* + but recommended with Curb Zones. **See [examples](examples.md) for these endpoints.** @@ -68,9 +69,7 @@ All endpoints return a JSON object containing the fields as specified in the [RE Endpoint: `/curbs/zone` Method: `GET` -`data` Payload: a JSON object with the following fields: - - `zones`: an array of [Curb Zone](#curb-zone) objects - - `policies`: an array of [Policy](#policy) objects +`data` Payload: a JSON object with a `zones` field containing an array of [Curb Zone](#curb-zone) objects. _This endpoint must be implemented by every Curbs API server._ @@ -84,7 +83,6 @@ All query parameters are optional. | `min_lat`
        `min_lng`
        `max_lat`
        `max_lng` | Numeric | Specifies a bounding box; if one of these parameters is specified, all four MUST be. If specified only return Curb Zones that intersect the supplied bounding box. | | `lat`
        `lng`
        `radius` | Numeric | If one of these parameters is specified, all three MUST be. Returns only Curb Zones that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Zones in the response MUST be ordered ascending by distance from the center point. | | `include_geometry` | `true`/`false` | If the value is `false`, do not include the `geometry` field within the [Curb Zone](#curb-zone) feature object. | -| `include_policies` | `true`/`false` | If the value is `false`, do not include the `policies` field within the response. | | `time` | [Timestamp][ts] | Only Curb Zone objects whose validity period includes this time will be returned; availability data (if supplied) will be returned as of this time. | [Top][toc] @@ -135,7 +133,7 @@ Endpoint: `/curb/policy` Method: `GET` `data` Payload: a JSON object with a `policies` field containing an array of [Curb Policy](#policy) objects. -_Optional endpoint; if not implemented, the server should reply with `501 Not Implemented`._ +_Optional endpoint, but required if Curb Zones contain policy_id references; if not implemented, the server should reply with `501 Not Implemented`._ ### Query Parameters @@ -159,10 +157,10 @@ _Optional endpoint; if not implemented, the server should reply with `501 Not Im All query parameters are optional. -| Name | Type | Description | -| ------------ | --------- | ---------------------------------------------- | -| `time` | [Timestamp][ts] | The Curb Zone object will only be returned if its validity period includes this time; otherwise, the server should reply with `404 Not Found`. Availability data (if supplied) will be returned as of this time. | -| `show_historic` | Boolean | Whether to return historic, retired curb zone data. Default is "false" to reduce payload size and complexity. | +| Name | Type | Description | +| --------------- | --------------- | ---------------------------------------------- | +| `time` | [Timestamp][ts] | The Curb Zone object will only be returned if its validity period includes this time; otherwise, the server should reply with `404 Not Found`. Availability data (if supplied) will be returned as of this time. | +| `show_historic` | Boolean | Whether to return historic, retired curb zone data. Default is "false" to reduce payload size and complexity. | [Top][toc] @@ -190,9 +188,9 @@ Method: `GET` All query parameters are optional. -| Name | Type | Description | -| ------------ | --------- | ---------------------------------------------- | -| `time` | [Timestamp][ts] | Availability data (if supplied) will be returned as of this time. | +| Name | Type | Description | +| ------------ | --------------- | ---------------------------------------------- | +| `time` | [Timestamp][ts] | Availability data (if supplied) will be returned as of this time. | [Top][toc] @@ -484,7 +482,7 @@ A Location Reference is a JSON object with the following fields: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `source` | URL | Required | An identifier for the source of the linear reference. This MUST be a URL pointing to more information about the underlying map or reference system. Values include (but other can be used):
        • `https://sharedstreets.io`: SharedStreets
        • `http://openlr.org`: OpenLR
        • `https://coord.com`: Coord
        • `https://yourcityname.gov`: custom city LR, direct link if possible
          • | +| `source` | URL | Required | An identifier for the source of the linear reference. This MUST be a URL pointing to more information about the underlying map or reference system. Values include (but other can be used):
          • `https://sharedstreets.io`: SharedStreets
          • `http://openlr.org`: OpenLR
          • `https://coord.com`: Coord
          • `https://yourcityname.gov`: custom city LR, direct link if possible
          | | `ref_id` | String | Required | The linear feature being referenced (usually a street or curb segment). For OpenLR, this is the Base64-encoded OpenLR line location for the street segment of which this Curb Zone is part, and the start and end offsets below are relative to this segment. | | `start` | Integer | Required | The distance (in centimeters) from the start of the referenced linear feature to the start of the Curb Zone. | | `end` | Integer | Required | The distance (in centimeters) from the start of the referenced linear feature to the end of the Curb Zone. 'end' MAY be smaller than start, implying that the direction of the Curb Zone is opposite to the direction of the referenced linear feature. | From 0a47a73450bb79e0a58360c13c8c76a88635e579 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 17 Jan 2022 11:06:09 -0500 Subject: [PATCH 126/173] Updated endpoint requirements --- curbs/README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 8cd5942d..bccc4307 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -71,7 +71,7 @@ Endpoint: `/curbs/zone` Method: `GET` `data` Payload: a JSON object with a `zones` field containing an array of [Curb Zone](#curb-zone) objects. -_This endpoint must be implemented by every Curbs API server._ +_This required endpoint must be implemented by every Curbs API server. If attaching policies to curb zones, the [Query Curb Policies](#query-curb-policies) endpoint is also required._ ### Query Parameters @@ -93,7 +93,7 @@ Endpoint: `/curbs/area` Method: `GET` `data` Payload: a JSON object with an `areas` field containing an array of [Curb Area](#curb-area) objects. -_Optional endpoint; if not implemented, the server should reply with `501 Not Implemented`._ +_Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._ ### Query Parameters @@ -112,7 +112,7 @@ Endpoint: `/curbs/space` Method: `GET` `data` Payload: a JSON object with a `spaces` field containing an array of [Curb Space](#curb-space) objects. -_Optional endpoint; if not implemented, the server should reply with `501 Not Implemented`._ +_Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._ ### Query Parameters @@ -133,7 +133,7 @@ Endpoint: `/curb/policy` Method: `GET` `data` Payload: a JSON object with a `policies` field containing an array of [Curb Policy](#policy) objects. -_Optional endpoint, but required if Curb Zones contain policy_id references; if not implemented, the server should reply with `501 Not Implemented`._ +_Optional endpoint, but required if Curb Zones contain policy_id references. If not implemented, the server should reply with `501 Not Implemented`._ ### Query Parameters @@ -151,7 +151,7 @@ Endpoint: `/curbs/zone/` Method: `GET` `data` Payload: the [Curb Zone](#curb-zone) object with the ID provided in the path. -_Optional endpoint; if not implemented, the server should reply with `501 Not Implemented`._ +_Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._ ### Query Parameters @@ -170,7 +170,7 @@ Endpoint: `/curbs/area/` Method: `GET` `data` Payload: the [Curb Area](#curb-area) object with the ID provided in the path. -_Optional endpoint; if not implemented, the server should reply with `501 Not Implemented`._ +_Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._ ### Query Parameters @@ -184,6 +184,8 @@ Endpoint: `/curbs/space/` Method: `GET` `data` Payload: the [Curb Space](#curb-space) object with the ID provided in the path. +_Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._ + ### Query Parameters All query parameters are optional. From a1eb0ee503fb7f49adfa40223038db4ae8f392e5 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 17 Jan 2022 11:07:28 -0500 Subject: [PATCH 127/173] Removed policies from curb zone example --- curbs/examples.md | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/curbs/examples.md b/curbs/examples.md index ce8af600..ed3111aa 100644 --- a/curbs/examples.md +++ b/curbs/examples.md @@ -9,11 +9,11 @@ This file presents a series of CDS [Curbs](/curbs) endpoint examples to use as t ## Curb Zones Minimum -A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with minimum required fields returned, plus a max parking stay of 60 minutes, and some parameters passed in. +A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with minimum required fields returned, and some parameters passed in. **Query**: -`/curbs/zone?include_geometry=true&include_policies=true×tamp=1552678594427` +`/curbs/zone?include_geometry=true×tamp=1552678594427` **Payload**: @@ -47,19 +47,6 @@ A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with mini "last_updated_date": 1552678594428, "start_date": 1552678594428 } - ], - "policies": [ - { - "curb_policy_id": "cd0996d7-3765-4f0b-a72e-7caf7cf3fe21", - "published_date": 1552678594428, - "priority": 1, - "rules": [ - { - "activity": "parking", - "max_stay": 60 - } - ] - } ] } ] From 798b23d98344ecd4ea410f9b225b2d36420047a0 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 17 Jan 2022 11:40:46 -0500 Subject: [PATCH 128/173] Added links to privacy guidance for 3 fields --- events/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/events/README.md b/events/README.md index bf71a21a..fc6e2ab4 100644 --- a/events/README.md +++ b/events/README.md @@ -107,13 +107,13 @@ A Curb Event is represented as a JSON object, whose fields are as follows: | `data_source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | | `data_source_operator_id` | [UUID][uuid] | Conditionally Required | Unique identifier of the entity responsible for operating the event data source. IDs can identify the fleet operator sending a data feed, or the organization (company or city) operating the sensor. IDs for fleet operators are required and global and come from the [data_source_operators.csv](/data_source_operators.csv) file, and optional for others. Read our [How to Get a Data Source Operator ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Data-Source-Operator-ID) guide. An agency at their discretion may allow a small, local company to simply provide a consistent `data_source_operator_name` string instead of this field, otherwise this field is required. | | `data_source_operator_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `data_source_operator_id` or on its own for small operators at the discretion of the city. | -| `data_source_device_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as the external `vehicle_id`. | +| `data_source_device_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as the external `vehicle_id`. If this field is needed for your use cases, review our [Privacy Guidance](/README.md#data-privacy). | | `data_source_manufacturer` | String | Optional | Manufacturer of the data source hardware or vehicle reporting event data. | | `data_source_model` | String | Optional | Model of the data source hardware or vehicle reporting event data. | | `sensor_status_is_commissioned` | Boolean | Optional | If a sensor was used to capture this event, the commissioned status at the time that the event was reported. Indicates whether the sensor is currently in a state where it should be reporting data. | | `sensor_status_is_online` | Boolean | Optional | If a sensor was used to capture this event, the online status at the time that the event was reported. Indicates whether the sensor is currently online and reporting data. | -| `vehicle_id` | String | Optional | A vehicle identifier visible externally on the vehicle itself. | -| `vehicle_license_plate` | String | Optional | The consistently placed vehicle license plate, usable by ALPR systems, when required for curb use. This field is potentially sensitive (depending on local, state, and national laws) and a data privacy framework is recommended for collecting, retention, deletion, obfuscation, and security. | +| `vehicle_id` | String | Optional | A vehicle identifier visible externally on the vehicle itself. If this field is needed for your use cases, review our [Privacy Guidance](/README.md#data-privacy). | +| `vehicle_license_plate` | String | Optional | The consistently placed vehicle license plate, usable by ALPR systems, when required for curb use. This field is potentially sensitive (depending on local, state, and national laws) and a data privacy framework is recommended for collecting, retention, deletion, obfuscation, and security. If this field is needed for your use cases, review our [Privacy Guidance](/README.md#data-privacy). | | `vehicle_permit_number` | String | Optional | If applicable, the assigned permit number for this vehicle from the city agency. | | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | | `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | From 1a5ef9707a5fb6a1172561b57c4c46cffb038248 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 17 Jan 2022 11:45:50 -0500 Subject: [PATCH 129/173] Added privacy link to Metrics --- metrics/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/metrics/README.md b/metrics/README.md index 04835bf3..eeb2c868 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -46,7 +46,7 @@ header but does not include this value; it MUST respond with a status of `406 No ## Authorization -[Authorization](/general-information.md#authorization) is **optionally required** for all the Metrics endpoints, since depending on implementation, use cases, fields required, local laws, and audience it may contain information only city transportation agencies should have access to. It is recommended to authenticate when in doubt, though the information in [Query Aggregate](#query-aggregate) is aggregated report level data suitable for data analysis and public release. +[Authorization](/general-information.md#authorization) is **optionally required** for all the Metrics endpoints, since depending on implementation, use cases, fields required, local laws, and audience it may contain information only city transportation agencies should have access to. It is recommended to authenticate when in doubt, though the information in [Query Aggregate](#query-aggregate) is aggregated report level data suitable for data analysis and public release. Review our [Privacy Guidance](/README.md#data-privacy) for more details. [Top][toc] From d41f4068b3598823edef82539c10ebfa7fbc0a4a Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 18 Jan 2022 10:40:00 -0500 Subject: [PATCH 130/173] New images and link to website --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c3f781f6..25e50a84 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,9 @@ The Curb Data Specification (**CDS**), a project of the [Open Mobility Foundatio Urban curb is a valuable, limited, and often under-managed part of the public right of way. Curb demand is growing, including from commercial activity like passenger pickup/drop off, traditional and on-demand delivery services, new mobility programs like scooters, bikeshare, and carshare, and goods and freight delivery. While cities have made some progress in digitizing their curb and using curb data, more tools are needed to proactively manage curbs and sidewalks, and to deliver more public value from this scarce resource. Curb data standards can provide a mechanism for expressing static and dynamic regulations, measuring activity at the curb, and developing policies that create more accessible, useful curbs. -![Curb Data Specification Logo](https://i.imgur.com/dc855VZ.png) +**CDS** is a key piece of digital infrastructure that supports the effective implementation of curb policies in cities and for curb users. For a high level overview and visuals, see the **[About CDS](https://www.openmobilityfoundation.org/about-cds/) page** on the OMF website. + +![Curb Data Specification Logo](https://i.imgur.com/pj3ig4F.png) [Top][toc] @@ -46,7 +48,7 @@ Many parts of the CDS definitions and APIs align across each other. In these cas CDS contains a series of connected endpoints and fields beneath each interconnected API. -

          +

          ## Modularity From 33b7b1cd082d9782240a8a5ee20a701647545a65 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 18 Jan 2022 10:42:27 -0500 Subject: [PATCH 131/173] Updated CDS logo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 25e50a84..2a7a7b78 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Urban curb is a valuable, limited, and often under-managed part of the public ri **CDS** is a key piece of digital infrastructure that supports the effective implementation of curb policies in cities and for curb users. For a high level overview and visuals, see the **[About CDS](https://www.openmobilityfoundation.org/about-cds/) page** on the OMF website. -![Curb Data Specification Logo](https://i.imgur.com/pj3ig4F.png) +![Curb Data Specification Logo](https://i.imgur.com/pvZZQF4.png) [Top][toc] From 6505a7046cf18665a9d3a7136c80c0976cc508e2 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 18 Jan 2022 11:25:13 -0500 Subject: [PATCH 132/173] Fixed timestamp -> time --- curbs/examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/curbs/examples.md b/curbs/examples.md index ed3111aa..f3cc7973 100644 --- a/curbs/examples.md +++ b/curbs/examples.md @@ -13,7 +13,7 @@ A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with mini **Query**: -`/curbs/zone?include_geometry=true×tamp=1552678594427` +`/curbs/zone?include_geometry=true&time=1552678594427` **Payload**: From 84aa866780bd4d61350f3a23a06f9252ad7914df Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Jan 2022 13:17:12 -0500 Subject: [PATCH 133/173] Added unloading to activities --- curbs/README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index bccc4307..fedfcd55 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -366,12 +366,14 @@ for instance, implies that the Curb Zone does allow loading at the time in quest - `parking` - implies that loading and stopping are also permitted - `no parking` - may not stop and leave vehicle unattended -- `loading` - of goods; implies that stopping is also permitted -- `no loading` - implies that parking is also prohibited +- `loading` - loading of goods; implies that stopping is also permitted +- `no loading` - no loading allowed; implies that parking is also prohibited +- `unloading` - unloading of goods; implies that stopping is also permitted +- `no unloading` - no unloading allowed; implies that parking is also prohibited - `stopping` - stopping briefly to pick up or drop off passengers -- `no stopping` - stopping, loading, and parking are all prohibited +- `no stopping` - stopping, loading, unloading, and parking are all prohibited; not a typical travel lane - `travel` - represents curbside lanes intended for moving vehicles, like bus lanes, bike lanes, - and rush-hour-only travel lanes; implies that parking, loading, and stopping are prohibited. + and rush-hour-only travel lanes; implies that parking, loading, unloading, and stopping are prohibited. [Top][toc] From 16738f139e45635a726cdb7156cc5868d3544e1e Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Jan 2022 13:28:25 -0500 Subject: [PATCH 134/173] Link to parameters --- curbs/examples.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/curbs/examples.md b/curbs/examples.md index f3cc7973..3c0e3484 100644 --- a/curbs/examples.md +++ b/curbs/examples.md @@ -9,7 +9,7 @@ This file presents a series of CDS [Curbs](/curbs) endpoint examples to use as t ## Curb Zones Minimum -A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with minimum required fields returned, and some parameters passed in. +A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with minimum required fields returned, and some [query parameters](/curbs/README.md#query-parameters) passed in. **Query**: @@ -57,7 +57,7 @@ A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with mini ## Curb Policies -A [Query Curb Policies](https://github.com/openmobilityfoundation/curb-data-specification/tree/feature-release-work-1/curbs#query-curb-policies) example of `/curbs/policy` showing policies giving 3 fleet operators using electric vehicles operating rideshare curb access for max 15 minute drop-offs on weekdays from 10am to 4pm, other commerical activity for up to 60 minutes between 8am and 10pm, but otherwise no stopping (eg overnight). No query parameters passed in. +A [Query Curb Policies](https://github.com/openmobilityfoundation/curb-data-specification/tree/feature-release-work-1/curbs#query-curb-policies) example of `/curbs/policy` showing policies giving 3 fleet operators using electric vehicles operating rideshare curb access for max 15 minute drop-offs on weekdays from 10am to 4pm, other commerical activity for up to 60 minutes between 8am and 10pm, but otherwise no stopping (eg overnight). No [query parameters](/curbs/README.md#query-parameters) passed in. **Query**: From ceebd64bba1909b4b1ecfdfa02ac6af64cbd15f3 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Jan 2022 13:53:30 -0500 Subject: [PATCH 135/173] Refresh on Events description --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2a7a7b78..95b0149d 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ CDS is at its core a set of Application Programming Interfaces (APIs) and endpoi | API | Description | |---|---| | **[Curbs](/curbs)** | A standard way for cities to digitally publish curb locations and regulations, which can be shared with the public and with companies using curb space. | -| **[Events](/events)** | A standard way to transmit real-time and historic commercial events happening at the curb to cities. Event data can be derived from company data feeds, sensors, payments, check-ins, enforcement, and other city data sources. | +| **[Events](/events)** | A standard way to transmit real-time and historic commercial events happening at the curb to cities. Event data can be derived from company data feeds, on street sensors, session payments, company check-ins, in-person parking personnel, and/or other city data sources. | | **[Metrics](/metrics)** | Track curb usage session details and define common calculation methodologies to measure historic dwell time, occupancy, usage and other aggregated statistics. | CDS is a data exchange format and a translation layer between internal systems and external entities using data feeds. It is not expected that CDS will be the format used internally to store curb regulations in a city. The internal storage format is something different, and a subset of that data should be able to be converted to CDS for publishing out to the public and curb users. From 92942dbbc728c02bfe7c7e6a8b85ac619caf3186 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Jan 2022 13:54:04 -0500 Subject: [PATCH 136/173] Update to events description --- events/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index fc6e2ab4..54de8128 100644 --- a/events/README.md +++ b/events/README.md @@ -1,6 +1,6 @@ # Curb Data Specification: Events API -The Events API is a REST API allowing real-time and historic events at the curb to be sent to cities, and the ability to check on the status of any sensors. Events can come from company data feeds, sensors, payments, check-ins, enforcement, and/or other city data sources. Data sent in the Events API can be connected to the Curbs API over time and space, and events are used for calculations in the Metrics API. +The Events API is a REST API allowing real-time and historic events at the curb to be sent to cities, and the ability to check on the status of any sensors. Events can come from company data feeds, on street sensors, session payments, company check-ins, in-person parking personnel, and/or other city data sources. Data sent in the Events API can be connected to the Curbs API over time and space, and events are used for calculations in the Metrics API. **See [other CDS APIs](/README.md#curb-data-specification-apis) on the homepage.** From ef1191841153a5717464434abcd5b2e75c6193db Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Jan 2022 14:52:26 -0500 Subject: [PATCH 137/173] Link to parameters --- events/examples.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/events/examples.md b/events/examples.md index c223ad20..232df1be 100644 --- a/events/examples.md +++ b/events/examples.md @@ -9,7 +9,7 @@ This file presents a series of CDS [Events](/events) endpoint examples to use as ## Curb Event Minimum -A [Query Event](/events#query-event) example of `/events/event` with minimum required fields showing the start of a `park_start` event at a specific curb zone detected by an above ground sensor, and no parameters passed in. +A [Query Event](/events#query-event) example of `/events/event` with minimum required fields showing the start of a `park_start` event at a specific curb zone detected by an above ground sensor, and no [query parameters](/events#query-parameters) passed in. **Query**: @@ -53,7 +53,7 @@ A [Query Event](/events#query-event) example of `/events/event` with minimum req ## Fleet Operator -A [Query Event](/events#query-event) example of `/events/event` from a fleet operator's data feed with many optional fields showing the start of a `park_start` with event details and vehicle properties, and the curb_zone_id parameter passed in. +A [Query Event](/events#query-event) example of `/events/event` from a fleet operator's data feed with many optional fields showing the start of a `park_start` with event details and vehicle properties, and the curb_zone_id [query parameter](/events#query-parameters) passed in. **Query**: From 21938500c65a05ed36183d7271d5e78a48a2d291 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 15:59:36 -0500 Subject: [PATCH 138/173] Parameters link in Metrics --- metrics/examples.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/metrics/examples.md b/metrics/examples.md index f39c4dc6..d8ca0a5d 100644 --- a/metrics/examples.md +++ b/metrics/examples.md @@ -9,7 +9,7 @@ This file presents a series of CDS [Metrics](/metrics) endpoint examples to use ## Dynamic Sessions -A [Query Session](/metrics#query-session) example of `/metrics/session` with all fields returned for parking events in a specific zone over a short time period. Dynamic endpoint with parameters passed in. +A [Query Session](/metrics#query-session) example of `/metrics/session` with all fields returned for parking events in a specific zone over a short time period. Dynamic endpoint with [query parameters](/metrics#query-parameters) passed in. **Query**: @@ -29,7 +29,7 @@ parking,35c923fd-78f5-471d-a548-efb0dabca3b7,c702915e-9b2e-45a5-ab30-f4413cdb1a1 ## Static Aggregate Metrics -A [Query Aggregate](/metrics#query-aggregate) example of `/metrics/aggregate` that collects 2 aggregate metrics in 2 places over a 1 day period. Static endpoint so no parameters passed in. +A [Query Aggregate](/metrics#query-aggregate) example of `/metrics/aggregate` that collects 2 aggregate metrics in 2 places over a 1 day period. Static endpoint, so no [query parameters](/metrics#query-parameters) passed in. **Query**: From c66146e432d1d3ece8b678ecd08871780813b87f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 16:01:30 -0500 Subject: [PATCH 139/173] Links to paramaters in Curbs example --- curbs/examples.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/curbs/examples.md b/curbs/examples.md index 3c0e3484..d29d19fa 100644 --- a/curbs/examples.md +++ b/curbs/examples.md @@ -9,7 +9,7 @@ This file presents a series of CDS [Curbs](/curbs) endpoint examples to use as t ## Curb Zones Minimum -A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with minimum required fields returned, and some [query parameters](/curbs/README.md#query-parameters) passed in. +A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with minimum required fields returned, and some [query parameters](/curbs#query-parameters) passed in. **Query**: @@ -57,7 +57,7 @@ A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with mini ## Curb Policies -A [Query Curb Policies](https://github.com/openmobilityfoundation/curb-data-specification/tree/feature-release-work-1/curbs#query-curb-policies) example of `/curbs/policy` showing policies giving 3 fleet operators using electric vehicles operating rideshare curb access for max 15 minute drop-offs on weekdays from 10am to 4pm, other commerical activity for up to 60 minutes between 8am and 10pm, but otherwise no stopping (eg overnight). No [query parameters](/curbs/README.md#query-parameters) passed in. +A [Query Curb Policies](https://github.com/openmobilityfoundation/curb-data-specification/tree/feature-release-work-1/curbs#query-curb-policies) example of `/curbs/policy` showing policies giving 3 fleet operators using electric vehicles operating rideshare curb access for max 15 minute drop-offs on weekdays from 10am to 4pm, other commerical activity for up to 60 minutes between 8am and 10pm, but otherwise no stopping (eg overnight). No [query parameters](/curbs#query-parameters-3) passed in. **Query**: From 88beb75ea5cf474f8265da07f4742c141e9f5aea Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 16:18:06 -0500 Subject: [PATCH 140/173] Changed endpoints to plural: Curbs --- curbs/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index fedfcd55..65f4403f 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -67,7 +67,7 @@ All endpoints return a JSON object containing the fields as specified in the [RE ## Query Curb Zones -Endpoint: `/curbs/zone` +Endpoint: `/curbs/zones` Method: `GET` `data` Payload: a JSON object with a `zones` field containing an array of [Curb Zone](#curb-zone) objects. @@ -89,7 +89,7 @@ All query parameters are optional. ## Query Curb Areas -Endpoint: `/curbs/area` +Endpoint: `/curbs/areas` Method: `GET` `data` Payload: a JSON object with an `areas` field containing an array of [Curb Area](#curb-area) objects. @@ -108,7 +108,7 @@ All query parameters are optional. ## Query Curb Spaces -Endpoint: `/curbs/space` +Endpoint: `/curbs/spaces` Method: `GET` `data` Payload: a JSON object with a `spaces` field containing an array of [Curb Space](#curb-space) objects. @@ -129,7 +129,7 @@ All query parameters are optional. ## Query Curb Policies -Endpoint: `/curb/policy` +Endpoint: `/curb/policies` Method: `GET` `data` Payload: a JSON object with a `policies` field containing an array of [Curb Policy](#policy) objects. @@ -147,7 +147,7 @@ All query parameters are optional. ## Fetch a Curb Zone -Endpoint: `/curbs/zone/` +Endpoint: `/curbs/zones/` Method: `GET` `data` Payload: the [Curb Zone](#curb-zone) object with the ID provided in the path. @@ -166,7 +166,7 @@ All query parameters are optional. ## Fetch a Curb Area -Endpoint: `/curbs/area/` +Endpoint: `/curbs/areas/` Method: `GET` `data` Payload: the [Curb Area](#curb-area) object with the ID provided in the path. @@ -180,7 +180,7 @@ This endpoint takes no query parameters. ## Fetch a Curb Space -Endpoint: `/curbs/space/` +Endpoint: `/curbs/spaces/` Method: `GET` `data` Payload: the [Curb Space](#curb-space) object with the ID provided in the path. @@ -198,7 +198,7 @@ All query parameters are optional. ## Fetch a Curb Policy -Endpoint: `/curb/policy/` +Endpoint: `/curb/policies/` Method: `GET` `data` Payload: the [Curb Policy](#policy) object with the ID provided in the path. From 72565440921e7d504fcbeba0276bab9b415a48fe Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 16:19:19 -0500 Subject: [PATCH 141/173] Changed endpoints to plural: Curbs examples --- curbs/examples.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/curbs/examples.md b/curbs/examples.md index d29d19fa..cd2d1f15 100644 --- a/curbs/examples.md +++ b/curbs/examples.md @@ -9,11 +9,11 @@ This file presents a series of CDS [Curbs](/curbs) endpoint examples to use as t ## Curb Zones Minimum -A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with minimum required fields returned, and some [query parameters](/curbs#query-parameters) passed in. +A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zones` with minimum required fields returned, and some [query parameters](/curbs#query-parameters) passed in. **Query**: -`/curbs/zone?include_geometry=true&time=1552678594427` +`/curbs/zones?include_geometry=true&time=1552678594427` **Payload**: @@ -57,11 +57,11 @@ A [Query Curb Zones](/curbs#query-curb-zones) example of `/curbs/zone` with mini ## Curb Policies -A [Query Curb Policies](https://github.com/openmobilityfoundation/curb-data-specification/tree/feature-release-work-1/curbs#query-curb-policies) example of `/curbs/policy` showing policies giving 3 fleet operators using electric vehicles operating rideshare curb access for max 15 minute drop-offs on weekdays from 10am to 4pm, other commerical activity for up to 60 minutes between 8am and 10pm, but otherwise no stopping (eg overnight). No [query parameters](/curbs#query-parameters-3) passed in. +A [Query Curb Policies](https://github.com/openmobilityfoundation/curb-data-specification/tree/feature-release-work-1/curbs#query-curb-policies) example of `/curbs/policies` showing policies giving 3 fleet operators using electric vehicles operating rideshare curb access for max 15 minute drop-offs on weekdays from 10am to 4pm, other commerical activity for up to 60 minutes between 8am and 10pm, but otherwise no stopping (eg overnight). No [query parameters](/curbs#query-parameters-3) passed in. **Query**: -`/curbs/policy` +`/curbs/policies` **Payload**: From 8f029322847eeacb2e6804aaf4d1744abdaddde1 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 16:20:13 -0500 Subject: [PATCH 142/173] Changed endpoints to plural: Events --- events/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index 54de8128..9d3b7610 100644 --- a/events/README.md +++ b/events/README.md @@ -45,7 +45,7 @@ All endpoints return a JSON object containing the fields as specified in the [RE ## Query Event -Endpoint: `/events/event` +Endpoint: `/events/events` Method: `GET` `data` Payload: a JSON object with the following fields: - `events`: an array of [Curb Event](#curb-event) objects. See [Event Times](/general-information.md#event-times) guidance about the order of data returned. From 988ff82f0c1e21f981ad66690d8818f689346238 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 16:20:52 -0500 Subject: [PATCH 143/173] Changed endpoints to plural: Events examples --- events/examples.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/events/examples.md b/events/examples.md index 232df1be..691a8fcd 100644 --- a/events/examples.md +++ b/events/examples.md @@ -9,11 +9,11 @@ This file presents a series of CDS [Events](/events) endpoint examples to use as ## Curb Event Minimum -A [Query Event](/events#query-event) example of `/events/event` with minimum required fields showing the start of a `park_start` event at a specific curb zone detected by an above ground sensor, and no [query parameters](/events#query-parameters) passed in. +A [Query Event](/events#query-event) example of `/events/events` with minimum required fields showing the start of a `park_start` event at a specific curb zone detected by an above ground sensor, and no [query parameters](/events#query-parameters) passed in. **Query**: -`/events/event` +`/events/events` **Payload**: @@ -53,11 +53,11 @@ A [Query Event](/events#query-event) example of `/events/event` with minimum req ## Fleet Operator -A [Query Event](/events#query-event) example of `/events/event` from a fleet operator's data feed with many optional fields showing the start of a `park_start` with event details and vehicle properties, and the curb_zone_id [query parameter](/events#query-parameters) passed in. +A [Query Event](/events#query-event) example of `/events/events` from a fleet operator's data feed with many optional fields showing the start of a `park_start` with event details and vehicle properties, and the curb_zone_id [query parameter](/events#query-parameters) passed in. **Query**: -`/events/event?curb_zone_id=02885f6f-ef93-441b-9e74-487279380656` +`/events/events?curb_zone_id=02885f6f-ef93-441b-9e74-487279380656` **Payload**: From 5c44ecba25edfc5af919ef3bfe58c5e8a02839d0 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 16:21:33 -0500 Subject: [PATCH 144/173] Changed endpoints to plural: Metrics --- metrics/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index eeb2c868..9df4664a 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -69,7 +69,7 @@ The agency serving the data may choose how frequently they want to update the da ## Query Session -Endpoint: `/metrics/session` +Endpoint: `/metrics/sessions` Method: `GET` `data` Payload: a CSV object with the following fields: - `session`: an array of [Session](#session) objects @@ -93,7 +93,7 @@ An agency may choose to make this endpoint static (and return all the available ## Query Aggregate -Endpoint: `/metrics/aggregate` +Endpoint: `/metrics/aggregates` Method: `GET` `data` Payload: a CSV object with the following fields: - `aggregate`: an array of [Aggregate](#aggregate) objects From a0bfaaf456687ec1445a61873f727c4459b64546 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 16:24:49 -0500 Subject: [PATCH 145/173] Changed endpoints to plural: Metrics examples --- metrics/examples.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/metrics/examples.md b/metrics/examples.md index d8ca0a5d..a5784718 100644 --- a/metrics/examples.md +++ b/metrics/examples.md @@ -9,11 +9,11 @@ This file presents a series of CDS [Metrics](/metrics) endpoint examples to use ## Dynamic Sessions -A [Query Session](/metrics#query-session) example of `/metrics/session` with all fields returned for parking events in a specific zone over a short time period. Dynamic endpoint with [query parameters](/metrics#query-parameters) passed in. +A [Query Session](/metrics#query-session) example of `/metrics/sessions` with all fields returned for parking events in a specific zone over a short time period. Dynamic endpoint with [query parameters](/metrics#query-parameters) passed in. **Query**: -`/metrics/session?curb_place_type=zone&curb_place_id=d3c862b1-5404-4635-a90b-056537c50e81&start_time=1641738460&end_time=1642119064` +`/metrics/sessions?curb_place_type=zone&curb_place_id=d3c862b1-5404-4635-a90b-056537c50e81&start_time=1641738460&end_time=1642119064` **Payload**: @@ -29,11 +29,11 @@ parking,35c923fd-78f5-471d-a548-efb0dabca3b7,c702915e-9b2e-45a5-ab30-f4413cdb1a1 ## Static Aggregate Metrics -A [Query Aggregate](/metrics#query-aggregate) example of `/metrics/aggregate` that collects 2 aggregate metrics in 2 places over a 1 day period. Static endpoint, so no [query parameters](/metrics#query-parameters) passed in. +A [Query Aggregate](/metrics#query-aggregate) example of `/metrics/aggregates` that collects 2 aggregate metrics in 2 places over a 1 day period. Static endpoint, so no [query parameters](/metrics#query-parameters) passed in. **Query**: -`/metrics/aggregate` +`/metrics/aggregates` **Payload**: From 7dcc548c1498e9231b5015c3afe716ed8e1627f9 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 16:29:08 -0500 Subject: [PATCH 146/173] Fixed /curb api typos --- curbs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 65f4403f..89e632c0 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -129,7 +129,7 @@ All query parameters are optional. ## Query Curb Policies -Endpoint: `/curb/policies` +Endpoint: `/curbs/policies` Method: `GET` `data` Payload: a JSON object with a `policies` field containing an array of [Curb Policy](#policy) objects. @@ -198,7 +198,7 @@ All query parameters are optional. ## Fetch a Curb Policy -Endpoint: `/curb/policies/` +Endpoint: `/curbs/policies/` Method: `GET` `data` Payload: the [Curb Policy](#policy) object with the ID provided in the path. From 2b8e0f0af815989cdeb3af2d693589d8b58f20c1 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 16:35:00 -0500 Subject: [PATCH 147/173] Create pull_request_template.md --- .../pull_request_template.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE/pull_request_template.md diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md new file mode 100644 index 00000000..6dfeffe8 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -0,0 +1,41 @@ +--- +name: Default +about: Suggest changes to CDS +title: + +--- + +# CDS Pull Request + +Thank you for your contribution! Please review our OMF [contributing page](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) to understand guidelines and policies for participation, and our [Code of Conduct page](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md). + +To avoid complications and help make the Review process as smooth as possible, make sure to: + +1. Target [**`dev`**](https://github.com/openmobilityfoundation/curb-data-specification/tree/dev) branch. Please ensure you are targeting **`dev`**, not **`main`**. +1. Keep the *"Allow edits from maintainers"* button checked to help us resolve some issues for you. +1. Be ready to resolve any merge conflicts before we approve your Pull Request. +1. Have an up to date profile, per our Github [community profile](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md#community-profile) guildance. + +## Explain pull request + +Please provide a clear and concise reason for this pull request and the impact of the change + +## Is this a breaking change + +A breaking change would require consumers or implementors of the API to modify their code for it to continue to function (ex: renaming of a required field or the change in data type of an existing field). A non-breaking change would allow existing code to continue to function (ex: addition of an optional field or the creation of a new optional endpoint). + +* Yes, breaking +* No, not breaking +* I'm not sure + +## Impacted Spec + +Which API(s) will this pull request impact? + +* `Curbs` +* `Events` +* `Metrics` + +## Additional context + +Add any other context or screenshots about the feature request here. From dc809b92e67f22454feaceea52094f1727d3b5b9 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 16:36:09 -0500 Subject: [PATCH 148/173] Create release-candidate.md --- .../PULL_REQUEST_TEMPLATE/release-candidate.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE/release-candidate.md diff --git a/.github/PULL_REQUEST_TEMPLATE/release-candidate.md b/.github/PULL_REQUEST_TEMPLATE/release-candidate.md new file mode 100644 index 00000000..5fb3bfba --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/release-candidate.md @@ -0,0 +1,17 @@ +--- +name: Release Candidate +about: Initiate discussion to obtain OMF approval for new release +title: Release Candidate [X.Y.Z] +labels: admin + +--- + +### Summary + +The Release Candidate for CDS `X.Y.Z` has been submitted: + +Please use this pull request to track Technology Council and OMF Board feedback and/or requested changes. + +### Action Item + +This pull request will be merged by an OMF maintainer after OMF Board Approval following the [Release Guidelines](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md#making-a-release). From 82acf1604b4850e8c5b852600185644183bf58dd Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 17:00:53 -0500 Subject: [PATCH 149/173] Added more vehicle properties --- curbs/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/curbs/README.md b/curbs/README.md index 89e632c0..e35e8c0b 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -415,6 +415,7 @@ Vehicle properties - `electric_assist` - `electric` - `combustion` +- `autonomous` Purpose - `construction` @@ -429,6 +430,7 @@ Purpose - `special_events` - `taxi` - `utilities` +- `vending` - `waste_management` [Top][toc] From e3a89346240c8ea1e8609b7dab23608c39244f76 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 20 Jan 2022 17:04:26 -0500 Subject: [PATCH 150/173] Added new event purposes --- events/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/events/README.md b/events/README.md index 9d3b7610..69c55b02 100644 --- a/events/README.md +++ b/events/README.md @@ -207,6 +207,7 @@ General event purpose `event_purpose` that the vehicle performed during its even | `special_events` | Includes unloading equipment for concerts, theatre, street events | | `waste_management` | Retrieval/disposal of waste | | `device_maintenance` | Includes scooter pickup, drop off, battery swapping | +| `autonomous` | Autonomous vehicle use | | `ems` | Emergency medical vehicle use | | `fire` | Emergency fire vehicle | | `food_delivery` | Delivery of food items ready for consumption to an end consumer | @@ -220,6 +221,7 @@ General event purpose `event_purpose` that the vehicle performed during its even | `utility_work` | Includes public sector activity like sewer, water, telecoms | | `vehicle_charging` | Parking for electric vehicles to charge | | `vehicle_parking` | Includes private or commercial vehicle free or paid/metered parking | +| `vending` | Mobile vending or food truck curb uses | | `unspecified` | Unknown or unspecified activity type | [Top][toc] From ef0873bdd44f398e670108ba459a9b6d98943772 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 21 Jan 2022 11:20:12 -0500 Subject: [PATCH 151/173] Added CDS icons --- README.md | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 95b0149d..60dc39a9 100644 --- a/README.md +++ b/README.md @@ -32,13 +32,28 @@ Urban curb is a valuable, limited, and often under-managed part of the public ri # Curb Data Specification APIs -CDS is at its core a set of Application Programming Interfaces (APIs) and endpoints within those APIs, which allow information to flow between organizations managing and using curb places. It includes the following APIs and their associated endpoints: +CDS is at its core a set of Application Programming Interfaces (APIs) and endpoints within those APIs, which allow information to flow between organizations managing and using curb places. It includes the following three APIs, with multiple endpoints under each API: + +--- + +CDS Curbs Icon + +The [`Curbs`](/curbs/) API is a standard way for cities to digitally publish curb locations and regulations, which can be shared with the public and with companies using curb space. It defines curb policies, curb zones, spaces in zones, and areas around curbs. + +--- + +CDS Events Icon + +The [`Events`](/events/) API is a standard way to transmit real-time and historic commercial events happening at the curb to cities. Event data can be derived from company data feeds, on street sensors, session payments, company check-ins, in-person parking personnel, and/or other city data sources. + +--- + +CDS Metrics Icon + +The [`Metrics`](/metrics/) API is a way to track curb usage session details and define common calculation methodologies to measure historic dwell time, occupancy, usage and other aggregated statistics. It defines sessions and aggregates derived from Events. + +--- -| API | Description | -|---|---| -| **[Curbs](/curbs)** | A standard way for cities to digitally publish curb locations and regulations, which can be shared with the public and with companies using curb space. | -| **[Events](/events)** | A standard way to transmit real-time and historic commercial events happening at the curb to cities. Event data can be derived from company data feeds, on street sensors, session payments, company check-ins, in-person parking personnel, and/or other city data sources. | -| **[Metrics](/metrics)** | Track curb usage session details and define common calculation methodologies to measure historic dwell time, occupancy, usage and other aggregated statistics. | CDS is a data exchange format and a translation layer between internal systems and external entities using data feeds. It is not expected that CDS will be the format used internally to store curb regulations in a city. The internal storage format is something different, and a subset of that data should be able to be converted to CDS for publishing out to the public and curb users. From 9757a35409c5295284ce0cb9f671c63b13a4d101 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 21 Jan 2022 11:30:48 -0500 Subject: [PATCH 152/173] Added to API text --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 60dc39a9..349021d1 100644 --- a/README.md +++ b/README.md @@ -38,19 +38,19 @@ CDS is at its core a set of Application Programming Interfaces (APIs) and endpoi CDS Curbs Icon -The [`Curbs`](/curbs/) API is a standard way for cities to digitally publish curb locations and regulations, which can be shared with the public and with companies using curb space. It defines curb policies, curb zones, spaces in zones, and areas around curbs. +The [`Curbs`](/curbs/) API is a standard way for cities to digitally publish curb locations and regulations, which can be shared with the public and with companies using curb space. It defines curb policies, curb zones, spaces in zones, and areas around curbs, and is used by Events and Metrics. --- CDS Events Icon -The [`Events`](/events/) API is a standard way to transmit real-time and historic commercial events happening at the curb to cities. Event data can be derived from company data feeds, on street sensors, session payments, company check-ins, in-person parking personnel, and/or other city data sources. +The [`Events`](/events/) API is a standard way to transmit real-time and historic commercial events happening at the curb to cities. Event data can be derived from company data feeds, on street sensors, session payments, company check-ins, in-person parking personnel, and/or other city data sources. Connected to Curbs and used by Metrics. --- CDS Metrics Icon -The [`Metrics`](/metrics/) API is a way to track curb usage session details and define common calculation methodologies to measure historic dwell time, occupancy, usage and other aggregated statistics. It defines sessions and aggregates derived from Events. +The [`Metrics`](/metrics/) API is a way to track curb usage session details and define common calculation methodologies to measure historic dwell time, occupancy, usage and other aggregated statistics. It defines sessions and aggregates data derived from raw Events data. --- From cd09664afe170fc2817f3c9543c08d6b68b1dcb7 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 21 Jan 2022 11:33:11 -0500 Subject: [PATCH 153/173] Added Curbs Icon --- curbs/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/curbs/README.md b/curbs/README.md index e35e8c0b..8cddccf9 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -1,5 +1,7 @@ # Curb Data Specification: Curbs API +CDS Curbs Icon + The Curbs API is a REST API allowing cities to specify areas of interest along the curb along with the rules for using them: who is allowed to park, load, unload, pick up, drop off, etc., for how long, for what price (if any), at what times, and on which days. Locations defined in the From d9c67b4d787c089255373e5f1372820f64ea3dcb Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 21 Jan 2022 11:33:45 -0500 Subject: [PATCH 154/173] Added Events Icon --- events/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/events/README.md b/events/README.md index 69c55b02..4118def8 100644 --- a/events/README.md +++ b/events/README.md @@ -1,5 +1,7 @@ # Curb Data Specification: Events API +CDS Events Icon + The Events API is a REST API allowing real-time and historic events at the curb to be sent to cities, and the ability to check on the status of any sensors. Events can come from company data feeds, on street sensors, session payments, company check-ins, in-person parking personnel, and/or other city data sources. Data sent in the Events API can be connected to the Curbs API over time and space, and events are used for calculations in the Metrics API. **See [other CDS APIs](/README.md#curb-data-specification-apis) on the homepage.** From 5e055788dc7ca18a0e73945a33d1d0dd03ecc884 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 21 Jan 2022 11:34:55 -0500 Subject: [PATCH 155/173] Added Metrics Icon --- metrics/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/metrics/README.md b/metrics/README.md index 9df4664a..c1946dbb 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -1,6 +1,8 @@ # Curb Data Specification: Metrics API -The Metrics API is a REST API allowing historic metrics calculations based on Event activity that happened at defined Curb places. +CDS Metrics Icon + +The Metrics API is a REST API allowing historic metrics calculations based on Event activity that happened at defined Curb places. Defines common calculation methodologies to measure historic dwell time, occupancy, usage and other aggregated statistics. **See [other CDS APIs](/README.md#curb-data-specification-apis) on the homepage.** From b70f6fb7af71af7512bde782bf522b14cc5c36ab Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 21 Jan 2022 13:59:22 -0500 Subject: [PATCH 156/173] Create ReleaseNotes.md --- ReleaseNotes.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 ReleaseNotes.md diff --git a/ReleaseNotes.md b/ReleaseNotes.md new file mode 100644 index 00000000..a9d92ecd --- /dev/null +++ b/ReleaseNotes.md @@ -0,0 +1,32 @@ +## 1.0.0 + +**Release Candidate submitted 2022-01-25** + +[Release Plan](https://github.com/openmobilityfoundation/governance/wiki/Release-1.2.0) + +The 1.0.0 major release is the first release of the Curb Data Specification (CDS) after over 15 months of community work. It includes three major APIs to define Curbs and policies, track Events at the curb and determine sensor status, and derive Metrics for sessions and aggregate curb usage with a well defined methodology. + +### CHANGES + +See work tagged with "Milestone 1.0.0" in [Pull Requests](https://github.com/openmobilityfoundation/curb-data-specification/pulls?q=is%3Apr+is%3Aclosed+milestone%3A1.0.0), [Issues](https://github.com/openmobilityfoundation/curb-data-specification/issues?q=is%3Aissue+milestone%3A1.0.0+is%3Aclosed), and [Discussions](https://github.com/openmobilityfoundation/curb-data-specification/discussions) for a full list of changes and history. + +**_General CDS_** + +- Creation of spec from working group drafts and community code submissions + - See [About CDS](https://www.openmobilityfoundation.org/about-cds/) web page for high level details + +**_Curbs_** + +- The Curbs API is a standard way for cities to digitally publish curb locations and regulations, which can be shared with the public and with companies using curb space. It defines curb policies, curb zones, spaces in zones, and areas around curbs, and is used by Events and Metrics. + +**_Events_** + +- The Events API is a standard way to transmit real-time and historic commercial events happening at the curb to cities. Event data can be derived from company data feeds, on street sensors, session payments, company check-ins, in-person parking personnel, and/or other city data sources. Connected to Curbs and used by Metrics. + +**_Metrics_** + +- The Metrics API is a way to track curb usage session details and define common calculation methodologies to measure historic dwell time, occupancy, usage and other aggregated statistics. It defines sessions and aggregates data derived from raw Events data. + +_Minor Updates_ + +- Formatting of spec, links, TOCs, headers, etc From a383a6ca732356e8d95401b1f2781c65350258d3 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 21 Jan 2022 14:05:02 -0500 Subject: [PATCH 157/173] Added releases link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 349021d1..df1ee74c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Curb Data Specification ## Release Candidate -> ⚠ **This repository is a release candidate for CDS 1.0. It has been approved by the [Working Group Steering Committee](https://github.com/openmobilityfoundation/curb-data-specification/wiki). You may start to use it in your development and production environments for real world use cases. The release is going through the final [OMF approval process](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md#approval-by-the-open-mobility-foundation), where it may be tweaked or enhanced with more guidance and resources. See the [Release Plan](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Release-1.0.0) page for updates.** +> ⚠ **This repository is a [release candidate](https://github.com/openmobilityfoundation/curb-data-specification/releases) for CDS 1.0. It has been approved by the [Working Group Steering Committee](https://github.com/openmobilityfoundation/curb-data-specification/wiki). You may start to use it in your development and production environments for real world use cases. The release is going through the final [OMF approval process](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md#approval-by-the-open-mobility-foundation), where it may be tweaked or enhanced with more guidance and resources. See the [Release Plan](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Release-1.0.0) page for updates.** ## Table of Contents From 6d5b2c744df08132a01b469f5f290141ee5104b5 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 21 Jan 2022 15:49:19 -0500 Subject: [PATCH 158/173] Update Curbs icon --- curbs/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 8cddccf9..8e47cb74 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -1,7 +1,5 @@ # Curb Data Specification: Curbs API - -CDS Curbs Icon - +CDS Curbs Icon The Curbs API is a REST API allowing cities to specify areas of interest along the curb along with the rules for using them: who is allowed to park, load, unload, pick up, drop off, etc., for how long, for what price (if any), at what times, and on which days. Locations defined in the From 7c21e5fc7493d0d8535834ef09a4df7f2de7daf3 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 21 Jan 2022 15:50:12 -0500 Subject: [PATCH 159/173] Update Metrics icon --- metrics/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/metrics/README.md b/metrics/README.md index c1946dbb..d29538b4 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -1,6 +1,6 @@ # Curb Data Specification: Metrics API -CDS Metrics Icon +CDS Metrics Icon The Metrics API is a REST API allowing historic metrics calculations based on Event activity that happened at defined Curb places. Defines common calculation methodologies to measure historic dwell time, occupancy, usage and other aggregated statistics. From 557b93bfbb2ddcf6182f3a406b99e36b132c8be4 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 21 Jan 2022 15:50:50 -0500 Subject: [PATCH 160/173] Update Events icon --- events/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/events/README.md b/events/README.md index 4118def8..b836545a 100644 --- a/events/README.md +++ b/events/README.md @@ -1,6 +1,6 @@ # Curb Data Specification: Events API -CDS Events Icon +CDS Events Icon The Events API is a REST API allowing real-time and historic events at the curb to be sent to cities, and the ability to check on the status of any sensors. Events can come from company data feeds, on street sensors, session payments, company check-ins, in-person parking personnel, and/or other city data sources. Data sent in the Events API can be connected to the Curbs API over time and space, and events are used for calculations in the Metrics API. From d89d38c81ab7695406d5149d0853ada88271e406 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 21 Jan 2022 15:51:09 -0500 Subject: [PATCH 161/173] Curbs icon size --- curbs/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/curbs/README.md b/curbs/README.md index 8e47cb74..e4fa8878 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -1,5 +1,7 @@ # Curb Data Specification: Curbs API -CDS Curbs Icon + +CDS Curbs Icon + The Curbs API is a REST API allowing cities to specify areas of interest along the curb along with the rules for using them: who is allowed to park, load, unload, pick up, drop off, etc., for how long, for what price (if any), at what times, and on which days. Locations defined in the From 7f2fb358f592823ffe7a48d0daaaec1bea4928d7 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 21 Jan 2022 15:59:54 -0500 Subject: [PATCH 162/173] Example on timestamp --- general-information.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/general-information.md b/general-information.md index 6f74bff3..b6f79f6f 100644 --- a/general-information.md +++ b/general-information.md @@ -258,8 +258,7 @@ in RFC 4122, including time-based (V1), random (V4), or name-based (V5). # Timestamp -A timestamp is an integer representing a number of milliseconds since midnight, January 1st, 1970 UTC -(the UNIX epoch). +A timestamp is an integer representing a number of milliseconds since midnight, January 1st, 1970 UTC (the UNIX epoch). E.g., `1643130000000` is Tuesday, January 25, 2022 5:00:00 PM UTC. [Top][toc] From bc2c7c4578fa0a3f21466c41126ba75811621503 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 24 Jan 2022 10:51:14 -0500 Subject: [PATCH 163/173] Present tense pass --- README.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index df1ee74c..df61e6a0 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,9 @@ The Curb Data Specification (**CDS**), a project of the [Open Mobility Foundation](http://www.openmobilityfoundation.org/) (**OMF**), is a data standard and set of Application Programming Interfaces (APIs) that helps cities manage and companies use dynamic curb zones that optimize loading activities of people and goods, and measure the impact of these programs. -Urban curb is a valuable, limited, and often under-managed part of the public right of way. Curb demand is growing, including from commercial activity like passenger pickup/drop off, traditional and on-demand delivery services, new mobility programs like scooters, bikeshare, and carshare, and goods and freight delivery. While cities have made some progress in digitizing their curb and using curb data, more tools are needed to proactively manage curbs and sidewalks, and to deliver more public value from this scarce resource. Curb data standards can provide a mechanism for expressing static and dynamic regulations, measuring activity at the curb, and developing policies that create more accessible, useful curbs. +Urban curb is a valuable, limited, and often under-managed part of the public right of way. Curb demand is growing, including from commercial activity like passenger pickup/drop off, traditional and on-demand delivery services, new mobility programs like scooters, bikeshare, and carshare, and goods and freight delivery. While cities have made some progress in digitizing their curb and using curb data, more tools are needed to proactively manage curbs and sidewalks, and to deliver more public value from this scarce resource. CDS can provide a mechanism for expressing static and dynamic regulations, measuring activity at the curb, and developing policies that create more accessible, useful curbs. -**CDS** is a key piece of digital infrastructure that supports the effective implementation of curb policies in cities and for curb users. For a high level overview and visuals, see the **[About CDS](https://www.openmobilityfoundation.org/about-cds/) page** on the OMF website. +**CDS** is a key piece of digital infrastructure that supports the effective implementation of curb policies in cities and for curb users. For a high level overview and visuals, see the **[About CDS](https://www.openmobilityfoundation.org/about-cds/)** page on the OMF website. ![Curb Data Specification Logo](https://i.imgur.com/pvZZQF4.png) @@ -54,7 +54,6 @@ The [`Metrics`](/metrics/) API is a way to track curb usage session details and --- - CDS is a data exchange format and a translation layer between internal systems and external entities using data feeds. It is not expected that CDS will be the format used internally to store curb regulations in a city. The internal storage format is something different, and a subset of that data should be able to be converted to CDS for publishing out to the public and curb users. Many parts of the CDS definitions and APIs align across each other. In these cases, consolidated information can be found on the [General Information](/general-information.md) page. @@ -71,19 +70,19 @@ CDS is designed to be a modular and flexible specification. Regulatory agencies ## MDS Overlap -Like the [Mobility Data Specification](https://github.com/openmobilityfoundation/mobility-data-specification/) (MDS), the CDS will be consumed by both cities and transportation providers operating in the public right of way. In many cases, the same mobility providers using curbs with CDS may also be interacting with other OMF [MDS Policy](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/policy), [MDS Provider](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/provider), and [MDS Agency](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/agency) data objects within the same [MDS Jurisdiction](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/jurisdiction) or [MDS Geography](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/geography), and using similar [MDS Metrics](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/metrics). Consistent with the Technology Design Principles codified in the [Technology Council's](https://github.com/openmobilityfoundation/governance/wiki/Technology-Council) OMF [Architectural Landscape Document](https://github.com/openmobilityfoundation/governance/blob/main/documents/OMF-MDS-Architectural-Landscape.pdf), the members of this working group are making reasonable best efforts to ensure that work is both _modular_ and _inter operable_ with other technology managed by the OMF as to avoid duplication and downstream implementation complexity. +Like the [Mobility Data Specification](https://github.com/openmobilityfoundation/mobility-data-specification/) (MDS), the CDS will be consumed by both cities and transportation providers operating in the public right of way. In many cases, the same mobility providers using curbs with CDS may also be interacting with other OMF [MDS Policy](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/policy), [MDS Provider](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/provider), and [MDS Agency](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/agency) data objects within the same [MDS Jurisdiction](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/jurisdiction) or [MDS Geography](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/geography), and using similar [MDS Metrics](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/metrics). Consistent with the Technology Design Principles codified in the [Technology Council's](https://github.com/openmobilityfoundation/governance/wiki/Technology-Council) OMF [Architectural Landscape Document](https://github.com/openmobilityfoundation/governance/blob/main/documents/OMF-MDS-Architectural-Landscape.pdf), the members of this working group are making reasonable best efforts to ensure that work is both _modular_ and _inter operable_ with other technology managed by the OMF as to avoid duplication and downstream implementation complexity. The first version of CDS intentionally has no direct connetions to MDS which allowed it to be created based strictly on real-world curb use cases and needs, but may align directly in future versions. [Top][toc] # Work in Progress -The CDS is a work in progress and is under ongoing development by the community under the guidance of the [Working Group Steering Committee](https://github.com/openmobilityfoundation/curb-data-specification/wiki) on specific [discussion topics](https://github.com/openmobilityfoundation/curb-data-specification/discussions) and bi-weekly [public meetings](https://github.com/openmobilityfoundation/curb-data-specification/wiki#meeting-agendas) around a specific [Scope of Work](https://docs.google.com/document/d/1yY5pRiiei8seVxXOmcYiqCA7wx7DueeatJnjbZoV3hU/). Work and discussion is also happening in the [Curb Data Specification - Draft and Ideas Doc](https://docs.google.com/document/d/1UgD2fHtVyIMwNG-qXJRv-gcY7nCdYxokbMsLTs32Em4/edit?usp=sharing) before being committed to GitHub. The Steering Committee has created supplementary resources the [Architectural Decisions](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Curb-Architectural-Decisions), [Curbs Use Cases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Curbs-Use-Cases), and [Pilot Project Guide](https://docs.google.com/document/d/1Mb1wpy4AFJ1MLvDpSIJsii4_1j2JC16NxNUVPI5BMNM/edit?usp=sharing) pages. The goal is to release a beta version of the spec by the end of 2021 and incorporate feedback from pilot programs into future versions. +The CDS is a work in progress and is under ongoing development by the community under the guidance of the [Working Group Steering Committee](https://github.com/openmobilityfoundation/curb-data-specification/wiki) on specific [discussion topics](https://github.com/openmobilityfoundation/curb-data-specification/discussions) and bi-weekly [public meetings](https://github.com/openmobilityfoundation/curb-data-specification/wiki#meeting-agendas) around a specific [Scope of Work](https://docs.google.com/document/d/1yY5pRiiei8seVxXOmcYiqCA7wx7DueeatJnjbZoV3hU/). The Steering Committee has created supplementary resources like [Architectural Decisions](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Curb-Architectural-Decisions), [Use Cases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Use-Cases), [Privacy Guidance](https://docs.google.com/document/d/117kJhXp6ldv7KHq7k9wHONHVVHw00xweaHpORVu_c10/edit?usp=sharing), [Policy Language Guidance](https://github.com/openmobilityfoundation/governance/blob/main/technical/OMF-CDS-Policy-Language-Guidance.md), and a [Pilot Project Guide](https://docs.google.com/document/d/1Mb1wpy4AFJ1MLvDpSIJsii4_1j2JC16NxNUVPI5BMNM/edit?usp=sharing). After the CDS 1.0 launch, the public working group will incorporate feedback from on-the-ground pilot programs into future versions. [Top][toc] # Get Involved -The OMF’s [Curb Management Working Group](https://github.com/openmobilityfoundation/curb-data-specification/wiki), led by a steering committee of individuals representing public agencies and private sector companies, is developing this data specification for curb usage. The CDS will encompass digitized curb regulations, real time and historic event information, and utilization metrics. The specification will allow sharing of this data between cities, commercial companies, and the public. Get involved by siging up to the [Curb Mailing List](https://groups.google.com/a/openmobilityfoundation.org/g/wg-curb). +The OMF’s [Curb Management Working Group](https://github.com/openmobilityfoundation/curb-data-specification/wiki), led by a steering committee of individuals representing public agencies and private sector companies, has developed this data specification for curb usage. The CDS encompasses digitized curb regulations, real time and historic event information, and utilization metrics. The specification allows sharing of this data between cities, commercial companies, and the public. Get involved by siging up to the [Curb Mailing List](https://groups.google.com/a/openmobilityfoundation.org/g/wg-curb). The Curb Data Specification is an open source project with all development taking place on GitHub. Read our **[Community Wiki](https://github.com/openmobilityfoundation/curb-data-specification/wiki)** to get started. Comments and ideas can be shared by [starting a discussion](https://github.com/openmobilityfoundation/curb-data-specification/discussions), [creating an issue](https://github.com/openmobilityfoundation/curb-data-specification/issues), and specific changes can be suggested by [opening a pull request](https://github.com/openmobilityfoundation/curb-data-specification/pulls). Before contributing, please review our OMF [CONTRIBUTING page](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) and our [CODE OF CONDUCT page](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md) to understand guidelines and policies for participation. @@ -99,7 +98,7 @@ The OMF provides guidance on upgrading for cities, providers, and software compa ## Technical Information -The latest CDS release is in the [`main`](https://github.com/openmobilityfoundation/curb-data-specification/tree/main) branch, and development for the next release occurs in the [`dev`](https://github.com/openmobilityfoundation/curb-data-specification/tree/dev) branch. +The latest CDS release is in the [`main`](https://github.com/openmobilityfoundation/curb-data-specification/tree/main) branch, and development for the next release occurs in the [`dev`](https://github.com/openmobilityfoundation/curb-data-specification/tree/dev) and other branches. The CDS specification is versioned using Git tags and [semantic versioning](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md#versioning). @@ -136,7 +135,7 @@ CDS includes information about commercial vehicles using select curb zones in a * [Privacy Guide for Cities](https://github.com/openmobilityfoundation/governance/raw/main/documents/OMF-MDS-Privacy-Guide-for-Cities.pdf) - guide that covers essential privacy topics and best practices * [The Privacy Principles for Mobility Data](https://www.mobilitydataprivacyprinciples.org/) - principles endorsed by the OMF and other mobility organizations to guide the mobility ecosystem in the responsible use of data and the protection of individual privacy * [Mobility Data State of Practice](https://github.com/openmobilityfoundation/privacy-committee/blob/main/products/state-of-the-practice.md) - real-world examples related to the handling and protection of MDS and other types of mobility data -* [CDS Use Cases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Curbs-Use-Cases) - outlines real-world use cases, and how to use CDS to make them happen and why. +* [CDS Use Cases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Use-Cases) - outlines real-world use cases, and how to use CDS to make them happen and why. The OMF’s [Privacy, Security, and Transparency Committee](https://github.com/openmobilityfoundation/privacy-committee#welcome-to-the-privacy-security-and-transparency-committee) creates many of these resources, and advises the OMF on principles and practices that ensure the secure handling of mobility data. The committee – which is composed of both private and public sector OMF members – also holds regular public meetings, which provide additional resources and an opportunity to discuss issues related to privacy and mobility data. Learn more [here](https://github.com/openmobilityfoundation/privacy-committee#welcome-to-the-privacy-security-and-transparency-committee). @@ -146,7 +145,7 @@ The OMF’s [Privacy, Security, and Transparency Committee](https://github.com/o How cities use CDS depends on a variety of factors: their transportation goals, existing services and infrastructure, and the unique needs of their communities. Cities are using CDS to create policy, manage curbs, and ensure the safe operation of vehicles in the public right of way. -A list of use cases is useful to show what's possible with CDS, to see many use cases up front for privacy considerations, and to use for policy discussions and policy language. More details and examples can be seen on the [CDS Use Cases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Curbs-Use-Cases). +A list of use cases is useful to show what's possible with CDS, to see many use cases up front for privacy considerations, and to use for policy discussions and policy language. More details and examples can be seen on the [CDS Use Cases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Use-Cases). [Top][toc] From a6fefd387d6067fb23e8747171742452b5c855c9 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 24 Jan 2022 10:53:27 -0500 Subject: [PATCH 164/173] Update ReleaseNotes.md --- ReleaseNotes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ReleaseNotes.md b/ReleaseNotes.md index a9d92ecd..9a3561e1 100644 --- a/ReleaseNotes.md +++ b/ReleaseNotes.md @@ -2,9 +2,9 @@ **Release Candidate submitted 2022-01-25** -[Release Plan](https://github.com/openmobilityfoundation/governance/wiki/Release-1.2.0) +[Release Plan](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Release-1.0.0) -The 1.0.0 major release is the first release of the Curb Data Specification (CDS) after over 15 months of community work. It includes three major APIs to define Curbs and policies, track Events at the curb and determine sensor status, and derive Metrics for sessions and aggregate curb usage with a well defined methodology. +The 1.0.0 major release is the first release of the Curb Data Specification (CDS) after over 15 months of community work across dozens of public meetings, with 70+ organizations and 160+ individuals participating. It includes three major APIs to define Curbs and policies, track Events at the curb and determine sensor status, and derive Metrics for sessions and aggregate curb usage with a well defined methodology. ### CHANGES From 792559e7fe85221fb1f2864c937949cb49644d12 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 24 Jan 2022 11:07:33 -0500 Subject: [PATCH 165/173] Logo Tweak --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index df61e6a0..89f9c182 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Urban curb is a valuable, limited, and often under-managed part of the public ri **CDS** is a key piece of digital infrastructure that supports the effective implementation of curb policies in cities and for curb users. For a high level overview and visuals, see the **[About CDS](https://www.openmobilityfoundation.org/about-cds/)** page on the OMF website. -![Curb Data Specification Logo](https://i.imgur.com/pvZZQF4.png) +![Curb Data Specification Logo](https://i.imgur.com/iGPCZyQ.png) [Top][toc] From 0e4bc4da40ab159917305214c227330a65e5823b Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 24 Jan 2022 11:40:51 -0500 Subject: [PATCH 166/173] Update general-information.md --- general-information.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/general-information.md b/general-information.md index b6f79f6f..46820fa3 100644 --- a/general-information.md +++ b/general-information.md @@ -260,6 +260,16 @@ in RFC 4122, including time-based (V1), random (V4), or name-based (V5). A timestamp is an integer representing a number of milliseconds since midnight, January 1st, 1970 UTC (the UNIX epoch). E.g., `1643130000000` is Tuesday, January 25, 2022 5:00:00 PM UTC. +## Time Ranges + +All ranges across the spec of timestamps, times, or dates are 'inclusive' at the start and 'exclusive' at the end, unless otherwise noted. + +For example: + +- `start_datetime`: "2021-08-12 00:00:00" and `end_datetime`: "2021-08-13 00:00:00" + +This covers all of 2021-08-12, which is inclusive of the time "2021-08-12 00:00:00", but exclusive (does not include) the time "2021-08-13 00:00:00". This is easier and more clear than using "2021-08-12 23:59:59" as the `end_datetime`. + [Top][toc] # Versioning From 22a5d97fa6d9756f57dcc2ae6758b64ddff7ae94 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 24 Jan 2022 11:41:31 -0500 Subject: [PATCH 167/173] Added Time Range clarity --- general-information.md | 1 + 1 file changed, 1 insertion(+) diff --git a/general-information.md b/general-information.md index 46820fa3..96e73b78 100644 --- a/general-information.md +++ b/general-information.md @@ -18,6 +18,7 @@ This document contains specifications that are shared between the various CDS AP - [Pagination](#pagination) - [UUID](#uuid) - [Timestamp](#timestamp) + - [Time Range](#time-range) - [Versioning](#versioning) # Authorization From 42733c5ac8d19adc0f261545b4574d5e6fa76d04 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 24 Jan 2022 11:49:34 -0500 Subject: [PATCH 168/173] Added inclusive/exclusive clarity --- curbs/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index e4fa8878..3eafd887 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -244,8 +244,8 @@ A Curb Zone is represented as a JSON object, whose fields are as follows: | `published_date` | [Timestamp][ts] | Required | The date/time that this curb zone was first published in this data feed. | | `last_updated_date` | [Timestamp][ts] | Required | The date/time that the properties of ths curb zone were last updated. This helps consumers know that some curb objects fields may have changed. | | `prev_curb_zone_ids` | Array of [UUIDs][uuid] | Optional | An array of IDs of previous curb zone objects. They are listed in order with the most recent ones first. | -| `start_date` | [Timestamp][ts] | Required | The earliest time that the data for this curb location is known to be valid. This could be the date on which the data was collected, for instance. This MUST never change for a given id. | -| `end_date` | [Timestamp][ts] | Optional | The time at which the data for this curb location ceases to be valid. If not present, the data will be presumed to be valid indefinitely. | +| `start_date` | [Timestamp][ts] | Required | The earliest time that the data for this curb location is known to be valid (_inclusive_, see [Time Range](/general-information.md#time-range)). This could be the date on which the data was collected, for instance. This MUST never change for a given id. | +| `end_date` | [Timestamp][ts] | Optional | The time at which the data for this curb location ceases to be valid (_exclusive_, see [Time Range](/general-information.md#time-range)). If not present, the data will be presumed to be valid indefinitely. | | `location_references` | Array of [Location Reference](#location-reference) objects | Optional | One or more linear references for this Curb Zone. | | `name` | String | Optional | A human-readable name for this Curb Zone that identifies it to end users. | | `user_zone_id` | String | Optional | An identifier that can be used to refer to this Curb Zone on physical signage as well as within mobile applications, typically for payment purposes. | @@ -453,13 +453,13 @@ A Time Span is represented as a JSON object whose fields are as follows: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `start_date` | [Timestamp][ts] | Optional | The earliest point in time that this Time Span could apply. If unspecified, the Time Span applies to all matching periods arbitrarily far in the past. See note below for more details. | -| `end_date` | [Timestamp][ts] | Optional | The latest point in time that this Time Span could apply. If unspecified, the Time Span applies to all matching periods arbitrarily far in the future. See note below for more details. | +| `start_date` | [Timestamp][ts] | Optional | The earliest point in time that this Time Span could apply (_inclusive_, see [Time Range](/general-information.md#time-range)). If unspecified, the Time Span applies to all matching periods arbitrarily far in the past. See note below for more details. | +| `end_date` | [Timestamp][ts] | Optional | The latest point in time that this Time Span could apply (_exclusive_, see [Time Range](/general-information.md#time-range)). If unspecified, the Time Span applies to all matching periods arbitrarily far in the future. See note below for more details. | | `days_of_week` | Array of strings | Optional | An array of days of the week when this Time Span applies, specified as 3-character strings (`"sun"`, `"mon"`, `"tue"`, `"wed"`, `"thu"`, `"fri"`, `"sat"`). | | `days_of_month` | Array of integers | Optional | An array of days of the month when this Time Span applies, specified as integers (1-31). Note that, in order to specify, e.g., the "2nd Monday of the month", you can use `days_of_month` combined with `days_of_week` (in this example, `days_of_week = ["mon"]` and `days_of_month = [8,9,10,11,12,13,14]`). | | `months` | Array of integers | Optional | If specified, this Time Span applies only during these months (1=January, 12=December). | -| `time_of_day_start` | "HH:MM" string | Optional | The 24-hour local time that this Time Span starts to apply. If unspecified, this Time Span starts at midnight. | -| `time_of_day_end` | "HH:MM" string | Optional | The 24-hour local time that this Time Span stops applying. This is not inclusive, so for instance if `time_of_day_end` is `"17:00"`, this Time Span goes up to 5PM but does not include it. If unspecified, this Time Span ends at midnight. | +| `time_of_day_start` | "HH:MM" string | Optional | The 24-hour local time that this Time Span starts to apply (_inclusive_, see [Time Range](/general-information.md#time-range)). If unspecified, this Time Span starts at midnight. | +| `time_of_day_end` | "HH:MM" string | Optional | The 24-hour local time that this Time Span stops applying (_exclusive_, see [Time Range](/general-information.md#time-range)). This is not inclusive, so for instance if `time_of_day_end` is `"17:00"`, this Time Span goes up to 5PM but does not include it. If unspecified, this Time Span ends at midnight. | | `designated_period` | String | Optional | A string representing an arbitrarily-named, externally-defined period of time. Any values MAY be specified but the following known values SHOULD be used when possible:
          • `snow emergency`
          • `holidays`
          • `school days`
          • `game days`
          | | `designated_period_except` | `Boolean` | `Optional` | If specified and `true`, this Time Span applies at all times not matching the named designated period. (e.g., if `designated_period` is `snow emergency` and `designated_period_except` is `true`, this Time Span does not apply on snow days). | @@ -477,8 +477,8 @@ A Rate defines the amount a user of the curb needs to pay when a given rule appl | `rate_unit` | Enum | Required | The unit of time associated with the rate. One of "second", "minute", "hour", "day", "week", "month", "year". | | `increment_minutes` | Integer | Optional | If specified, this is the smallest amount of time a user can pay for (e.g., if `increment_minutes` is `15`, a user can pay for 15, 30, 45, etc. minutes). | | `increment_amount` | Integer | Optional | If specified, the rate for this space is rounded up to the nearest increment of this amount, specified in the same units as `per_hour`. | -| `start_minutes` | Integer | Optional | The amount of time the vehicle must have already been present in the Curb Zone before this rate starts applying. If not specified, this rate starts when the vehicle arrives. | -| `end_minutes` | Integer | Optional | The amount of time after which the rate stops applying. If not specified, this rate ends when the vehicle departs. | +| `start_minutes` | Integer | Optional | The amount of time the vehicle must have already been present in the Curb Zone before this rate starts applying (_inclusive_, see [Time Range](/general-information.md#time-range)). If not specified, this rate starts when the vehicle arrives. | +| `end_minutes` | Integer | Optional | The amount of time after which the rate stops applying (_inclusive_, see [Time Range](/general-information.md#time-range)). If not specified, this rate ends when the vehicle departs. | [Top][toc] From 297a4afe5fb9458d45b85841fb29967547e8e13f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 24 Jan 2022 13:25:08 -0500 Subject: [PATCH 169/173] Rename Time Range heading --- general-information.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/general-information.md b/general-information.md index 96e73b78..b0c35d7f 100644 --- a/general-information.md +++ b/general-information.md @@ -261,7 +261,7 @@ in RFC 4122, including time-based (V1), random (V4), or name-based (V5). A timestamp is an integer representing a number of milliseconds since midnight, January 1st, 1970 UTC (the UNIX epoch). E.g., `1643130000000` is Tuesday, January 25, 2022 5:00:00 PM UTC. -## Time Ranges +## Time Range All ranges across the spec of timestamps, times, or dates are 'inclusive' at the start and 'exclusive' at the end, unless otherwise noted. From dacb23b256caa2231bd8ab43adbb6c752a3f0350 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 24 Jan 2022 13:26:54 -0500 Subject: [PATCH 170/173] Updated rate end as exclusive --- curbs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/curbs/README.md b/curbs/README.md index 3eafd887..7582a573 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -478,7 +478,7 @@ A Rate defines the amount a user of the curb needs to pay when a given rule appl | `increment_minutes` | Integer | Optional | If specified, this is the smallest amount of time a user can pay for (e.g., if `increment_minutes` is `15`, a user can pay for 15, 30, 45, etc. minutes). | | `increment_amount` | Integer | Optional | If specified, the rate for this space is rounded up to the nearest increment of this amount, specified in the same units as `per_hour`. | | `start_minutes` | Integer | Optional | The amount of time the vehicle must have already been present in the Curb Zone before this rate starts applying (_inclusive_, see [Time Range](/general-information.md#time-range)). If not specified, this rate starts when the vehicle arrives. | -| `end_minutes` | Integer | Optional | The amount of time after which the rate stops applying (_inclusive_, see [Time Range](/general-information.md#time-range)). If not specified, this rate ends when the vehicle departs. | +| `end_minutes` | Integer | Optional | The amount of time after which the rate stops applying (_exclusive_, see [Time Range](/general-information.md#time-range)). If not specified, this rate ends when the vehicle departs. | [Top][toc] From 378972275821cd9962732ec3961241a7a35ab18d Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 24 Jan 2022 18:20:30 -0500 Subject: [PATCH 171/173] Expanded time ranges to all ranges --- general-information.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/general-information.md b/general-information.md index b0c35d7f..4bca66ad 100644 --- a/general-information.md +++ b/general-information.md @@ -16,9 +16,9 @@ This document contains specifications that are shared between the various CDS AP - [Responses](#responses) - [REST Endpoints](#rest-endpoints) - [Pagination](#pagination) +- [Range Boundaries](#range-boundaries) - [UUID](#uuid) - [Timestamp](#timestamp) - - [Time Range](#time-range) - [Versioning](#versioning) # Authorization @@ -248,6 +248,18 @@ At a minimum, payloads that use pagination must include a `next` key, which must [Top][toc] +# Range Boundaries + +All ranges across the spec of timestamps, times, measurements, dates, etc are 'inclusive' at the start and 'exclusive' at the end, unless otherwise noted. + +For example: + +- `start_datetime`: "2021-08-12 00:00:00" and `end_datetime`: "2021-08-13 00:00:00" + +This covers all of 2021-08-12, which is inclusive of the time "2021-08-12 00:00:00", but exclusive (does not include) the time "2021-08-13 00:00:00". This is easier and more clear than using "2021-08-12 23:59:59" as the `end_datetime`. + +[Top][toc] + # UUID A UUID is a 128-bit, globally unique identifier represented as a string using the format defined in @@ -261,18 +273,6 @@ in RFC 4122, including time-based (V1), random (V4), or name-based (V5). A timestamp is an integer representing a number of milliseconds since midnight, January 1st, 1970 UTC (the UNIX epoch). E.g., `1643130000000` is Tuesday, January 25, 2022 5:00:00 PM UTC. -## Time Range - -All ranges across the spec of timestamps, times, or dates are 'inclusive' at the start and 'exclusive' at the end, unless otherwise noted. - -For example: - -- `start_datetime`: "2021-08-12 00:00:00" and `end_datetime`: "2021-08-13 00:00:00" - -This covers all of 2021-08-12, which is inclusive of the time "2021-08-12 00:00:00", but exclusive (does not include) the time "2021-08-13 00:00:00". This is easier and more clear than using "2021-08-12 23:59:59" as the `end_datetime`. - -[Top][toc] - # Versioning CDS APIs must handle requests for specific versions of the specification from clients. From 50b07e7ad71dffd5da461ffae0484a20a8afc3e9 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 24 Jan 2022 18:25:32 -0500 Subject: [PATCH 172/173] Renamed Time Range to Range Boundaries --- curbs/README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/curbs/README.md b/curbs/README.md index 7582a573..9dc47f2f 100644 --- a/curbs/README.md +++ b/curbs/README.md @@ -244,8 +244,8 @@ A Curb Zone is represented as a JSON object, whose fields are as follows: | `published_date` | [Timestamp][ts] | Required | The date/time that this curb zone was first published in this data feed. | | `last_updated_date` | [Timestamp][ts] | Required | The date/time that the properties of ths curb zone were last updated. This helps consumers know that some curb objects fields may have changed. | | `prev_curb_zone_ids` | Array of [UUIDs][uuid] | Optional | An array of IDs of previous curb zone objects. They are listed in order with the most recent ones first. | -| `start_date` | [Timestamp][ts] | Required | The earliest time that the data for this curb location is known to be valid (_inclusive_, see [Time Range](/general-information.md#time-range)). This could be the date on which the data was collected, for instance. This MUST never change for a given id. | -| `end_date` | [Timestamp][ts] | Optional | The time at which the data for this curb location ceases to be valid (_exclusive_, see [Time Range](/general-information.md#time-range)). If not present, the data will be presumed to be valid indefinitely. | +| `start_date` | [Timestamp][ts] | Required | The earliest time that the data for this curb location is known to be valid (_inclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). This could be the date on which the data was collected, for instance. This MUST never change for a given id. | +| `end_date` | [Timestamp][ts] | Optional | The time at which the data for this curb location ceases to be valid (_exclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). If not present, the data will be presumed to be valid indefinitely. | | `location_references` | Array of [Location Reference](#location-reference) objects | Optional | One or more linear references for this Curb Zone. | | `name` | String | Optional | A human-readable name for this Curb Zone that identifies it to end users. | | `user_zone_id` | String | Optional | An identifier that can be used to refer to this Curb Zone on physical signage as well as within mobile applications, typically for payment purposes. | @@ -453,13 +453,13 @@ A Time Span is represented as a JSON object whose fields are as follows: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `start_date` | [Timestamp][ts] | Optional | The earliest point in time that this Time Span could apply (_inclusive_, see [Time Range](/general-information.md#time-range)). If unspecified, the Time Span applies to all matching periods arbitrarily far in the past. See note below for more details. | -| `end_date` | [Timestamp][ts] | Optional | The latest point in time that this Time Span could apply (_exclusive_, see [Time Range](/general-information.md#time-range)). If unspecified, the Time Span applies to all matching periods arbitrarily far in the future. See note below for more details. | +| `start_date` | [Timestamp][ts] | Optional | The earliest point in time that this Time Span could apply (_inclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). If unspecified, the Time Span applies to all matching periods arbitrarily far in the past. See note below for more details. | +| `end_date` | [Timestamp][ts] | Optional | The latest point in time that this Time Span could apply (_exclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). If unspecified, the Time Span applies to all matching periods arbitrarily far in the future. See note below for more details. | | `days_of_week` | Array of strings | Optional | An array of days of the week when this Time Span applies, specified as 3-character strings (`"sun"`, `"mon"`, `"tue"`, `"wed"`, `"thu"`, `"fri"`, `"sat"`). | | `days_of_month` | Array of integers | Optional | An array of days of the month when this Time Span applies, specified as integers (1-31). Note that, in order to specify, e.g., the "2nd Monday of the month", you can use `days_of_month` combined with `days_of_week` (in this example, `days_of_week = ["mon"]` and `days_of_month = [8,9,10,11,12,13,14]`). | | `months` | Array of integers | Optional | If specified, this Time Span applies only during these months (1=January, 12=December). | -| `time_of_day_start` | "HH:MM" string | Optional | The 24-hour local time that this Time Span starts to apply (_inclusive_, see [Time Range](/general-information.md#time-range)). If unspecified, this Time Span starts at midnight. | -| `time_of_day_end` | "HH:MM" string | Optional | The 24-hour local time that this Time Span stops applying (_exclusive_, see [Time Range](/general-information.md#time-range)). This is not inclusive, so for instance if `time_of_day_end` is `"17:00"`, this Time Span goes up to 5PM but does not include it. If unspecified, this Time Span ends at midnight. | +| `time_of_day_start` | "HH:MM" string | Optional | The 24-hour local time that this Time Span starts to apply (_inclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). If unspecified, this Time Span starts at midnight. | +| `time_of_day_end` | "HH:MM" string | Optional | The 24-hour local time that this Time Span stops applying (_exclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). This is not inclusive, so for instance if `time_of_day_end` is `"17:00"`, this Time Span goes up to 5PM but does not include it. If unspecified, this Time Span ends at midnight. | | `designated_period` | String | Optional | A string representing an arbitrarily-named, externally-defined period of time. Any values MAY be specified but the following known values SHOULD be used when possible:
          • `snow emergency`
          • `holidays`
          • `school days`
          • `game days`
          | | `designated_period_except` | `Boolean` | `Optional` | If specified and `true`, this Time Span applies at all times not matching the named designated period. (e.g., if `designated_period` is `snow emergency` and `designated_period_except` is `true`, this Time Span does not apply on snow days). | @@ -477,7 +477,7 @@ A Rate defines the amount a user of the curb needs to pay when a given rule appl | `rate_unit` | Enum | Required | The unit of time associated with the rate. One of "second", "minute", "hour", "day", "week", "month", "year". | | `increment_minutes` | Integer | Optional | If specified, this is the smallest amount of time a user can pay for (e.g., if `increment_minutes` is `15`, a user can pay for 15, 30, 45, etc. minutes). | | `increment_amount` | Integer | Optional | If specified, the rate for this space is rounded up to the nearest increment of this amount, specified in the same units as `per_hour`. | -| `start_minutes` | Integer | Optional | The amount of time the vehicle must have already been present in the Curb Zone before this rate starts applying (_inclusive_, see [Time Range](/general-information.md#time-range)). If not specified, this rate starts when the vehicle arrives. | +| `start_minutes` | Integer | Optional | The amount of time the vehicle must have already been present in the Curb Zone before this rate starts applying (_inclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). If not specified, this rate starts when the vehicle arrives. | | `end_minutes` | Integer | Optional | The amount of time after which the rate stops applying (_exclusive_, see [Time Range](/general-information.md#time-range)). If not specified, this rate ends when the vehicle departs. | [Top][toc] @@ -492,8 +492,8 @@ A Location Reference is a JSON object with the following fields: | ------ | ------ | ------------------- | ------------- | | `source` | URL | Required | An identifier for the source of the linear reference. This MUST be a URL pointing to more information about the underlying map or reference system. Values include (but other can be used):
          • `https://sharedstreets.io`: SharedStreets
          • `http://openlr.org`: OpenLR
          • `https://coord.com`: Coord
          • `https://yourcityname.gov`: custom city LR, direct link if possible
          | | `ref_id` | String | Required | The linear feature being referenced (usually a street or curb segment). For OpenLR, this is the Base64-encoded OpenLR line location for the street segment of which this Curb Zone is part, and the start and end offsets below are relative to this segment. | -| `start` | Integer | Required | The distance (in centimeters) from the start of the referenced linear feature to the start of the Curb Zone. | -| `end` | Integer | Required | The distance (in centimeters) from the start of the referenced linear feature to the end of the Curb Zone. 'end' MAY be smaller than start, implying that the direction of the Curb Zone is opposite to the direction of the referenced linear feature. | +| `start` | Integer | Required | The distance (in centimeters) from the start of the referenced linear feature to the start of the Curb Zone (_inclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). | +| `end` | Integer | Required | The distance (in centimeters) from the start of the referenced linear feature to the end of the Curb Zone (_exclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). 'end' MAY be smaller than start, implying that the direction of the Curb Zone is opposite to the direction of the referenced linear feature - in this case the [Range Boundaries](/general-information.md#range-boundaries)) are reversed. | | `side` | String | Optional | If the referenced linear feature is a roadway, the side of the roadway on which the Curb Zone may be found, when heading from the start to the end of the feature in its native orientation. Values are `left` and `right`. MUST be absent for features where `entire_roadway` is true. | [Top][toc] @@ -507,8 +507,8 @@ A Previous Policy is a JSON object with the following fields: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | | `curb_policy_ids` | Array of [UUIDs][uuid] | Required | An array of IDs of [Policy objects](#policy). Together, these define the previous regulations of this Curb Zone. | -| `start_date` | [Timestamp][ts] | Required | The date/time that this policy started being active for this curb location. | -| `end_date` | [Timestamp][ts] | Required | The date/time that this policy ended being active for this curb location. | +| `start_date` | [Timestamp][ts] | Required | The date/time that this policy started being active for this curb location (_inclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). | +| `end_date` | [Timestamp][ts] | Required | The date/time that this policy ended being active for this curb location (_exclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). | [Top][toc] From 63597d1124706ca2bfaf7c8b99d4a612923a98d1 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 24 Jan 2022 18:30:03 -0500 Subject: [PATCH 173/173] Added Range Boundaries clarity to Metrics too --- metrics/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index d29538b4..cfec75c1 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -88,8 +88,8 @@ An agency may choose to make this endpoint static (and return all the available | `curb_place_id` | [UUID][uuid] | Optional | The ID of this single curb place. If specified, only return data contained within this area. Required with `curb_place_type`. | | `min_lat`
          `min_lng`
          `max_lat`
          `max_lng` | Numeric | Optional | Specifies a latitude and longitude bounding box. If one of these parameters is specified, all four MUST be. If specified only return Curb Zones that intersect the supplied bounding box. | | `lat`
          `lng`
          `radius` | Numeric | Optional | Specifies a latitude and longitude bounding point and a radius away from that point. If one of these parameters is specified, all three MUST be. Returns only Curb Zones that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Zones in the response MUST be ordered ascending by distance from the center point. | -| `start_time` | [Timestamp][ts] | Optional | The start of the time period to return data | -| `end_time` | [Timestamp][ts] | Optional | The end of the time period to return data | +| `start_time` | [Timestamp][ts] | Optional | The start of the time period to return data (_inclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). | +| `end_time` | [Timestamp][ts] | Optional | The end of the time period to return data (_exclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). | [Top][toc] @@ -113,8 +113,8 @@ An agency may choose to make this endpoint static (and return all the available | `metric_type` | Enum | Optional | The single metric to return from the [Methodology](#methodology): `total_sessions`, `turnover`, `average_dwell_time`, `occupancy_percent`. | | `min_lat`
          `min_lng`
          `max_lat`
          `max_lng` | Numeric | Optional | Specifies a latitude and longitude bounding box. If one of these parameters is specified, all four MUST be. If specified only return Curb Zones that intersect the supplied bounding box. | | `lat`
          `lng`
          `radius` | Numeric | Optional | Specifies a latitude and longitude bounding point and a radius away from that point. If one of these parameters is specified, all three MUST be. Returns only Curb Zones that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Zones in the response MUST be ordered ascending by distance from the center point. | -| `start_time` | [Timestamp][ts] | Optional | The start of the time period to return data | -| `end_time` | [Timestamp][ts] | Optional | The end of the time period to return data | +| `start_time` | [Timestamp][ts] | Optional | The start of the time period to return data (_inclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). | +| `end_time` | [Timestamp][ts] | Optional | The end of the time period to return data (_exclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). | [Top][toc]