├── .gitignore ├── curbs ├── examples.md └── README.md ├── events ├── examples.md └── README.md ├── metrics ├── examples.md └── README.md ├── CODEOWNERS ├── SECURITY.md ├── .github ├── PULL_REQUEST_TEMPLATE │ ├── release-candidate.md │ └── pull_request_template.md ├── ISSUE_TEMPLATE │ ├── add-provider-id.md │ └── feature-request.md └── pull_request_template.md ├── data_source_operators.csv ├── LIABILITY ├── ReleaseNotes.md ├── data-types.md ├── LICENCE ├── README.md └── general-information.md /.gitignore: -------------------------------------------------------------------------------- 1 | .venv/ 2 | .vscode 3 | .DS_Store 4 | .idea 5 | __pycache__ 6 | -------------------------------------------------------------------------------- /curbs/examples.md: -------------------------------------------------------------------------------- 1 | # Curbs Examples 2 | 3 | See the [CDS Curbs Examples](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Curbs-Examples) wiki page for code examples of specific Curbs use cases, and ideas on how Curbs can be implemented. 4 | -------------------------------------------------------------------------------- /events/examples.md: -------------------------------------------------------------------------------- 1 | # Events Examples 2 | 3 | See the [CDS Events Examples](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Events-Examples) wiki page for code examples of specific Events use cases, and ideas on how Events can be implemented. 4 | -------------------------------------------------------------------------------- /metrics/examples.md: -------------------------------------------------------------------------------- 1 | # Metrics Examples 2 | 3 | See the [CDS Metrics Examples](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Metrics-Examples) wiki page for code examples of specific Metrics use cases, and ideas on how Metrics can be implemented. 4 | -------------------------------------------------------------------------------- /CODEOWNERS: -------------------------------------------------------------------------------- 1 | ## Below is the CDS CODEOWNERS file, which dictates who is required for review on any given file. 2 | 3 | ## All CDS approvals 4 | * @openmobilityfoundation/omf-admin 5 | 6 | ## CDS Working Group 7 | * @openmobilityfoundation/cds-maintainers @openmobilityfoundation/omf-admin 8 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | ## Supported Versions 4 | 5 | The most recent version and/or any version 2 years old or newer is supported. Other versions are not recommended and not supported. 6 | 7 | See our [CDS Releases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Releases) page for full details and list of supported releases by version number. 8 | 9 | ## Reporting a Vulnerability or Issue 10 | 11 | If you find a vulnerability or issue with a supported version of the specification, open an [Issue](https://github.com/openmobilityfoundation/curb-data-specification/issues) to let us know and start a discussion on how to fix it in a future release. 12 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE/release-candidate.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Release Candidate 3 | about: Initiate discussion to obtain OMF approval for new release 4 | title: Release Candidate [X.Y.Z] 5 | labels: admin 6 | 7 | --- 8 | 9 | ### Summary 10 | 11 | The Release Candidate for CDS `X.Y.Z` has been submitted: 12 | 13 | Please use this pull request to track Technology Council and OMF Board feedback and/or requested changes. 14 | 15 | ### Action Item 16 | 17 | 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). 18 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/add-provider-id.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Add Provider ID 3 | about: Create Provider ID for use in CDS 4 | title: 'Add Provider ID: [Provider Name]' 5 | labels: admin,identifier change 6 | assignees: '' 7 | 8 | --- 9 | 10 | **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. 11 | 12 | Opening this issue will allow you as a mobility service provider get an official provider ID for use across CDS globally. 13 | 14 | **Fields needed from you for the [providers.csv file](https://github.com/openmobilityfoundation/curb -data-specification/blob/main/providers.csv).** 15 | 16 | _All fields are required._ 17 | 18 | 1. **provider_name** - Short name of your company. 19 | - ... 20 | 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). 21 | - ... 22 | 1. **url** - URL to the home page of your company. 23 | 24 | Additionally, please provide your name and role within your agency to help with verification. 25 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature-request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request / proposal 3 | about: Suggest an idea for this project 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | ### Is your feature request related to a problem? Please describe. 11 | 12 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 13 | 14 | ### Describe the solution you'd like 15 | 16 | A clear and concise description of what you want to happen. 17 | 18 | ### Is this a breaking change 19 | 20 | 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). 21 | 22 | * Yes, breaking 23 | * No, not breaking 24 | * I'm not sure 25 | 26 | ### Impacted Spec 27 | 28 | For which spec is this feature being requested? 29 | 30 | * `Curbs` 31 | * `Events` 32 | * `Metrics` 33 | 34 | ### Describe alternatives you've considered 35 | 36 | A clear and concise description of any alternative solutions or features you've considered. 37 | 38 | ### Additional context 39 | 40 | Add any other context or screenshots about the feature request here. 41 | -------------------------------------------------------------------------------- /data_source_operators.csv: -------------------------------------------------------------------------------- 1 | data_source_operator_name,data_source_operator_id,url 2 | Automotus,6ee362db-b059-43ac-83d4-3d634ec7a22c,https://www.automotus.co/ 3 | Bird,2411d395-04f2-47c9-ab66-d09e9e3c3251,https://www.bird.co 4 | Kiwibot,5f19acae-d7e9-4b57-96bd-f6406712d654,https://www.kiwibot.com/ 5 | Passport,55b617b9-730e-485e-83de-5e1a35fdc352,https://www.passportinc.com/ 6 | Spin,70aa475d-1fcd-4504-b69c-2eeb2107f7be,https://www.spin.app 7 | Waymo,288e70d7-fa0b-499d-ab20-a686ec4ee2cb,https://waymo.com/ 8 | Vade,a7e7d081-7718-4abe-addf-c43dc138f655,https://www.vade.ai 9 | Flowbird Group,1e56a8aa-d5bc-4b43-9c56-3de44d787ac2,https://www.flowbird.group/ 10 | CurbIQ,d79d92ee-d554-4348-a749-bb5c24a60151,https://curbiq.io/ 11 | Univrses,99cab7dc-4ae3-4f8b-82f9-99426910db03,https://univrses.com/ 12 | Cleverciti,1e240e62-5871-497e-9e27-e8f798ce4829,https://www.cleverciti.com/ 13 | Umojo,d0abb612-cc14-41ad-a3a8-a616e2c92ddb,https://www.umojo.com/ 14 | ParkMobile,8d1917b4-ad33-4ef6-857f-87d4c6bef4f7,https://parkmobile.io/ 15 | PayByPhone,fa9ef92a-979e-40c5-94e3-3efa86731dbc,https://www.paybyphone.com/ 16 | Eleven-X,8570c84f-5172-40be-a30b-47cf4ac9fb75,https://eleven-x.com/ 17 | TurboData,9472cfa8-bbcb-4ecb-b605-9b013d029f5d,https://www.turbodata.com/ 18 | IPSGroup,97942825-be5f-434c-9b6c-9e40ad013266,https://www.ipsgroupinc.com 19 | T2 Systems,9018eea8-d115-423c-ab1c-0ef9cc97a0e3,https://www.t2systems.com 20 | RiseTek,c5934670-8648-4072-b8cb-1d6a95e3546b,https://risetekglobal.com/ 21 | Gtechna,ce602dcb-f3ee-4fe9-a489-df0461e5bc86,https://www.gtechna.com/ 22 | -------------------------------------------------------------------------------- /LIABILITY: -------------------------------------------------------------------------------- 1 | Liability for Deliverables 2 | 3 | All Open Mobility Foundation deliverables are provided "AS IS", without warranty of any 4 | kind, express or implied, and OMF, as well as all of its Members and Contributors, 5 | expressly disclaim any warranty of merchantability, fitness for a particular or intended 6 | purpose, accuracy, completeness, non-infringement of third party rights, or any other 7 | warranty. 8 | 9 | In no event shall OMF or any of its officers, directors, agents or Members be liable to 10 | any other person or entity for any loss of profits, loss of use, direct, indirect, incidental, 11 | consequential, punitive, or special damages, whether under contract, tort, warranty, or 12 | otherwise, arising in any way out of this Policy, whether or not such party had advance 13 | notice of the possibility of such damages. Limitations to the liability of OMF 14 | Contributors as Contributors are set forth in their Contributor License Agreements. 15 | 16 | In addition, except for grossly negligent or intentionally fraudulent acts, OMF and its 17 | officers, directors, agents, Members and Contributors (and their respective 18 | representatives) shall not be liable to any other person or entity for any loss of profits, 19 | loss of use, direct, indirect, incidental, consequential, punitive, or special damages, 20 | whether under contract, tort, warranty, or otherwise, arising in any way out of this 21 | Policy, whether or not such party had advance notice of the possibility of such damages. 22 | 23 | OMF assumes no responsibility to compile, confirm, update or make public any 24 | assertions of intellectual property rights or claims that might be infringed by an 25 | implementation of an OMF Deliverable. 26 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Default 3 | about: Suggest changes to CDS 4 | title: 5 | 6 | --- 7 | 8 | # CDS Pull Request 9 | 10 | 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). 11 | 12 | To avoid complications and help make the Review process as smooth as possible, make sure to: 13 | 14 | 1. Target [**`dev`**](https://github.com/openmobilityfoundation/curb-data-specification/tree/dev) branch. Please ensure you are targeting **`dev`**, not **`main`**. 15 | 1. Keep the *"Allow edits from maintainers"* button checked to help us resolve some issues for you. 16 | 1. Be ready to resolve any merge conflicts before we approve your Pull Request. 17 | 1. Have an up to date profile, per our Github [community profile](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md#community-profile) guildance. 18 | 19 | ## Explain pull request 20 | 21 | Please provide a clear and concise reason for this pull request and the impact of the change 22 | 23 | ## Is this a breaking change 24 | 25 | 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). 26 | 27 | * Yes, breaking 28 | * No, not breaking 29 | * I'm not sure 30 | 31 | ## Impacted Spec 32 | 33 | Which API(s) will this pull request impact? 34 | 35 | * `Curbs` 36 | * `Events` 37 | * `Metrics` 38 | 39 | ## Additional context 40 | 41 | Add any other context or screenshots about the feature request here. 42 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE/pull_request_template.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Default 3 | about: Suggest changes to CDS 4 | title: 5 | 6 | --- 7 | 8 | # CDS Pull Request 9 | 10 | 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). 11 | 12 | To avoid complications and help make the Review process as smooth as possible, make sure to: 13 | 14 | 1. Target [**`dev`**](https://github.com/openmobilityfoundation/curb-data-specification/tree/dev) branch. Please ensure you are targeting **`dev`**, not **`main`**. 15 | 1. Keep the *"Allow edits from maintainers"* button checked to help us resolve some issues for you. 16 | 1. Be ready to resolve any merge conflicts before we approve your Pull Request. 17 | 1. Have an up to date profile, per our Github [community profile](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md#community-profile) guildance. 18 | 19 | ## Explain pull request 20 | 21 | Please provide a clear and concise reason for this pull request and the impact of the change 22 | 23 | ## Is this a breaking change 24 | 25 | 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). 26 | 27 | * Yes, breaking 28 | * No, not breaking 29 | * I'm not sure 30 | 31 | ## Impacted Spec 32 | 33 | Which API(s) will this pull request impact? 34 | 35 | * `Curbs` 36 | * `Events` 37 | * `Metrics` 38 | 39 | ## Additional context 40 | 41 | Add any other context or screenshots about the feature request here. 42 | -------------------------------------------------------------------------------- /ReleaseNotes.md: -------------------------------------------------------------------------------- 1 | ## 1.1.0 2 | 3 | > Released: 2025-10-27 4 | 5 | The 1.1 release is the first minor release for CDS. 6 | 7 | ### CHANGES 8 | 9 | See the [Milestone 1.1.0](https://github.com/openmobilityfoundation/curb-data-specification/milestone/4) and tagged [PRs](https://github.com/openmobilityfoundation/curb-data-specification/pulls?q=is%3Apr+is%3Aclosed+milestone%3A1.1) and [Issues](https://github.com/openmobilityfoundation/curb-data-specification/issues?q=is%3Aissue%20state%3Aclosed%20milestone%3A1.1) for a full list of changes. 10 | 11 | **Full [Release Notes](https://github.com/openmobilityfoundation/curb-data-specification/releases/tag/1.1.0)** for details. 12 | 13 | ## 1.0.1 14 | 15 | > Released: 2024-12-09 16 | 17 | The 1.0.1 patch release cleans up and clarifies some minor issues and typos to help make the specification clearer. 18 | 19 | ### CHANGES 20 | 21 | See the closed [PRs](https://github.com/openmobilityfoundation/curb-data-specification/pulls?q=is%3Apr+is%3Aclosed+milestone%3A1.0.1) tagged with [Milestone 1.0.1](https://github.com/openmobilityfoundation/curb-data-specification/milestone/6?closed=1) and [Issues](https://github.com/openmobilityfoundation/curb-data-specification/issues?q=is%3Aissue+milestone%3A1.0.1+is%3Aclosed) for a full list of changes. 22 | 23 | **Minor updates** 24 | 25 | - OpenAPI support 26 | - Reference to MDS 27 | - Internal Links 28 | - Event location description 29 | - Street name description 30 | - Accessibility user classes 31 | - Rate maximum fee clarification 32 | - New data source device name field 33 | - New operators 34 | 35 | ### ACKNOWLEDGEMENTS 36 | 37 | Thank you to our current and past [steering committee members](https://github.com/openmobilityfoundation/curb-data-specification/wiki#steering-committee), GitHub pull request and issue creators (Passport, CurbIQ, INRIX, Umojo, Clevercity, @jamesdwilson) for this release, and for the organizations that participated on our weekly [working group calls](https://github.com/openmobilityfoundation/curb-data-specification/wiki#meeting-agendas). 38 | 39 | ## What's Changed 40 | 41 | **Full Changelog**: https://github.com/openmobilityfoundation/curb-data-specification/compare/1.0.0...1.0.1 42 | 43 | ### Additional Updates 44 | 45 | See the [final release page](https://github.com/openmobilityfoundation/curb-data-specification/releases/tag/1.0.1) for any additional updates to these notes 46 | 47 | ## 1.0.0 48 | 49 | > Released: 2022-04-29 50 | 51 | > [Release Plan](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Release-1.0.0) 52 | 53 | The 1.0.0 major release is the first release of the Curb Data Specification (CDS) after over 17 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. CDS is currently being used by over [two dozen organizations](https://github.com/openmobilityfoundation/curb-data-specification/wiki#cds-users). 54 | 55 | ### CHANGES 56 | 57 | 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. 58 | 59 | **_General CDS_** 60 | 61 | - Creation of spec from working group drafts and community code submissions 62 | - See [About CDS](https://www.openmobilityfoundation.org/about-cds/) web page for high level details 63 | 64 | **_Curbs_** 65 | 66 | - 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. 67 | 68 | **_Events_** 69 | 70 | - 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. 71 | 72 | **_Metrics_** 73 | 74 | - 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. 75 | 76 | _Minor Updates_ 77 | 78 | - Formatting of spec, links, TOCs, headers, etc 79 | -------------------------------------------------------------------------------- /data-types.md: -------------------------------------------------------------------------------- 1 | # Curb Data Specification: **Data Types** 2 | 3 | This CDS data types page catalogs the data objects (fields, types, requirements, descriptions) used across CDS APIs and endpoints. 4 | 5 | ## Table of Contents 6 | 7 | - [Custom Attributes](#custom-attributes) 8 | - [Enforcement](#enforcement) 9 | - [Violations](#violations) 10 | - [External Reference](#external-reference) 11 | - [Lane Type](#lane-type) 12 | 13 | ## Custom Attributes 14 | 15 | Custom Attributes are optional additional attributes that do not fit in other fields and objects in CDS. They are unique for the organizations created and consuming the endpoint, that may not apply to other jurisdictions. Examples include custom identifiers, information required by ordinance, vendor attributes, supplemental data, etc. 16 | 17 | The format is one or more JSON name/value pairs, and the values must be a string. If a `custom_attributes` field is provided in Curbs, Areas, Spaces, Objects, or Events endpoints, then the relevant [endpoint](general-information.md#rest-endpoints) must contain the `custom_attribute_dictionary` field, which describes details of the custom fields provided. 18 | 19 | Before creating any custom attributes, the preference is to use existing CDS fields and data objects first. If the fields and data you provide in custom attributes apply to multiple jurisdictions, vendors, and/or scenarios, please open an issue to include new fields in a future CDS release. 20 | 21 | 22 | [Top][toc] 23 | 24 | ## Enforcement 25 | 26 | The Enforcement object describes a specific set of features from a data feed or API that is relevant to an enforcement Curb Event. This allows CDS users to reference detailed enforcement data separate from the main API endpoints. 27 | 28 | Where a citation could represent multiple violations, an enforcement object contains an array that enumerates the violations for a single citation. Where a citation can only represent a single violation, multiple Curb Events may be published, each with a single violation in the array. 29 | 30 | The `enforcement` object is a JSON *object* with the following fields: 31 | 32 | | Name | Type | Required/Optional | Description | 33 | | ---------------- | ------- | ----------------- | ------------- | 34 | | `enforcement_id` | UUID | Required | An identifier unique to the enforcement incident, generated the first time an enforcement event is recorded, and referenced in future related enforcement events. Multiple Curb Events (ex: `vehicle_violation_start`, `vehicle_violation_end`, or `citation_issued`) that relate to the same enforcement activity can share the same `enforcement_id`. | 35 | | `citation_id` | String | Optional | A unique id which represents a single citation. | 36 | | `is_warning` | Boolean | Optional | A boolean value to indicate if the enforcement action is being processed as a warning. | 37 | | `action_taken` | String | Optional | Indicates how the violation was enforced. Typical well-known values are `citation_registered`, `citation_posted`, `citation_served`, or `citation_emailed`. | 38 | | `citation_cost` | String | Optional | The total cost of all violations associated to this enforcement action. | 39 | | `violations` | Array of [Violations](#violations) | Optional | An array of Violation objects that indicate the one-to-many violations associated to this enforcement event. | 40 | 41 | [Top][toc] 42 | 43 | ### Violations 44 | 45 | The Violations object describes the violations associated to an enforcement action that can occur as a Curb Event. 46 | 47 | The `violations` object is a JSON *object* with the following fields: 48 | 49 | | Name | Type | Required/Optional | Description | 50 | | ---------------- | ------ | ----------------- | ------------- | 51 | | `violation_code` | String | Optional | The unique code created by the municipality, city, county, state, federal, or enforcement agency to identify the type of rule being enforced. | 52 | | `violation_name` | String | Optional | The city/municipal, county, state, provincial, or federal code that was violated. | 53 | | `violation_cost` | String | Optional | The original cost associated with the violation. | 54 | 55 | [Top][toc] 56 | 57 | ## External Reference 58 | 59 | An External Reference object describes a specific feature from an external data source that is relevant to a part of CDS data. This allows CDS users to reference other data sources that impact or provide information about a CDS object, and see more details at an external URL. Data sources can be anything available via a URL, including an existing data standard (MDS, WZDx, CWZ, GTFS, GBFS, CDS, etc), a custom feed, API, document, web page, report, etc. 60 | 61 | The `external_reference` object is a JSON *array* with the following fields: 62 | 63 | | Name | Type | Required/Optional | Description | 64 | | ----------------- | ------- | ------------------- | ------------- | 65 | | `reference_url` | URL | Required | A web-accessible identifier URL for the source of the publicly or privately accessible data feed, document, website, etc. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location, event, or policy, etc. | 66 | | `name` | String | Optional | Name of the data source for reference. E.g. "WZDx", "CWZ", "MDS", "GBFS", "GTFS", "CDS". | 67 | | `public` | Boolean | Optional | Is this data source able to be viewed without any sort of authentication? If `true`, the `reference_url` is public. If `false`, the `reference_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the feed user, and does not provide any credentials directly unless explicitly contained in the `reference_url`. | 68 | | `identifier_name` | String | Optional | The name of the data field or object that is referenced by the unique `ids`. E.g. "id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in `reference_url`. | 69 | | `ids` | Array of Strings | Optional | An array of one or more **ids** from the `reference_url` that impacts the use of or relationship to part of CDS, e.g. a curb zone, curb space, curb area, curb event, etc. The **ids** and their details can be found in the referenced `reference_url`. | 70 | 71 | [Top][toc] 72 | 73 | ### Lane Type 74 | 75 | Type(s) of lane referenced by the curb policy or event, in or outside of curb zones. 76 | 77 | | Name | Description | 78 | | -------------- | ------------------------------------------------------ | 79 | | `travel_lane` | A standard vehicle travel lane. | 80 | | `turn_lane` | A dedicated turn lane. | 81 | | `center_turn_lane` | A center lane available for turns in both directions. Sometimes used for courier parking for loading activity. | 82 | | `bike_lane` | A lane dedicated for usage by cyclists. | 83 | | `bus_lane` | A lane dedicated for usage by buses. | 84 | | `parking` | A lane used for parking, not allowed for travel. | 85 | | `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. | 86 | | `median` | An often unpaved, non-drivable area that separates sections of the roadway. | 87 | | `sidewalk` | A path for pedestrians, usually on the side of the roadway. | 88 | | `unspecified` | Unspecified | 89 | 90 | [Top][toc] 91 | 92 | [toc]: #table-of-contents 93 | -------------------------------------------------------------------------------- /LICENCE: -------------------------------------------------------------------------------- 1 | Creative Commons Attribution 4.0 International Public License 2 | 3 | By exercising the Licensed Rights (defined below), You accept and agree 4 | to be bound by the terms and conditions of this Creative Commons 5 | Attribution 4.0 International Public License ("Public License"). To the 6 | extent this Public License may be interpreted as a contract, You are 7 | granted the Licensed Rights in consideration of Your acceptance of 8 | these terms and conditions, and the Licensor grants You such rights in 9 | consideration of benefits the Licensor receives from making the 10 | Licensed Material available under these terms and conditions. 11 | 12 | 13 | Section 1 -- Definitions. 14 | 15 | a. Adapted Material means material subject to Copyright and Similar 16 | Rights that is derived from or based upon the Licensed Material 17 | and in which the Licensed Material is translated, altered, 18 | arranged, transformed, or otherwise modified in a manner requiring 19 | permission under the Copyright and Similar Rights held by the 20 | Licensor. For purposes of this Public License, where the Licensed 21 | Material is a musical work, performance, or sound recording, 22 | Adapted Material is always produced where the Licensed Material is 23 | synched in timed relation with a moving image. 24 | 25 | b. Adapter's License means the license You apply to Your Copyright 26 | and Similar Rights in Your contributions to Adapted Material in 27 | accordance with the terms and conditions of this Public License. 28 | 29 | c. Copyright and Similar Rights means copyright and/or similar rights 30 | closely related to copyright including, without limitation, 31 | performance, broadcast, sound recording, and Sui Generis Database 32 | Rights, without regard to how the rights are labeled or 33 | categorized. For purposes of this Public License, the rights 34 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 35 | Rights. 36 | 37 | d. Effective Technological Measures means those measures that, in the 38 | absence of proper authority, may not be circumvented under laws 39 | fulfilling obligations under Article 11 of the WIPO Copyright 40 | Treaty adopted on December 20, 1996, and/or similar international 41 | agreements. 42 | 43 | e. Exceptions and Limitations means fair use, fair dealing, and/or 44 | any other exception or limitation to Copyright and Similar Rights 45 | that applies to Your use of the Licensed Material. 46 | 47 | f. Licensed Material means the artistic or literary work, database, 48 | or other material to which the Licensor applied this Public 49 | License. 50 | 51 | g. Licensed Rights means the rights granted to You subject to the 52 | terms and conditions of this Public License, which are limited to 53 | all Copyright and Similar Rights that apply to Your use of the 54 | Licensed Material and that the Licensor has authority to license. 55 | 56 | h. Licensor means the individual(s) or entity(ies) granting rights 57 | under this Public License. 58 | 59 | i. Share means to provide material to the public by any means or 60 | process that requires permission under the Licensed Rights, such 61 | as reproduction, public display, public performance, distribution, 62 | dissemination, communication, or importation, and to make material 63 | available to the public including in ways that members of the 64 | public may access the material from a place and at a time 65 | individually chosen by them. 66 | 67 | j. Sui Generis Database Rights means rights other than copyright 68 | resulting from Directive 96/9/EC of the European Parliament and of 69 | the Council of 11 March 1996 on the legal protection of databases, 70 | as amended and/or succeeded, as well as other essentially 71 | equivalent rights anywhere in the world. 72 | 73 | k. You means the individual or entity exercising the Licensed Rights 74 | under this Public License. Your has a corresponding meaning. 75 | 76 | 77 | Section 2 -- Scope. 78 | 79 | a. License grant. 80 | 81 | 1. Subject to the terms and conditions of this Public License, 82 | the Licensor hereby grants You a worldwide, royalty-free, 83 | non-sublicensable, non-exclusive, irrevocable license to 84 | exercise the Licensed Rights in the Licensed Material to: 85 | 86 | a. reproduce and Share the Licensed Material, in whole or 87 | in part; and 88 | 89 | b. produce, reproduce, and Share Adapted Material. 90 | 91 | 2. Exceptions and Limitations. For the avoidance of doubt, where 92 | Exceptions and Limitations apply to Your use, this Public 93 | License does not apply, and You do not need to comply with 94 | its terms and conditions. 95 | 96 | 3. Term. The term of this Public License is specified in Section 97 | 6(a). 98 | 99 | 4. Media and formats; technical modifications allowed. The 100 | Licensor authorizes You to exercise the Licensed Rights in 101 | all media and formats whether now known or hereafter created, 102 | and to make technical modifications necessary to do so. The 103 | Licensor waives and/or agrees not to assert any right or 104 | authority to forbid You from making technical modifications 105 | necessary to exercise the Licensed Rights, including 106 | technical modifications necessary to circumvent Effective 107 | Technological Measures. For purposes of this Public License, 108 | simply making modifications authorized by this Section 2(a) 109 | (4) never produces Adapted Material. 110 | 111 | 5. Downstream recipients. 112 | 113 | a. Offer from the Licensor -- Licensed Material. Every 114 | recipient of the Licensed Material automatically 115 | receives an offer from the Licensor to exercise the 116 | Licensed Rights under the terms and conditions of this 117 | Public License. 118 | 119 | b. No downstream restrictions. You may not offer or impose 120 | any additional or different terms or conditions on, or 121 | apply any Effective Technological Measures to, the 122 | Licensed Material if doing so restricts exercise of the 123 | Licensed Rights by any recipient of the Licensed 124 | Material. 125 | 126 | 6. No endorsement. Nothing in this Public License constitutes or 127 | may be construed as permission to assert or imply that You 128 | are, or that Your use of the Licensed Material is, connected 129 | with, or sponsored, endorsed, or granted official status by, 130 | the Licensor or others designated to receive attribution as 131 | provided in Section 3(a)(1)(A)(i). 132 | 133 | b. Other rights. 134 | 135 | 1. Moral rights, such as the right of integrity, are not 136 | licensed under this Public License, nor are publicity, 137 | privacy, and/or other similar personality rights; however, to 138 | the extent possible, the Licensor waives and/or agrees not to 139 | assert any such rights held by the Licensor to the limited 140 | extent necessary to allow You to exercise the Licensed 141 | Rights, but not otherwise. 142 | 143 | 2. Patent and trademark rights are not licensed under this 144 | Public License. 145 | 146 | 3. To the extent possible, the Licensor waives any right to 147 | collect royalties from You for the exercise of the Licensed 148 | Rights, whether directly or through a collecting society 149 | under any voluntary or waivable statutory or compulsory 150 | licensing scheme. In all other cases the Licensor expressly 151 | reserves any right to collect such royalties. 152 | 153 | 154 | Section 3 -- License Conditions. 155 | 156 | Your exercise of the Licensed Rights is expressly made subject to the 157 | following conditions. 158 | 159 | a. Attribution. 160 | 161 | 1. If You Share the Licensed Material (including in modified 162 | form), You must: 163 | 164 | a. retain the following if it is supplied by the Licensor 165 | with the Licensed Material: 166 | 167 | i. identification of the creator(s) of the Licensed 168 | Material and any others designated to receive 169 | attribution, in any reasonable manner requested by 170 | the Licensor (including by pseudonym if 171 | designated); 172 | 173 | ii. a copyright notice; 174 | 175 | iii. a notice that refers to this Public License; 176 | 177 | iv. a notice that refers to the disclaimer of 178 | warranties; 179 | 180 | v. a URI or hyperlink to the Licensed Material to the 181 | extent reasonably practicable; 182 | 183 | b. indicate if You modified the Licensed Material and 184 | retain an indication of any previous modifications; and 185 | 186 | c. indicate the Licensed Material is licensed under this 187 | Public License, and include the text of, or the URI or 188 | hyperlink to, this Public License. 189 | 190 | 2. You may satisfy the conditions in Section 3(a)(1) in any 191 | reasonable manner based on the medium, means, and context in 192 | which You Share the Licensed Material. For example, it may be 193 | reasonable to satisfy the conditions by providing a URI or 194 | hyperlink to a resource that includes the required 195 | information. 196 | 197 | 3. If requested by the Licensor, You must remove any of the 198 | information required by Section 3(a)(1)(A) to the extent 199 | reasonably practicable. 200 | 201 | 4. If You Share Adapted Material You produce, the Adapter's 202 | License You apply must not prevent recipients of the Adapted 203 | Material from complying with this Public License. 204 | 205 | 206 | Section 4 -- Sui Generis Database Rights. 207 | 208 | Where the Licensed Rights include Sui Generis Database Rights that 209 | apply to Your use of the Licensed Material: 210 | 211 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 212 | to extract, reuse, reproduce, and Share all or a substantial 213 | portion of the contents of the database; 214 | 215 | b. if You include all or a substantial portion of the database 216 | contents in a database in which You have Sui Generis Database 217 | Rights, then the database in which You have Sui Generis Database 218 | Rights (but not its individual contents) is Adapted Material; and 219 | 220 | c. You must comply with the conditions in Section 3(a) if You Share 221 | all or a substantial portion of the contents of the database. 222 | 223 | For the avoidance of doubt, this Section 4 supplements and does not 224 | replace Your obligations under this Public License where the Licensed 225 | Rights include other Copyright and Similar Rights. 226 | 227 | 228 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 229 | 230 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 231 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 232 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 233 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 234 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 235 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 236 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 237 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 238 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 239 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 240 | 241 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 242 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 243 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 244 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 245 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 246 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 247 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 248 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 249 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 250 | 251 | c. The disclaimer of warranties and limitation of liability provided 252 | above shall be interpreted in a manner that, to the extent 253 | possible, most closely approximates an absolute disclaimer and 254 | waiver of all liability. 255 | 256 | 257 | Section 6 -- Term and Termination. 258 | 259 | a. This Public License applies for the term of the Copyright and 260 | Similar Rights licensed here. However, if You fail to comply with 261 | this Public License, then Your rights under this Public License 262 | terminate automatically. 263 | 264 | b. Where Your right to use the Licensed Material has terminated under 265 | Section 6(a), it reinstates: 266 | 267 | 1. automatically as of the date the violation is cured, provided 268 | it is cured within 30 days of Your discovery of the 269 | violation; or 270 | 271 | 2. upon express reinstatement by the Licensor. 272 | 273 | For the avoidance of doubt, this Section 6(b) does not affect any 274 | right the Licensor may have to seek remedies for Your violations 275 | of this Public License. 276 | 277 | c. For the avoidance of doubt, the Licensor may also offer the 278 | Licensed Material under separate terms or conditions or stop 279 | distributing the Licensed Material at any time; however, doing so 280 | will not terminate this Public License. 281 | 282 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 283 | License. 284 | 285 | 286 | Section 7 -- Other Terms and Conditions. 287 | 288 | a. The Licensor shall not be bound by any additional or different 289 | terms or conditions communicated by You unless expressly agreed. 290 | 291 | b. Any arrangements, understandings, or agreements regarding the 292 | Licensed Material not stated herein are separate from and 293 | independent of the terms and conditions of this Public License. 294 | 295 | 296 | Section 8 -- Interpretation. 297 | 298 | a. For the avoidance of doubt, this Public License does not, and 299 | shall not be interpreted to, reduce, limit, restrict, or impose 300 | conditions on any use of the Licensed Material that could lawfully 301 | be made without permission under this Public License. 302 | 303 | b. To the extent possible, if any provision of this Public License is 304 | deemed unenforceable, it shall be automatically reformed to the 305 | minimum extent necessary to make it enforceable. If the provision 306 | cannot be reformed, it shall be severed from this Public License 307 | without affecting the enforceability of the remaining terms and 308 | conditions. 309 | 310 | c. No term or condition of this Public License will be waived and no 311 | failure to comply consented to unless expressly agreed to by the 312 | Licensor. 313 | 314 | d. Nothing in this Public License constitutes or may be interpreted 315 | as a limitation upon, or waiver of, any privileges and immunities 316 | that apply to the Licensor or You, including from the legal 317 | processes of any jurisdiction or authority. 318 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Curb Data Specification 2 | 3 | ## Table of Contents 4 | 5 | - [About](#about) 6 | - [Endpoints](#endpoints) 7 | - [Structure](#structure) 8 | - [Modularity](#modularity) 9 | - [MDS Overlap](#mds-overlap) 10 | - [Versions](#versions) 11 | - [Technical Information](#technical-information) 12 | - [Data Validation](#data-validation) 13 | - [Get Involved](#get-involved) 14 | - [Membership](#membership) 15 | - [Organizations Using CDS](#organizations-using-cds) 16 | - [Data Privacy](#data-privacy) 17 | - [Use Cases](#use-cases) 18 | 19 | # About 20 | 21 | 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 all their curb and on and off street parking programs, and allow companies to use static and dynamic curb zones that optimize loading activities of people, goods, and services, and measure the impact of these programs. 22 | 23 | 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 provides a mechanism for expressing static and dynamic parking and access regulations, measuring activity at the curb with clear metrics, and developing policies that create more accessible, useful curbs. 24 | 25 | **CDS** is a key piece of globally used digital infrastructure that supports the effective implementation of curb, loading, and parking 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. 26 | 27 | ![Curb Data Specification Logo](https://i.imgur.com/iGPCZyQ.png) 28 | 29 | [Top][toc] 30 | 31 | # Endpoints 32 | 33 | 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 operators using various curb and parking places. It includes the following three APIs, with multiple endpoints under each API: 34 | 35 | --- 36 | 37 | CDS Curbs Icon 38 | 39 | The [`Curbs`](/curbs/) API is a standard way for cities to digitally publish curb locations and parking regulations and policy, which can be shared with the public and with companies using curb space. It defines curb policies, curb zones, spaces in zones, areas around curbs, and objects near or at the curb, and is used by Events and Metrics. 40 | 41 | --- 42 | 43 | CDS Events Icon 44 | 45 | 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 sent from company data feeds directly, 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. 46 | 47 | --- 48 | 49 | CDS Metrics Icon 50 | 51 | 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. 52 | 53 | --- 54 | 55 | 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. 56 | 57 | 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. 58 | 59 | ## Structure 60 | 61 | CDS contains a series of connected endpoints and fields beneath each interconnected API. 62 | 63 |

64 | 65 | ## Modularity 66 | 67 | 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, test CDS in their pilot projects, or use CDS for digitally managing parking operations. 68 | 69 | ![CDS APIs and Endpoints](https://i.imgur.com/PejQC4R.png) 70 | 71 | ## MDS Overlap 72 | 73 | Like the [Mobility Data Specification](https://github.com/openmobilityfoundation/mobility-data-specification/) (MDS), CDS is two-way and will be produced and consumed by both cities, transportation providers, and vendors operating in the public right of way. CDS Curbs is analogous to MDS [Policy](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/policy) rules and geofencing (which uses MDS [Geography](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/geography) and [Jurisdiction](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/jurisdiction)), CDS Events to events data in MDS [Agency](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/agency)/[Provider](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/provider), and CDS Metrics to MDS [Metrics](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/metrics). In many existing jurisdictions , the same mobility providers using CDS are also using MDS to manage vehicles, services, and communicate right of way rules and policies. 74 | 75 | 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 latest version of CDS does allow connections by reference to MDS (and other specs), and vice versa, down to an overlapping field level. Future versions of MDS and CDS may lead to a more complete integration into a single, unified specification - [get involved](#get-involved) if interested. 76 | 77 | [Top][toc] 78 | 79 | # Versions 80 | 81 | CDS has a **current release** (version 1.1.0), 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. 82 | 83 | 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. 84 | 85 | ## Technical Information 86 | 87 | 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. 88 | 89 | The CDS specification is versioned using Git tags and [semantic versioning](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md#versioning). 90 | 91 | * [Latest Release Branch](https://github.com/openmobilityfoundation/curb-data-specification/tree/main) (main) 92 | * [Development Branch](https://github.com/openmobilityfoundation/curb-data-specification/tree/dev) (dev) 93 | * [All GitHub Releases](https://github.com/openmobilityfoundation/curb-data-specification/releases) 94 | * [CDS Releases](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Releases) - current/recommended versions, timeline 95 | * [Release Guidelines](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md) 96 | 97 | [Top][toc] 98 | 99 | ## Data Validation 100 | 101 | For CDS data and feed validation, please see the [OpenAPI schema description](https://github.com/openmobilityfoundation/cds-openapi). Interactive OpenAPI documentation for the CDS APIs, endpoints, fields, and data objects is also available on OMF's [Stoplight Interactive Documentation](https://openmobilityfnd.stoplight.io/docs/cds-openapi/83teyinnn1py6-curb-api) page. 102 | 103 | # Get Involved 104 | 105 | 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 and parking 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). 106 | 107 | 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 [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. 108 | 109 | 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). 110 | 111 | [Top][toc] 112 | 113 | ## Membership 114 | 115 | OMF Members (public agencies and commercial companies) have additional participation opportunities with leadership roles within our OMF [governance](https://github.com/openmobilityfoundation/governance#omf-scope-of-work): 116 | 117 | - [Board of Directors](https://www.openmobilityfoundation.org/about/) 118 | - [Privacy, Security, and Transparency Committee](https://github.com/openmobilityfoundation/privacy-committee) 119 | - [Technology Council](https://github.com/openmobilityfoundation/governance/wiki/Technology-Council) 120 | - [Strategy Committee](https://github.com/openmobilityfoundation/governance/wiki/Strategy-Committee) 121 | - [Advisory Committee](https://github.com/openmobilityfoundation/governance/wiki/Advisory-Committee) 122 | - Steering committees of all [Working Groups](https://github.com/openmobilityfoundation/mobility-data-specification/wiki#omf-meetings), currently: 123 | - [MDS Working Group](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Working-Group) 124 | - [Curb Working Group](https://github.com/openmobilityfoundation/curb-data-specification/wiki) 125 | 126 | Read about [how to become an OMF member](https://www.openmobilityfoundation.org/how-to-become-a-member/), [how to get involved and our governance model](https://www.openmobilityfoundation.org/how-to-get-involved-in-the-open-mobility-foundation/), and [contact us](https://mailchi.mp/openmobilityfoundation/membership) for more details. 127 | 128 | [Top][toc] 129 | 130 | # Organizations Using CDS 131 | 132 | Cities and public agencies, technology companies, commercial curb users, and operators are using CDS now and in the near term. 133 | 134 | - See our **[list of organizations using CDS](https://github.com/openmobilityfoundation/curb-data-specification/wiki#cds-users)**. 135 | 136 | Please let us know [via our website](https://www.openmobilityfoundation.org/get-in-touch/) if you are an organization using CDS so we can add you to the list. 137 | 138 | If you are a data source operator, you should also add yourself to the [operator list](/data_source_operators.csv) for a global ID and website link. Let us know [via our website](https://www.openmobilityfoundation.org/get-in-touch/) or find out how to do it yourself in our [Adding a CDS Data Source Operator ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Data-Source-Operator-ID) help document. 139 | 140 | [Top][toc] 141 | 142 | # Data Privacy 143 | 144 | CDS includes information about 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 unless required for the viability of a specific program, 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: 145 | 146 | * [CDS Privacy Guidance](https://docs.google.com/document/d/1nujWaj1ScxQ-1I9_BGrMKZ_mV_8mbk8tG_C21CQO7Cw/edit?usp=sharing) - identifies relevant data in CDS, use cases, and provides suggestions on the safe handling of this data. 147 | * [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 148 | * [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 149 | * [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 150 | * [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. 151 | 152 | 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). 153 | 154 | [Top][toc] 155 | 156 | # Use Cases 157 | 158 | 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. 159 | 160 | 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). 161 | 162 | [Top][toc] 163 | 164 | [toc]: #table-of-contents 165 | -------------------------------------------------------------------------------- /metrics/README.md: -------------------------------------------------------------------------------- 1 | # Curb Data Specification: Metrics API 2 | 3 | CDS Metrics Icon 4 | 5 | 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. 6 | 7 | **See [other CDS APIs](/README.md#endpoints) on the homepage.** 8 | 9 | # Endpoints 10 | 11 | There are two different endpoints that are part of the Metrics API: 12 | 13 | - [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. 14 | - [Aggregate](#aggregate) is aggregated counts and methodology of curb events. Aggregates is *optional* within Metrics. 15 | 16 | **See [examples](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Metrics-Examples) for these endpoints.** 17 | 18 | # Table of Contents 19 | 20 | - [Representative Sample Data](#representative-sample-data) 21 | - [REST Endpoints](#rest-endpoints) 22 | - [Authorization](#authorization) 23 | * [Update Frequency](#update-frequency) 24 | * [Query Session](#query-session) 25 | * [Query Aggregate](#query-aggregate) 26 | - [Data Objects](#data-objects) 27 | * [Session](#session) 28 | * [Aggregate](#aggregate) 29 | * [Methodology](#methodology) 30 | - [Examples](#examples) 31 | - [Schema](#schema) 32 | 33 | # Representative Sample Data 34 | 35 | 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. 36 | 37 | # REST Endpoints 38 | 39 | All endpoints return a CSV file that can either be pre-computed or created on demand dynamically. 40 | 41 | 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. 42 | 43 | If returning data from a dynamic server, they MUST set the `Content-Type` header to `application/vnd.cds+csv;version=1.1` to support 44 | versioning in the future. Clients SHOULD specify an `Accept` header containing 45 | `application/vnd.cds+csv;version=1.1`. If the server receives a request that contains an `Accept` 46 | header but does not include this value; it MUST respond with a status of `406 Not Acceptable`. 47 | 48 | [Top][toc] 49 | 50 | ## Authorization 51 | 52 | [Authorization](/general-information.md#authorization) is **recommended** 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. 53 | 54 | Some jurisdictinos may allow publicly available endpoints or reports to help enable cross-vendor collaboration, data analysis, and Open Data goals. Agencies wishing to publicly release Metrics data are encouraged to limit releases to static [Aggregate](#aggregate) data that has been reviewed for potential privacy risks. Consult our [Privacy Guidance](/README.md#data-privacy) for more details. 55 | 56 | [Top][toc] 57 | 58 | ## Update Frequency 59 | 60 | 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. 61 | 62 | [Top][toc] 63 | 64 | ## Query Session 65 | 66 | **Endpoint**: `/metrics/sessions` 67 | **Method**: `GET` 68 | `data` **Payload**: a CSV object with the following fields: 69 | - `session`: an array of [Session](#session) objects 70 | 71 | _Optional endpoint; if not implemented, a server should reply with 501 Not Implemented._ 72 | 73 | ### Query Parameters 74 | 75 | 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. 76 | 77 | | Name | Type | Required/Optional | Description | 78 | | ------------ | --------- | ----------------- | ---------------------------------------------- | 79 | | `curb_place_type` | Enum | Optional | The type of curb place this aggregate applies to from the Curbs API: `area`, `zone`, `space`, `object`. Required with `curb_place_id`. | 80 | | `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`. | 81 | | `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. | 82 | | `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. | 83 | | `start_time` | [Timestamp][ts] | Optional | The start of the time period to return data (_inclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). | 84 | | `end_time` | [Timestamp][ts] | Optional | The end of the time period to return data (_exclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). | 85 | 86 | [Top][toc] 87 | 88 | ## Query Aggregate 89 | 90 | **Endpoint**: `/metrics/aggregates` 91 | **Method**: `GET` 92 | `data` **Payload**: a CSV object with the following fields: 93 | - `aggregate`: an array of [Aggregate](#aggregate) objects 94 | 95 | _Optional endpoint; if not implemented, a server should reply with 501 Not Implemented._ 96 | 97 | ### Query Parameters 98 | 99 | 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. 100 | 101 | | Name | Type | Required/Optional | Description | 102 | | ------------ | --------- | ----------------- | ---------------------------------------------- | 103 | | `curb_place_type` | Enum | Optional | The type of curb place this aggregate applies to from the Curbs API: `area`, `zone`, `space`, `object`. Required with `curb_place_id`. | 104 | | `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`. | 105 | | `metric_type` | Enum | Optional | The single metric to return from the [Methodology](#methodology): `total_sessions`, `total_events`, `turnover`, `average_dwell_time`, `occupancy_percent`. | 106 | | `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. | 107 | | `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. | 108 | | `start_time` | [Timestamp][ts] | Optional | The start of the time period to return data (_inclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). | 109 | | `end_time` | [Timestamp][ts] | Optional | The end of the time period to return data (_exclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). | 110 | 111 | [Top][toc] 112 | 113 | # Data Objects 114 | 115 | ## Session 116 | 117 | 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. 118 | 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. 119 | 120 | A Session is represented as a CSV object, whose fields are as follows, pulled from the Curb Events endpoint in the Events API: 121 | 122 | | Name | Type | Required/Optional | Description | 123 | | ------ | ------ | ------------------- | ------------- | 124 | | `session_type` | Enum | Required | The type of session that happened for this event: `parking` or `area` | 125 | | `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). | 126 | | `event_id_start` | [UUID][uuid] | Conditionally Required | The globally unique identifier of the **start/enter** event that occurred. | 127 | | `event_id_end` | [UUID][uuid] | Conditionally Required | The globally unique identifier of the **end/exit** event that occurred. | 128 | | `event_location_start_latitude` | Number | Conditionally Required | The geographic latitude point location where the **start/enter** of the event occurred. | 129 | | `event_location_start_longitude` | Number | Conditionally Required | The geographic longitude point location where the **start/enter** of the event occurred. | 130 | | `event_location_end_latitude` | Number | Conditionally Required | The geographic latitude point location where the **end/exit** of the event occurred. | 131 | | `event_location_end_longitude` | Number | Conditionally Required | The geographic longitude point location where the **end/exit** of the event occurred. | 132 | | `event_time_start` | [Timestamp][ts] | Conditionally Required | Timestamp (date/time) at which the event started with the `park_start` or `enter_area` event types. | 133 | | `event_time_end` | [Timestamp][ts] | Conditionally Required | Timestamp (date/time) at which the event occurred. | 134 | | `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_. | 135 | | `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_ | 136 | | `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_ | 137 | | `curb_object_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Object where the event occurred. Required for events that occurred at a known Curb Object for these event_types: _park_start, park_end, enter_area, exit_area_ | 138 | | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | 139 | | `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. | 140 | 141 | ### Event Types 142 | 143 | The following Event Types are relevant to the Session data, and the other event types are not utilized. 144 | 145 | For `session_type` of `parking`: 146 | - **park_start**: a vehicle stopped, parked, or double parked 147 | - **park_end**: a parked vehicle leaving a parked or stopped state and resuming movement 148 | 149 | For `session_type` of `area`: 150 | - **enter_area**: vehicle enters the relevant geographic area 151 | - **exit_area**: vehicle exits the relevant geographic area 152 | 153 | **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_. 154 | 155 | A "session duration" or "dwell time" can be calculated by calculating the difference between the `event_time_start` and `event_time_end`. 156 | 157 | [Top][toc] 158 | 159 | ## Aggregate 160 | 161 | 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). 162 | 163 | An Aggregate is represented as a CSV object, whose fields are as follows, as calculated from the Metrics [Methodology](#methodology): 164 | 165 | | Name | Type | Required/Optional | Description | 166 | | ------ | ------ | ------------------- | ------------- | 167 | | `curb_place_type` | Enum | Required | The type of curb place this aggregate applies to from the Curbs API: `area`, `zone`, `space`, `object`. | 168 | | `curb_place_id` | [UUID][uuid] | Required | The ID of this curb place. | 169 | | `metric_type` | Enum | Required | The metric this aggregate applies to from the [Methodology](#methodology): `total_sessions`, `total_events`, `turnover`, `average_dwell_time`, `occupancy_percent`. | 170 | | `date` | date | Required | The date the event occured in ISO 8601 format, local timezone, in "YYYY-MM-DD" format. E.g. "2021-10-31" | 171 | | `hour` | integer | Required | The hour of the day the event occured in ISO 8601 format, local timezone, in "hh" format. E.g. "23" | 172 | | `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" | 173 | 174 | ### Methodology 175 | 176 | 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, 177 | 178 | #### Total Sessions 179 | 180 | `count[sessions]` for a specific time period 181 | Name: `total_sessions` 182 | 183 | _Use Case_ 184 | 185 | 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. 186 | 187 | #### Total Events 188 | 189 | `count[events]` for a specific time period 190 | Name: `total_events` 191 | 192 | _Use Case_ 193 | 194 | Similar to `total_sessions`, cities use this to determine ‘demand’ for curb space and understand how many users have arrived for a given area for a period of time. Some examples for this include: seeing how many vehicles arrived and parked in a neighborhood (counting `park_start` event types), estimating occupancy with LPR (counting `vehicle_read` event types), or tracking enforcement by seeing how many tickets were handed out for a specific zone (counting `citation_issued` event types). 195 | 196 | #### Turnover 197 | 198 | `count[sessions]/hour` for a specific time period 199 | Name: `turnover` 200 | 201 | _Use Case_ 202 | 203 | Used together with Average Dwell Time by cities to understand how long vehicles are parked at the curb. When evaluated alongside a vehicle type breakdown, cities can see if the curb space is being used as intended and design better rules for compliance. 204 | 205 | #### Average Dwell Time 206 | 207 | `sum[dwell time] / count[sessions]` for a specific time period 208 | Name: `average_dwell_time` 209 | 210 | _Use Case_ 211 | 212 | Turnover and Average Dwell Time are used together by cities to understand how long vehicles are parked at the curb. When evaluated alongside a vehicle type breakdown, cities can see if the curb space is being used as intended and design better rules for compliance. 213 | 214 | For example, a city may want to impose a 5 minute time limit for a restaurant pick-up and drop-off zone if they see that a lot of vehicles are in that space for 30 minutes to help prioritize the quick pick-up and drop-offs. 215 | 216 | Another example would be if a city sees that a space has large vehicles with an average dwell time of 90 minutes or more they may want to make sure their time limits and operating hours can accommodate these deliveries so that companies aren’t having to leave mid-delivery to move their vehicle. 217 | 218 | #### Occupancy Percent 219 | 220 | `sum[dwell time] / total duration` for a specific time period 221 | Name: `occupancy_percent` 222 | 223 | _Use Case_ 224 | 225 | Occupancy is a metric from parking that cities would like to apply to curbs. With parking there’s an optimal occupancy where most of the parking spaces are in-use but there are enough open spaces for any vehicle to be able to drive up and find a space. Cities are interested to learn what the optimal occupancy would be for curbs. With so much competition at the curb, cities want to make sure that any loading zones they create are being used a lot, but not so much that they’re full and drivers have to double-park instead. 226 | 227 | [Top][toc] 228 | 229 | # Examples 230 | 231 | See the [CDS Metrics Examples](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Metrics-Examples) wiki page for code examples of specific Metrics use cases, and ideas on how Metrics can be implemented. 232 | 233 | [Top][toc] 234 | 235 | # Schema 236 | 237 | For details on the CDS schema in OpenAPI format and on Stoplight, please reference the [CDS OpenAPI](https://github.com/openmobilityfoundation/cds-openapi) repository. 238 | 239 | [Top][toc] 240 | 241 | [toc]: #table-of-contents 242 | [uuid]: /general-information.md#uuid 243 | [ts]: /general-information.md#timestamp 244 | [polygon]: /general-information.md#polygon 245 | -------------------------------------------------------------------------------- /general-information.md: -------------------------------------------------------------------------------- 1 | # Curb Data Specification: General Information 2 | 3 | CDS Curbs Icon 4 | 5 | This document contains specifications and common concepts that are shared between the various CDS APIs, such as [`Curbs`](/curbs), [`Events`](/events), and [`Metrics`](/metrics). 6 | 7 | # Table of Contents 8 | 9 | - [Authorization](#authorization) 10 | - [Beta Features](#beta-features) 11 | - [Costs and Currencies](#costs-and-currencies) 12 | - [Event Times](#event-times) 13 | - [Geographic Data](#geographic-data) 14 | - [Geographic Telemetry Data](geographic-telemetry-data) 15 | - [Polygon](#polygon) 16 | - [LineString](#linestring) 17 | - [Point](#Point) 18 | - [Intersection Operation](#intersection-operation) 19 | - [Pagination](#pagination) 20 | - [Range Boundaries](#range-boundaries) 21 | - [Responses](#responses) 22 | - [REST Endpoints](#rest-endpoints) 23 | - [Schema](#schema) 24 | - [Timestamp](#timestamp) 25 | - [Unit of Time Enum](#unit-of-time-enum) 26 | - [UUID](#uuid) 27 | - [Versioning](#versioning) 28 | 29 | # Authorization 30 | 31 | CDS implementers **SHALL** provide authorization for API endpoints via a bearer token based auth system, when required. 32 | 33 | For example, the `Authorization` header sent as part of an HTTP request: 34 | 35 | ``` 36 | GET /events/event HTTP/1.1 37 | Host: api.operator.com 38 | Authorization: Bearer 39 | ``` 40 | 41 | More info on how to document [Bearer Auth in swagger](https://swagger.io/docs/specification/authentication/bearer-authentication/) 42 | 43 | ## JSON Web Tokens 44 | 45 | JSON Web Token ([JWT](https://jwt.io/introduction/)) is **RECOMMENDED** as the token format. 46 | 47 | JWTs provide a safe, secure way to verify the identity of an agency and provide access to CDS resources without providing access to other, potentially sensitive data. 48 | 49 | > 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. 50 | 51 | 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. 52 | 53 | JWT provides a helpful [debugger](https://jwt.io/#debugger) for testing your token and verifying security. 54 | 55 | ## OAuth 2.0 56 | 57 | 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. 58 | 59 | 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. 60 | 61 | 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. 62 | 63 | ## Endpoint Authentication Requirements 64 | 65 | All endpoints marked authenticated **SHALL** be authenticated, to protect potentially sensitive information. 66 | 67 | # Beta Features 68 | 69 | 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. 70 | 71 | Despite this, CDS users are highly encouraged to use beta features. New features can only become proven and trusted through implementation, use, and the learning that comes with it. Users should be thoughtful about the role of beta features in their operations. Users of beta features are strongly encouraged to share their experiences, learnings, and challenges with the broader CDS community via GitHub issues or pull requests. This will inform the refinements that transform beta features into fully proven, stable parts of the specification. 72 | 73 | Beta features may be suitable for enabling some new tools and analysis, but may not be appropriate for mission-critical applications or regulatory decisions where certainty and reliability are essential. In subsequent releases existing beta features may include breaking changes, even in a minor release. 74 | 75 | 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. 76 | 77 | [Top][toc] 78 | 79 | # Costs and currencies 80 | 81 | Fields specifying a monetary cost use a currency as specified in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). 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 (100 cents). 82 | 83 | If the currency field is null, USD cents is implied. 84 | 85 | [Top][toc] 86 | 87 | # Definitions 88 | 89 | Defining terminology and abbreviations used throughout CDS. 90 | 91 | - API - Application Programming Interface - A function or set of functions/endpoints that allow one software application to access or communicate with features of a different software application or service. 92 | - API Endpoint - A point at which an API connects with a software application or service. 93 | - Curb Places - One of the defined Curb API areas: Areas, Zones, or Spaces. 94 | - Curb Area - A geographically defined area around one or more Curb Zones to track releated activity before and after Curb Zone use. 95 | - Curb Zone - A geographically and policy defined area where transactions may happen at curb space. 96 | - Curb Space - A geographically defined area within a Curb Zone for a single vehicle. 97 | 98 | # Event Times 99 | 100 | 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. 101 | 102 | 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. 103 | 104 | # Geographic Data 105 | 106 | References to geographic datatypes (Point, MultiPolygon, LineString, etc.) imply coordinates encoded in the [WGS 84 (EPSG:4326)][wgs84] standard GPS or GNSS projection expressed as [Decimal Degrees][decimal-degrees]. 107 | 108 | ## Geographic Telemetry Data 109 | 110 | 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: 111 | 112 | 113 | | Field | Type | Required/Optional | Field Description | 114 | | -------------- | --------------- | --------------------- | ------------------------------------------------------------ | 115 | | `timestamp` | [timestamp][ts] | Required | Date/time that event occurred. Based on GPS or GNSS clock | 116 | | `altitude` | Double | Required if Available | Altitude above mean sea level in meters | 117 | | `heading` | Double | Required if Available | Degrees - clockwise starting at 0 degrees at true North | 118 | | `speed` | Float | Required if Available | Estimated speed in meters / sec as reported by the GPS chipset | 119 | | `accuracy` | Float | Required if Available | Horizontal accuracy, in meters | 120 | | `hdop` | Float | Required if Available | Horizontal GPS or GNSS accuracy value (see [hdop][hdop]) | 121 | | `satellites` | Integer | Required if Available | Number of GPS or GNSS satellites | 122 | 123 | Example of a vehicle location GeoJSON [`Feature`][geojson-feature] object: 124 | 125 | ```json 126 | { 127 | "type": "Feature", 128 | "properties": { 129 | "timestamp": 1529968782421, 130 | "accuracy": 10, 131 | "speed": 1.21 132 | }, 133 | "geometry": { 134 | "type": "Point", 135 | "coordinates": [ 136 | -118.46710503101347, 137 | 33.9909333514159 138 | ] 139 | } 140 | } 141 | ``` 142 | 143 | ## Polygon 144 | 145 | A polygon is a GeoJSON geometry of type `"Polygon"` as defined in 146 | [RFC 7946 3.1.6](https://www.ietf.org/rfc/rfc7946.txt). An example polygon is: 147 | 148 | ``` 149 | { 150 | "type": "Polygon", 151 | "coordinates": [[ 152 | [-73.982105, 40.767932], 153 | [-73.973694, 40.764551], 154 | [-73.949318, 40.796918], 155 | [-73.958416, 40.800686], 156 | [-73.982105, 40.767932] 157 | ]] 158 | } 159 | ``` 160 | 161 | ## LineString 162 | 163 | A linestring is a GeoJSON geometry of type `"LineString"` (polyline) as defined in 164 | [RFC 7946 3.1.6](https://www.ietf.org/rfc/rfc7946.txt). An example linestring is: 165 | 166 | ``` 167 | { 168 | "type": "LineString", 169 | "coordinates": [ 170 | [-73.982105, 40.767932], 171 | [-73.973694, 40.764551], 172 | [-73.970913, 40.763627] 173 | ] 174 | } 175 | ``` 176 | 177 | ## Point 178 | 179 | A point is a GeoJSON geometry of type `"Point"` as defined in 180 | [RFC 7946 3.1.6](https://www.ietf.org/rfc/rfc7946.txt). An example point is: 181 | 182 | ``` 183 | { 184 | "type": "Point", 185 | "coordinates": [ 186 | -73.982105, 40.767932 187 | ] 188 | } 189 | ``` 190 | 191 | ## Intersection Operation 192 | 193 | For the purposes of this specification, the intersection of two geographic datatypes is defined according to the [`ST_Intersects` PostGIS operation][st-intersects] 194 | 195 | > 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). 196 | > 197 | > 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. 198 | 199 | [Top][toc] 200 | 201 | # Pagination 202 | 203 | Endpoints may use pagination, which must comply with the [JSON API](http://jsonapi.org/format/#fetching-pagination) specification. See [Event Times](/general-information.md#event-times) guidance about the order of data returned. 204 | 205 | The following keys must be used for pagination links: 206 | 207 | * `first`: url to the first page of data 208 | * `last`: url to the last page of data 209 | * `prev`: url to the previous page of data 210 | * `next`: url to the next page of data 211 | 212 | 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. 213 | 214 | ```json 215 | { 216 | "version": "x.y.z", 217 | "data": { 218 | "endpoint": [{ 219 | "field_name": "..." 220 | }] 221 | }, 222 | "links": { 223 | "first": "https://...", 224 | "last": "https://...", 225 | "prev": "https://...", 226 | "next": "https://..." 227 | } 228 | } 229 | ``` 230 | 231 | In general, a 'page-based strategy' is preferred to allow for page counts, but a 'cursor-based strategy' is acceptable, per [JSON API](http://jsonapi.org/format/#fetching-pagination). 232 | 233 | [Top][toc] 234 | 235 | # Range Boundaries 236 | 237 | All ranges across the spec of timestamps, times, measurements, dates, etc are 'inclusive' at the start and 'exclusive' at the end, unless otherwise noted. 238 | 239 | For example: 240 | 241 | - `start_datetime`: "2021-08-12 00:00:00" and `end_datetime`: "2021-08-13 00:00:00" 242 | 243 | 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`. 244 | 245 | All HH:MM times in CDS are in UTC, unless otherwise specified at the field level. 246 | 247 | [Top][toc] 248 | 249 | # Responses 250 | 251 | List of acceptable endpoint responses. 252 | 253 | * **200:** OK: operation successful. 254 | * **201:** Created: `POST` operations, new object created 255 | * **400:** Bad request. 256 | * **401:** Unauthorized: Invalid, expired, or insufficient scope of token. 257 | * **404:** Not Found: Object does not exist, returned on `GET` or `POST` operations if the object does not exist. 258 | * **406:** Not Acceptable. Invalid response. 259 | * **409:** Conflict: `POST` operations when an object already exists and an update is not possible. 260 | * **500:** Internal server error: In this case, the answer may contain a `text/plain` body with an error message for troubleshooting. 261 | * **501:** Not Implemented. 262 | 263 | ## Error Messages 264 | 265 | ```json 266 | { 267 | "error": "...", 268 | "error_description": "...", 269 | "error_details": [ "...", "..." ] 270 | } 271 | ``` 272 | 273 | | Field | Type | Field Description | 274 | | ------------------- | -------- | ---------------------- | 275 | | `error` | String | Error message string | 276 | | `error_description` | String | Human readable error description (can be localized) | 277 | | `error_details` | String[] | Array of error details | 278 | 279 | [Top][toc] 280 | 281 | ### Bulk Responses 282 | 283 | For multi-record POST and PUT calls, e.g. sending Events using the post method, the bulk-response structure describes a list of failures is as follows: 284 | 285 | ```jsonc 286 | { 287 | "success": "...", 288 | "total": "...", 289 | "failures": [ { // list of failure details 290 | "item": { ... }, // copy of the item with the problem 291 | "error": "...", 292 | "error_description": "...", 293 | "error_details": [ "...", "..." ] 294 | }, { 295 | // additional failure records 296 | } ] 297 | } 298 | ``` 299 | 300 | | Field | Type | Field Description | 301 | | ---------- | ------------------------------------- | --------------------------------------------------------------- | 302 | | `success` | Integer | Number of successfully written records | 303 | | `total` | Integer | Total number of provided records | 304 | | `failures` | [Failure Details](#failure-details)[] | Array of details about failed records (empty if all successful) | 305 | 306 | ### Failure Details 307 | 308 | | Field | Type | Field Description | 309 | | ------------------- | -------------------- | --------------------------------------------------- | 310 | | `item` | Event, etc. | Invalid submitted item | 311 | | `error` | Enum | Error code | 312 | | `error_description` | String | Human readable error description (can be localized) | 313 | | `error_details` | String[] | Array of fields with errors, if applicable | 314 | 315 | # REST Endpoints 316 | 317 | All dynamic REST endpoints will return a JSON object containing the following fields: 318 | 319 | | Name | Type | Required/Optional | Description | 320 | | ------ | ------ | ------------------- | ------------- | 321 | | `data` | _Endpoint-dependent_ | Required | The requested data objects. | 322 | | `version` | String | Required | The specification version that the API conforms to (e.g. `1.0.0`) | 323 | | `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"`). | 324 | | `last_updated` | [timestamp][ts] | Required | The last time the data in this API was updated. | 325 | | `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). | 326 | | `custom_attributes_dictionary` | URL | Conditionally Required | The data dictionary containing information on the fields and values in [Custom Attributes](/data-types.md#custom-attributes). This should include the attribute name, data type, associated CDS element if applicable, and description of what the attribute represents. Required if any Custom Attributes are provided in an Endpoint. | 327 | | `author` | String | Optional | The name of the organization that produces and maintains this data. | 328 | | `license_url` | URL | Optional | The licensing terms under which this data is provided. | 329 | 330 | Servers MUST set the `Content-Type` header to `application/vnd.cds+json;version=1.0` to support 331 | versioning in the future. Clients SHOULD specify an `Accept` header containing 332 | `application/vnd.cds+json;version=1.0`. If the server receives a request that contains an `Accept` 333 | header but does not include this value; it MUST respond with a status of `406 Not Acceptable`. 334 | 335 | [Top][toc] 336 | 337 | # Schema 338 | 339 | For CDS data and feed validation, please see the [OpenAPI schema description](https://github.com/openmobilityfoundation/cds-openapi). Interactive OpenAPI documentation for the CDS APIs, endpoints, fields, and data objects is also available on OMF's [Stoplight Interactive Documentation](https://openmobilityfnd.stoplight.io/docs/cds-openapi/83teyinnn1py6-curb-api) page. 340 | 341 | [Top][toc] 342 | 343 | # Timestamp 344 | 345 | 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. 346 | 347 | [Top][toc] 348 | 349 | # Unit of Time Enum 350 | 351 | An enumeration for units of time. Defined as "second", "minute", "hour", "day", "week", "month", and "year". 352 | 353 | [Top][toc] 354 | 355 | # UUID 356 | 357 | A UUID is a 128-bit, globally unique identifier represented as a string using the format defined in 358 | [RFC 4122](https://www.ietf.org/rfc/rfc4122.txt). An example UUID is 359 | `"98bd30e9-14cc-4e71-bee2-7bab0f28b2bd"`. UUIDs used in the Curbs API may be of any format described 360 | in RFC 4122, including time-based (V1), random (V4), or name-based (V5). 361 | 362 | [Top][toc] 363 | 364 | # Versioning 365 | 366 | CDS APIs must handle requests for specific versions of the specification from clients. 367 | 368 | Versioning must be implemented through the use of a custom media-type, `application/vnd.cds+json`, combined with a required `version` parameter. 369 | 370 | 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` 371 | 372 | Clients must specify the version they are targeting through the `Accept` header. For example: 373 | 374 | ```http 375 | Accept: application/vnd.cds+json;version=1.2.0 376 | ``` 377 | 378 | If an unsupported or invalid version is requested, the API must respond with a status of `406 Not Acceptable`. 379 | 380 | [Top][toc] 381 | 382 | [decimal-degrees]: https://en.wikipedia.org/wiki/Decimal_degrees 383 | [hdop]: https://en.wikipedia.org/wiki/Dilution_of_precision_(navigation) 384 | [geo]: #geographic-data 385 | [geojson-feature]: https://tools.ietf.org/html/rfc7946#section-3.2 386 | [geojson-point]: https://tools.ietf.org/html/rfc7946#section-3.1.2 387 | [st-intersects]: https://postgis.net/docs/ST_Intersects.html 388 | [toc]: #table-of-contents 389 | [ts]: /general-information.md#timestamps 390 | [wgs84]: https://en.wikipedia.org/wiki/World_Geodetic_System 391 | -------------------------------------------------------------------------------- /events/README.md: -------------------------------------------------------------------------------- 1 | # Curb Data Specification: Events API 2 | 3 | CDS Events Icon 4 | 5 | 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, directly from operators, 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. 6 | 7 | **See [other CDS APIs](/README.md#endpoints) on the homepage.** 8 | 9 | # Endpoints 10 | 11 | There are two different endpoints that are part of the Events API: 12 | 13 | - 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. 14 | - A [Status](#status) is the current status of a curb monitoring source. Event status is *optional*. 15 | 16 | **See [examples](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Metrics-Examples) for these endpoints.** 17 | 18 | # Table of Contents 19 | 20 | - [REST Endpoints](#rest-endpoints) 21 | - [Authorization](#authorization) 22 | * [Query Event](#query-event) 23 | * [Query Status](#query-status) 24 | * [Push Event](#push-event) 25 | * [Responses and Error Messages](#responses-and-error-messages) 26 | - [Data Objects](#data-objects) 27 | * [Curb Event](#curb-event) 28 | * [Event Type](#event-type) 29 | * [Source Type](#source-type) 30 | * [Vehicle Type](#vehicle-type) 31 | * [Propulsion Type](#propulsion-type) 32 | * [Event Purpose](#event-purpose) 33 | * [Payment Channel](#payment-channel) 34 | * [Payment Method](#payment-method) 35 | * [Curb Occupant](#curb-occupants) 36 | * [Status](#status) 37 | - [Examples](#examples) 38 | - [Schema](#schema) 39 | 40 | # REST Endpoints 41 | 42 | All endpoints return a JSON object containing the fields as specified in the [REST Endpoint](/general-information.md#rest-endpoints) details. 43 | 44 | [Top][toc] 45 | 46 | ## Authorization 47 | 48 | [Authorization](/general-information.md#authorization) is **recommended** for Events endpoints, since (depending on implementation, use cases, and fields required) it may contain information only city transporation agencies should have access to. 49 | 50 | [Top][toc] 51 | 52 | ## Query Event 53 | 54 | **Endpoint**: `/events/events` 55 | **Method**: `GET` 56 | **Authorization**: recommended 57 | `data` **Payload**: a JSON object with the following fields: 58 | - `events`: an array of [Curb Event](#curb-event) objects. See [Event Times](/general-information.md#event-times) guidance about the order of data returned. 59 | 60 | _This endpoint must be implemented by every Events API server._ 61 | 62 | ### Query Parameters 63 | 64 | All query parameters are optional. 65 | 66 | | Name | Type | Description | 67 | | ------------ | --------- | ---------------------------------------------- | 68 | | `event_time` | String | An ISO 8601 extended datetime representing an UTC hour between 00 and 23 in format `YYYY-MM-DDTHH`. Specifies the hour for which data should be returned. If omitted the API should return all events in the last 60 minutes. For example, requesting `event_time=2019-10-01T07` returns all events where `2019-10-01T07:00:00 <= event.event_time < 2019-10-01T08:00:00` UTC. | 69 | | `curb_area_id` | [UUID][uuid] | The ID of a [Curb Area](#curb-area). If specified, only return events occurring within this area. | 70 | | `curb_zone_id` | [UUID][uuid] | The ID of a [Curb Zone](#curb-zone). If specified, only return events occurring within this zone. | 71 | | `curb_space_id` | [UUID][uuid] | The ID of a [Curb Space](#curb-space). If specified, only return events occurring within this space. | 72 | | `curb_object_id` | [UUID][uuid] | The ID of a [Curb Object](#curb-object). If specified, only return events occurring at this object. | 73 | 74 | [Top][toc] 75 | 76 | ## Query Status 77 | 78 | **Endpoint**: `/events/status` 79 | **Method**: `GET` 80 | **Authorization**: recommended 81 | `data` **Payload**: a JSON object with a `status` field containing an array of [Status](#status) objects. 82 | 83 | _Optional endpoint, as required by public agencies; if not implemented, the server should reply with `501 Not Implemented` if possible._ 84 | 85 | ### Query Parameters 86 | 87 | All query parameters are optional. 88 | 89 | | Name | Type | Description | 90 | | ------------ | --------- | ---------------------------------------------- | 91 | | `curb_area_id` | [UUID][uuid] | The ID of a [Curb Area](#curb-area). If specified, only return sensor statuses within this area. | 92 | | `curb_zone_id` | [UUID][uuid] | The ID of a [Curb Zone](#curb-zone). If specified, only return sensor statuses within this zone. | 93 | | `curb_space_id` | [UUID][uuid] | The ID of a [Curb Space](#curb-space). If specified, only return sensor statuses within this space. | 94 | | `curb_object_id` | [UUID][uuid] | The ID of a [Curb Object](#curb-object). If specified, only return sensor statuses at this object. | 95 | 96 | [Top][toc] 97 | 98 | ## Push Event 99 | 100 | **Endpoint**: `/events/event` 101 | **Method**: `POST` 102 | **Authorization**: required 103 | `data` **Payload**: an array of [Curb Event](#curb-event) `events` objects. 104 | 105 | _Optional endpoint, as required by public agencies; if not implemented, the server should reply with `501 Not Implemented`._ 106 | 107 | Servers implementing a `POST /events/event` API should be able to deduplicate events from a publisher based upon the `event_id` field. It should be expected that some events can be resent as a result of restoring connections between systems interrupted by network or system errors. 108 | 109 | ### Responses 110 | 111 | _Possible HTTP Status Codes_: 112 | 200, 113 | 201, 114 | 400, 115 | 401, 116 | 404, 117 | 406, 118 | 409, 119 | 500, 120 | 501 121 | 122 | See [Responses](#responses-and-error-messages) for details. 123 | 124 | ### Event Errors: 125 | 126 | | `error` | `error_description` | `error_details`[] | 127 | | ------- | ------------------- | ----------------- | 128 | | `bad_param` | A validation error occurred | Array of parameters with errors | 129 | | `missing_param` | A required parameter is missing | Array of missing parameters | 130 | 131 | [Top][toc] 132 | 133 | ### Responses and Error Messages 134 | 135 | The response to a client request must include a valid HTTP status code defined in the [IANA HTTP Status Code Registry][iana]. 136 | 137 | The response must set the `Content-Type` header as specified in the [Versioning section][versioning]. 138 | 139 | Response bodies must be a `UTF-8` encoded JSON object. 140 | 141 | See the [Responses][responses], [Error Messages][error-messages], and [Bulk Responses][bulk-responses] sections, and the [schema][schema] for more details. 142 | 143 | [Top][toc] 144 | 145 | # Data Objects 146 | 147 | ## Curb Event 148 | 149 | A Curb Event is a record of activity that happens within the geographic bounds of a Curbs object. 150 | 151 | A Curb Event is represented as a JSON object, whose fields are as follows: 152 | 153 | | Name | Type | Required/Optional | Description | 154 | | ------ | ------ | ------------------- | ------------- | 155 | | `event_id` | [UUID][uuid] | Required | The globally unique identifier of the event that occurred. | 156 | | `event_type` | [Event Type](#event-type) | Required | The event_type that happened for this event. | 157 | | `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. | 158 | | `event_location` | [GeoJSON Point](/general-information.md#point) | Optional | The geographic point location where the event occurred. All efforts should be made to provide this field, even if slightly imprecise. But there may be times when a location is impossible or irrelevant. | 159 | | `event_time` | [Timestamp][ts] | Required | Time at which the event occurred. | 160 | | `event_publication_time` | [Timestamp][ts] | Required | Time at which the event became available for consumption by this API. | 161 | | `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. | 162 | | `curb_zone_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Zone where the event occurred. Required for events that occurred in a known Curb Zone, if known and used, for ALL _event_types_. | 163 | | `curb_area_ids` | Array of [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 ALL _event_types_. | 164 | | `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 ALL _event_types_. | 165 | | `curb_object_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Object where the event occurred. Required for events that occurred at a known Curb Object, if known and used, for ALL _event_types_. | 166 | | `data_source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | 167 | | `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. | 168 | | `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. | 169 | | `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). | 170 | | `data_source_device_name` | String | Conditionally Required | Unique name 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 usually the internal ID they use for the device. Must be provided if the device has a visible or shared identifier. If this field is needed for your use cases, review our [Privacy Guidance](/README.md#data-privacy). | 171 | | `data_source_manufacturer` | String | Optional | Manufacturer of the data source hardware or vehicle reporting event data. | 172 | | `data_source_model` | String | Optional | Model of the data source hardware or vehicle reporting event data. | 173 | | `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. | 174 | | `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. | 175 | | `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). _Note: in the next breaking CDS release, it is likely all of these "vehicle_" fields will be moved to a Vehicles data object._ | 176 | | `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). The detection of stealth, invisible, modified, ghost, or otherwise ANPR-evading plate violations may be recorded using the `enforcement` field and associated [Enforcement][enforcement] object. | 177 | | `vehicle_license_plate_jurisdiction` | String | Optional | Jurisdiction or state in which the `vehicle_license_plate` is registered. | 178 | | `vehicle_license_plate_confidence` | Integer | Optional | Value from 1 to 100 specifying the recognition confidence level for `vehicle_license_plate`. | 179 | | `vehicle_permit_number` | String | Optional | If applicable, the assigned permit number for this vehicle from the city agency. | 180 | | `vehicle_length` | Integer | Conditionally Required | Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length. | 181 | | `vehicle_type` | [Vehicle Type](#vehicle-type) | Conditionally Required | Type of the vehicle that performed the event. Required for sources capable of determining vehicle type. | 182 | | `vehicle_type_confidence` | Integer | Optional | Value from 1 to 100 specifying the recognition confidence level for `vehicle_type`. | 183 | | `vehicle_color` | String | Optional | Color of the vehicle that performed the event. | 184 | | `vehicle_color_confidence` | Integer | Optional | Value from 1 to 100 specifying the recognition confidence level for `vehicle_color`. | 185 | | `vehicle_company_name` | String | Optional | Company or courier name of the vehicle that performed the event. | 186 | | `vehicle_company_name_confidence` | Integer | Optional | Value from 1 to 100 specifying the recognition confidence level for `vehicle_company_name`. | 187 | | `vehicle_run_id` | String | Optional | Run identifier from an external runs table containing information about make, model, and/or year, of the vehicle that performed the event. | 188 | | `vehicle_run_id_confidence` | Integer | Optional | Value from 1 to 100 specifying the recognition confidence level for `vehicle_run_id`. | 189 | | `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. | 190 | | `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_ | 191 | | `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_ | 192 | | `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). | 193 | | `enforcement` | [Enforcement][enforcement] | Optional | Enforcement information related to this Curb Event, relevant to the moment in time the event happens. Only used for enforcement related events such as `vehicle_detected`, `vehicle_violation_start`, `vehicle_violation_end`, and `citation_issued`. | 194 | | `payment_channel` | [Payment Channel](#payment-channel) | Conditionally Required | If available from the source, the medium by which a user submitted payment. | 195 | | `payment_method` | [Payment Method](#payment-method) | Conditionally Required | If available from the source, the method used to pay for this event. | 196 | | `payment_transaction_id` | String | Conditionally Required | The transaction ID of the payment if available from the source and different from the `event_id`. | 197 | | `custom_attributes`| [Custom Attributes](/data-types.md#custom-attributes) JSON Object | Optional | Additional attributes (fields and data) to include in this [endpoint](/general-information.md#rest-endpoints). | 198 | | `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references to external data sources impacting this Curb Event. The external reference is relevant to the moment in time the event happens. | 199 | 200 | [Top][toc] 201 | 202 | ### Event Type 203 | 204 | Curb Event Type `event_type` enumerates the set of possible types of Curb Event. The values that it can assume are listed below: 205 | 206 | | Name | Description | 207 | |--------------------|-------------| 208 | | `comms_lost` | Communications with the event source were lost | 209 | | `comms_restored` | Communications with the event source were restored | 210 | | `decommissioned` | Event source was decommissioned | 211 | | `park_start` | A vehicle stopped, parked, or double parked | 212 | | `park_end` | A parked vehicle leaving a parked or stopped state and resuming movement | 213 | | `scheduled_report` | Event source reported status at a scheduled interval | 214 | | `enter_area` | Vehicle enters the relevant geographic area. This differs from `vehicle_detected` since `enter_area` represents the tracking of a vehicle crossing the geo-boundary of an area/location. | 215 | | `exit_area` | Vehicle exits the relevant geographic area | 216 | | `vehicle_detected` | Detection or observation of a vehicle within or near a curb zone. Can originate from manual surveying, automated license plate recognition (LPR) systems, or other detection methods. This differs from the `enter_area` and `exit_area` events where a `vehicle_detected` event does not require the vehicle to be crossing the geo-boundary of an area/location. | 217 | | `vehicle_violation_start` | Start of a compliance violation at a curb location, triggered when a vehicle is not permitted or has exceeded allowed time limits. This event may be published after detecting a vehicle but does not require a `vehicle_detected` event. | 218 | | `vehicle_violation_end` | Resolution of a compliance violation, when the vehicle is no longer in violation of regulations. Used for time-based violations where the end of the violation can be detected. Requires a preceding `vehicle_violation_start` event for the same vehicle. | 219 | | `citation_issued` | Issuance of a ticket or citation to a vehicle. May be published in addition to a related `vehicle_violation_start` event. | 220 | 221 | [Top][toc] 222 | 223 | ### Source Type 224 | 225 | 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: 226 | 227 | | Name | Description | 228 | |----------------| ----------- | 229 | | `data_feed` | Directly from a provider data feed sent to the agency | 230 | | `camera` | Video or static image processing source | 231 | | `above_ground` | Sensor deployed above ground | 232 | | `in_ground` | Sensor deployed in the ground | 233 | | `meter` | A smart parking meter | 234 | | `payment` | From payment system or app | 235 | | `in_person` | An individual on site recording the event digitally or otherwise | 236 | | `other` | Sources not enumerated above | 237 | 238 | [Top][toc] 239 | 240 | ### Vehicle Type 241 | 242 | Type of vehicle `vehicle_type` similar to [vehicle_type](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/data-types.md#vehicle-types) in MDS. In the next major MDS and CDS releases, alignment between vehicle types can occur. 243 | 244 | | Name | Description | 245 | |----------------- | ----------- | 246 | | `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) | 247 | | `bus` | A vehicle larger than a car or small truck capable of transporting multiple passengers at once | 248 | | `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) | 249 | | `car` | A passenger car or similar light-duty vehicle | 250 | | `delivery_robot` | A robot or remote-operated device intended for transporting goods | 251 | | `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 | 252 | | `scooter_standing` | A standing fully-motorized mobility device without a seat intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles | 253 | | `scooter_seated` | A fully-motorized mobility device with a seat intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles | 254 | | `moped` | A seated fully-motorized mobility device capable of travel at moderate or high speeds and suited for operation in general urban traffic | 255 | | `motorcycle` | A seated mobility device capable of travel at high speeds and suited for operation in general urban traffic or expressways | 256 | | `truck` | A box truck or large delivery truck with attached cab | 257 | | `van` | A van with significant interior cargo space | 258 | | `freight` | A large delivery truck with attached cab | 259 | | `other` | A device that does not fit in the other categories | 260 | | `unspecified` | Unspecified | 261 | 262 | [Top][toc] 263 | 264 | ### Propulsion Type 265 | 266 | 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. 267 | 268 | | Name | Description | 269 | | -------------------- | ------------------------------------------------------ | 270 | | `human` | Pedal or foot propulsion | 271 | | `electric_assist` | Provides electric motor assist only in combination with human propulsion - no throttle mode | 272 | | `electric` | Powered by battery-powered electric motor with throttle mode | 273 | | `combustion` | Powered by gasoline combustion engine | 274 | | `combustion_diesel` | Powered by diesel combustion engine | 275 | | `hybrid` | Powered by combined combustion engine and battery-powered motor | 276 | | `hydrogen_fuel_cell` | Powered by hydrogen fuel cell powered electric motor | 277 | | `plug_in_hybrid` | Powered by combined combustion engine and battery-powered motor with plug-in charging | 278 | 279 | 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"]`. 280 | 281 | [Top][toc] 282 | 283 | ### Event Purpose 284 | 285 | 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. 286 | 287 | | Name | Description | 288 | | --------------------- | ------------------------------------------------------ | 289 | | `construction` | Construction of hard assets including buildings and roadside infrastructure | 290 | | `delivery` | General delivery of parcels, goods, freight | 291 | | `emergency_use` | Includes ambulance, fire truck, police | 292 | | `parking` | Vehicle parking, charging, or stopping | 293 | | `passenger_transport` | Picking up and/or dropping off of human passengers | 294 | | `special_events` | Includes unloading equipment for concerts, theatre, street events | 295 | | `waste_management` | Retrieval/disposal of waste | 296 | | `device_maintenance` | Includes scooter pickup, drop off, battery swapping | 297 | | `autonomous` | Autonomous vehicle use | 298 | | `ems` | Emergency medical vehicle use | 299 | | `fire` | Emergency fire vehicle | 300 | | `food_delivery` | Delivery of food items ready for consumption to an end consumer | 301 | | `parcel_delivery` | Delivery of parcels, including bulk food goods to a restaurant or other business | 302 | | `police` | Use by a police vehicle | 303 | | `public_transit` | Includes large or small buses or paratransit. | 304 | | `ride_hail` | Includes privately run ride hailing services | 305 | | `road_maintenance` | Includes pothole patching, striping, snow plowing, street sweeping | 306 | | `service_vehicles` | Includes private sector activity like some utilities | 307 | | `taxi` | Traditionally licensed taxi services | 308 | | `utility_work` | Includes public sector activity like sewer, water, telecoms | 309 | | `vehicle_charging` | Parking for electric vehicles to charge | 310 | | `vehicle_parking` | Includes private or commercial vehicle free or paid/metered parking | 311 | | `vending` | Mobile vending or food truck curb uses | 312 | | `unspecified` | Unknown or unspecified activity type | 313 | 314 | [Top][toc] 315 | 316 | ### Payment Channel 317 | 318 | The payment channel describes the medium or platform used to pay for a curb 319 | event. This helps disambiguate a credit card payment made at a physical meter 320 | from a credit card payment made via a mobile app, for example. 321 | 322 | | Name | Description | 323 | | ----------------- | ------------------------------------------------------ | 324 | | `meter` | User paid at a physical meter. | 325 | | `mobile_app` | Paid via a mobile app, including iOS App Clips, and Android Instant App. | 326 | | `sms` | Paid via text message. | 327 | | `telephone` | Paid via a telephone call. | 328 | | `website` | User went to a standard website to pay, maybe directed by QR code. | 329 | | `other` | Some payment channel not captured above (please submit a pull request!). | 330 | 331 | [Top][toc] 332 | 333 | ### Payment Method 334 | 335 | Strings used to indicate how a curb user paid for a curb event. 336 | 337 | | Name | Description | 338 | | ----------------- | ------------------------------------------------------ | 339 | | `cash` | Bills or coins at a meter. | 340 | | `credit_card` | Visa, Mastercard, etc at a meter. | 341 | | `digital_wallet` | Payment disbursed from a digital wallet such as Apple Pay, Google Pay, Cash App, PayPal, or Venmo, etc. `credit_card` is preferred if the payment is made from a credit card via a digital wallet. | 342 | | `smart_card` | A specialized smart card. | 343 | | `membership_card` | A card used at a meter to pay via a corporate membership or loyalty program, etc. | 344 | | `billing` | Curb user will be billed for usage at a later time. | 345 | | `permit` | Curb user has a permit allowing them to use the curb without payment. | 346 | | `voucher` | Curb user paid with a pre-issued voucher. | 347 | | `courtesy` | At a curb that normally requires payment this event for some reason did not. | 348 | | `test` | This was a test payment/event. | 349 | | `other` | Some payment method not captured above (please submit a pull request!). | 350 | 351 | [Top][toc] 352 | 353 | ### Curb Occupants 354 | 355 | 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: 356 | 357 | | Name | Type | Required/Optional | Description | 358 | | ----------------- | -------------- | ----------------------- | ----------- | 359 | | `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". 360 | | `length` | Float | Conditionally required | The approximate length in centimeters of the vehicle. Required when the event source is capable of determining vehicle length. 361 | | `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. 362 | 363 | [Top][toc] 364 | 365 | ## Status 366 | 367 | The Curb Status is the current status of sensors that are monitoring curb places. 368 | 369 | A Curb Status is represented as a JSON object array of all deployed sensors, whose fields are as follows: 370 | 371 | | Name | Type | Required/Optional | Description | 372 | | ------ | ------ | ------------------- | ------------- | 373 | | `data_source_device_id` | [UUID][uuid] | Required | Unique identifier of this event source, whether sensor, vehicle, camera, etc. | 374 | | `data_source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. | 375 | | `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. | 376 | | `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. | 377 | | `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. | 378 | 379 | [Top][toc] 380 | 381 | # Examples 382 | 383 | See the [CDS Events Examples](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Events-Examples) wiki page for code examples of specific Events use cases, and ideas on how Events can be implemented. 384 | 385 | [Top][toc] 386 | 387 | # Schema 388 | 389 | For details on the CDS schema in OpenAPI format and on Stoplight, please reference the [CDS OpenAPI](https://github.com/openmobilityfoundation/cds-openapi) repository. 390 | 391 | [Top][toc] 392 | 393 | [bulk-responses]: /general-information.md#bulk-responses 394 | [enforcement]: ../data-types.md#enforcement 395 | [lane-type]: ../data-types.md#lane-type 396 | [violations]: ../data-types.md#violations 397 | [error-messages]: /general-information.md#error-messages 398 | [external-reference]: ../data-types.md#external-reference 399 | [iana]: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml 400 | [polygon]: /general-information.md#polygon 401 | [responses]: /general-information.md#responses 402 | [schema]: /general-information.md#schema/ 403 | [toc]: #table-of-contents 404 | [ts]: /general-information.md#timestamp 405 | [uuid]: /general-information.md#uuid 406 | [versioning]: /general-information.md#versioning 407 | -------------------------------------------------------------------------------- /curbs/README.md: -------------------------------------------------------------------------------- 1 | # Curb Data Specification: Curbs API 2 | 3 | CDS Curbs Icon 4 | 5 | The Curbs API is a REST API allowing cities to specify areas of interest along and around the curb, objects in and 6 | near the curb or on sidewalks or travel lanes, and off street parking areas. Included are 7 | the rules and policies for using these area: who is allowed to park, load, unload, pick up, drop off, etc., 8 | for how long, for what price (if any), at what times, and on which days. 9 | 10 | Locations defined in the Curbs API can be connected to [Event](/events) and [Metrics](/metrics) data, and can be shared with companies and the public, for 11 | purposes such as routing, finding legal parking, loading, and pick-up/drop-off spots, enforcement, compliance, and analyzing 12 | curb utilization over time. 13 | 14 | **See [other CDS APIs](/README.md#endpoints) on the homepage.** 15 | 16 | # Endpoints 17 | 18 | There are four different endpoints that are part of the Curbs API: 19 | 20 | - A [Curb Zone](#curb-zone) is a contiguous region of curb space on a single block face that is 21 | regulated in a particular way. Defining curb zones is *required* as part of the Curbs API. 22 | - A [Curb Space](#curb-space) is a defined vehicle parking spot along the curb for use by one 23 | vehicle at a time. Curb spaces are *optional*. 24 | - A [Curb Area](#curb-area) is a larger area of interest, such as a neighborhood or corridor, that 25 | could be used to show proximity, approaches, conflicts, circling, or other activity. Curb areas 26 | are *optional*. 27 | - A [Curb Object](#curb-object) is a physical item or asset located adjacent to, within, or associated with a curb space 28 | that is grouped under a certain type and contains a unique set of attributes. Curb objects are *optional*. 29 | - A [Curb Policy](#policy) A Policy is a rule that allows or prohibits a particular set of 30 | users from using a particular curb at a particular time or times. Curb policies are *optional* 31 | but recommended with Curb Zones. 32 | 33 | **See [examples](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Metrics-Examples) for these endpoints.** 34 | 35 | ![Curb Places](https://i.imgur.com/SxUlTHr.gif) 36 | 37 | # Table of Contents 38 | 39 | - [REST Endpoints](#rest-endpoints) 40 | - [Authorization](#authorization) 41 | - [Query Curb Zones](#query-curb-zones) 42 | - [Query Curb Areas](#query-curb-areas) 43 | - [Query Curb Spaces](#query-curb-spaces) 44 | - [Query Curb Policies](#query-curb-policies) 45 | - [Query Curb Objects](#query-curb-objects) 46 | - [Fetch a Curb Zone](#fetch-a-curb-zone) 47 | - [Fetch a Curb Area](#fetch-a-curb-area) 48 | - [Fetch a Curb Space](#fetch-a-curb-space) 49 | - [Fetch a Curb Policy](#fetch-a-curb-policy) 50 | - [Fetch a Curb Object](#fetch-a-curb-object) 51 | - [Data Objects](#data-objects) 52 | - [Curb Zone](#curb-zone) 53 | - [Curb Area](#curb-area) 54 | - [Curb Space](#curb-space) 55 | - [Curb Object](#curb-object) 56 | - [Object Types](#object-types) 57 | - [Policy](#policy) 58 | - [Rule](#rule) 59 | - [Activities](#activities) 60 | - [User Classes](#user-classes) 61 | - [Purposes](#purposes) 62 | - [Time Span](#time-span) 63 | - [Rate](#rate) 64 | - [Location Reference](#location-reference) 65 | - [Previous Policy](#previous-policy) 66 | - [Policy Color](#policy-color) 67 | - [Examples](#examples) 68 | - [Schema](#schema) 69 | 70 | # REST Endpoints 71 | 72 | All endpoints return a JSON object containing the fields as specified in the [REST Endpoint](/general-information.md#rest-endpoints) details. 73 | 74 | [Top][toc] 75 | 76 | ## Authorization 77 | 78 | [Authorization](/general-information.md#authorization) is not required for any of the Curbs endpoints, as this information should be made public and easily accessible. 79 | Free to acquire API keys or authorization may be utilized by the public agency to track usage, prevent abuse, or for certain mobility programs or pilots. 80 | 81 | [Top][toc] 82 | 83 | ## Query Curb Zones 84 | 85 | **Endpoint**: `/curbs/zones` 86 | **Method**: `GET` 87 | `data` **Payload**: a JSON object with a `zones` field containing an array of [Curb Zone](#curb-zone) objects. 88 | 89 | _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._ 90 | 91 | ### Query Parameters 92 | 93 | All query parameters are optional. 94 | 95 | | Name | Type | Description | 96 | | ------------ | --------- | ---------------------------------------------- | 97 | | `area` | [UUID][uuid] | The ID of a [Curb Area](#curb-area). If specified, only return Curb Zones contained within this area. | 98 | | `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. | 99 | | `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. | 100 | | `include_geometry` | `true`/`false` | If the value is `false`, do not include the `geometry` field within the [Curb Zone](#curb-zone) feature object. `true` by default. | 101 | | `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. | 102 | 103 | [Top][toc] 104 | 105 | ## Query Curb Areas 106 | 107 | **Endpoint**: `/curbs/areas` 108 | **Method**: `GET` 109 | `data` **Payload**: a JSON object with an `areas` field containing an array of [Curb Area](#curb-area) objects. 110 | 111 | _Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._ 112 | 113 | ### Query Parameters 114 | 115 | All query parameters are optional. 116 | 117 | | Name | Type | Description | 118 | | ------------ | --------- | ---------------------------------------------- | 119 | | `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 Areas that intersect the supplied bounding box. | 120 | | `lat`
`lng`
`radius` | Numeric | If one of these parameters is specified, all three MUST be. Returns only Curb Areas that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Areas in the response MUST be ordered ascending by distance from the center point. | 121 | 122 | [Top][toc] 123 | 124 | ## Query Curb Spaces 125 | 126 | **Endpoint**: `/curbs/spaces` 127 | **Method**: `GET` 128 | `data` **Payload**: a JSON object with a `spaces` field containing an array of [Curb Space](#curb-space) objects. 129 | 130 | _Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._ 131 | 132 | ### Query Parameters 133 | 134 | All query parameters are optional. 135 | 136 | | Name | Type | Description | 137 | | ------------ | --------- | ---------------------------------------------- | 138 | | `zone` | [UUID][uuid] | The ID of a [Curb Zone](#curb-zone). If specified, only return Curb Spaces contained within this zone. | 139 | | `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. | 140 | | `lat`
`lng`
`radius` | Numeric | If one of these parameters is specified, all three MUST be. Returns only Curb Spaces that are within `radius` centimeters of the point identified by `lat`/`lng`. Curb Spaces in the response MUST be ordered ascending by distance from the center point. | 141 | | `time` | [Timestamp][ts] | Availability data (if supplied) will be returned as of this time. | 142 | 143 | [Top][toc] 144 | 145 | ## Query Curb Policies 146 | 147 | **Endpoint**: `/curbs/policies` 148 | **Method**: `GET` 149 | `data` **Payload**: a JSON object with a `policies` field containing an array of [Curb Policy](#policy) objects. 150 | 151 | _Optional endpoint, but required if Curb Zones contain policy_id references. If not implemented, the server should reply with `501 Not Implemented`._ 152 | 153 | ### Query Parameters 154 | 155 | All query parameters are optional. 156 | 157 | | Name | Type | Description | 158 | | ------------ | --------- | ---------------------------------------------- | 159 | | `ids` | Comma-separated list of [UUIDs][uuid] | If present, return only policies with the supplied UUIDs. Otherwise, return all policies. | 160 | 161 | [Top][toc] 162 | 163 | ## Query Curb Objects 164 | 165 | **Endpoint**: `/curbs/objects` 166 | **Method**: `GET` 167 | `data` **Payload**: a JSON object with a `objects` field containing an array of [Curb Object](#curb-object) objects. 168 | 169 | _Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._ 170 | 171 | ### Query Parameters 172 | 173 | All query parameters are optional. 174 | 175 | | Name | Type | Description | 176 | | ------------ | --------- | ---------------------------------------------- | 177 | | `time` | [Timestamp][ts] | Only the most recently updated objects as of this time will be returned. | 178 | | `zone` | [UUID][uuid] | The ID of a [Curb Zone](#curb-zone). If specified, only return Curb Objects associated within this zone. | 179 | | `space`| [UUID][uuid] | The ID of a [Curb Space](#curb-space). If specified, only return Curb Objects associated within this space. | 180 | 181 | [Top][toc] 182 | 183 | ## Fetch a Curb Zone 184 | 185 | **Endpoint**: `/curbs/zones/` 186 | **Method**: `GET` 187 | `data` **Payload**: the [Curb Zone](#curb-zone) object with the ID provided in the path. 188 | 189 | _Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._ 190 | 191 | ### Query Parameters 192 | 193 | All query parameters are optional. 194 | 195 | | Name | Type | Description | 196 | | --------------- | --------------- | ---------------------------------------------- | 197 | | `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. | 198 | | `show_historic` | Boolean | Whether to return historic, retired curb zone data. Default is "false" to reduce payload size and complexity. | 199 | 200 | [Top][toc] 201 | 202 | ## Fetch a Curb Area 203 | 204 | **Endpoint**: `/curbs/areas/` 205 | **Method**: `GET` 206 | `data` **Payload**: the [Curb Area](#curb-area) object with the ID provided in the path. 207 | 208 | _Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._ 209 | 210 | ### Query Parameters 211 | 212 | This endpoint takes no query parameters. 213 | 214 | [Top][toc] 215 | 216 | ## Fetch a Curb Space 217 | 218 | **Endpoint**: `/curbs/spaces/` 219 | **Method**: `GET` 220 | `data` **Payload**: the [Curb Space](#curb-space) object with the ID provided in the path. 221 | 222 | _Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._ 223 | 224 | ### Query Parameters 225 | 226 | All query parameters are optional. 227 | 228 | | Name | Type | Description | 229 | | ------------ | --------------- | ---------------------------------------------- | 230 | | `time` | [Timestamp][ts] | Availability data (if supplied) will be returned as of this time. | 231 | 232 | [Top][toc] 233 | 234 | ## Fetch a Curb Policy 235 | 236 | **Endpoint**: `/curbs/policies/` 237 | **Method**: `GET` 238 | `data` **Payload**: the [Curb Policy](#policy) object with the ID provided in the path. 239 | 240 | ### Query Parameters 241 | 242 | This endpoint takes no query parameters. 243 | 244 | [Top][toc] 245 | 246 | ## Fetch a Curb Object 247 | 248 | **Endpoint**: `/curbs/objects/` 249 | **Method**: `GET` 250 | `data` **Payload**: the [Curb Object](#curb-object) object with the ID provided in the path. 251 | 252 | _Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._ 253 | 254 | ### Query Parameters 255 | 256 | All query parameters are optional. 257 | 258 | | Name | Type | Description | 259 | | ------------ | --------------- | ---------------------------------------------- | 260 | | `time` | [Timestamp][ts] | Availability data (if supplied) will be returned as of this time. | 261 | 262 | [Top][toc] 263 | 264 | # Data Objects 265 | 266 | ## Curb Zone 267 | 268 | A Curb Zone is a geographical entity representing a single region along the curb, along with 269 | metadata about that region and the policies that apply to its use by vehicles. What constitutes 270 | an individual Curb Zone is determined by the city, but all Curb Zones MUST meet the following 271 | criteria: 272 | 273 | 1. Always have a common regulation along their entire extent (i.e., if at certain times of day, 274 | half of a given stretch of curb is a loading zone and the other half is metered parking, that 275 | stretch of curb must be divided into at least two Curb Zones); 276 | 1. Never span multiple blocks -- an entire Curb Zone must be on the same street and be between 277 | the same two cross streets, alleys, or service roads. 278 | 1. Never overlap other Curb Zones in the same dataset with overlapping validity times. This 279 | applies to both the zone's polygon geometries and linear references (if used). 280 | 1. Be assigned a unique ID, in the form of a [UUID][uuid]. This ID SHOULD remain consistent as long as 281 | the Curb Zone's geography remains substantially the same. Policies may be updated without changing 282 | the ID. 283 | 1. It SHOULD NOT be possible to legally park a single vehicle in two different Curb Zones at the 284 | same time (i.e., a given non-demarcated parking area or loading zone should be represented as 285 | a single curb location), unless this conflicts with the requirements above. 286 | 287 | A Curb Zone is represented as a JSON object, whose fields are as follows: 288 | 289 | | Name | Type | Required/Optional | Description | 290 | | ------ | ------ | ------------------- | ------------- | 291 | | `curb_zone_id` | [UUID][uuid] | Required | The ID of this Curb Zone. | 292 | | `geometry` | GeoJSON [Polygon][polygon] OR [Linestring][linestring] | Required | The spatial extent of this curb zone. A new `curb_zone_id` is required if this geometry changes. Note that a two dimensional _polygon_ is the preferred `geometry`, but a _linestring_ is acceptable. Include the `width` field if known. | 293 | | `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. | 294 | | `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. | 295 | | `published_date` | [Timestamp][ts] | Required | The date/time that this curb zone was first published in this data feed. | 296 | | `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 fields may have changed. | 297 | | `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. | 298 | | `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. | 299 | | `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. | 300 | | `location_references` | Array of [Location Reference](#location-reference) objects | Optional | One or more linear references for this Curb Zone. | 301 | | `name` | String | Optional | A human-readable name for this Curb Zone that identifies it to end users. This could be an agency or vendor naming convention or schema (e.g. "350 S 1st St - PP", convention like "blockface-userzone-spaceid-ratetype", etc.) or unique or non-unique identifer. | 302 | | `description` | String | Optional | A more detailed description of the zone if needed. | 303 | | `jurisdiction_type` | String | Optional | Describes the type of entity that has jurisdiction of this curb zone. Values can be "public" for a street and curb zone maintained by a public sector agency (city, county, state), "private" for a street and curb zone maintained by a private entity (e.g. developer, home owner's association, university campus), or "other" for other options. | 304 | | `owner_name` | String | Optional | Identifies the name of the owner of the curb zone. E.g. "SFMTA", "CCSF", "Presidio Trust", etc. | 305 | | `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. | 306 | | `street_name` | String | Optional | The name of the street that this Curb Zone is on, including directionals. SHOULD NOT contain address numbers. Examples: `Main Street NE` or `West Market St`. | 307 | | `address_number` | String | Optional | The address number (street number, civic number, etc) or number range of the street that this Curb Zone is on. Examples: `123` or `221b` or `112-116`. | 308 | | `cross_street_start_name` | String | Optional | The name of the cross street at or before the start of this Curb Zone (which cross street is at the start and end of the location is defined in the same direction as the linear reference for this curb; if no linear reference is provided, start and end SHOULD be oriented such that start comes before end when moving in the direction of travel for the roadway immediately adjacent to the curb.) | 309 | | `cross_street_end_name` | String | Optional | The name of the cross street at the end of this Curb Zone. | 310 | | `length` | Integer | Optional | The length, in centimeters, of the Curb Zone when projected along the street centerline. Note that this is the definitive length of the curb area, and not the edge length of the geographic polygon. | 311 | | `available` | Boolean | Optional | If `true`, the curb zone is open for normal use. If `false`, the curb zone is closed and vehicles should look for alternative zones. Do not provide the field if the availability is unknown. | 312 | | `available_spaces` | Integer | Optional | The number of curb spaces that are open for use within the Zone. Spaces could be a count of available marked or delineated spaces, or a count of the available CDS [Curb Spaces](#curb-space). | 313 | | `available_space_lengths`| Array of Integers | Optional | If availability information is present, an array of numbers containing the lengths (in centimeters) of all known non-overlapping available spaces within this Curb Zone. Useful for non-delineated curb Zones where vehicles of different lengths may stop. In cases where availability is known less precisely, this data MAY be inferred from a model. | 314 | | `availability_time` | [Timestamp][ts] | Optional | If availability information is present, the timestamp corresponding to the most recent time that availability was computed for this zone. | 315 | | `width` | Integer | Optional | The width, in centimeters, that the Curb Zone occupies from the curb to the roadway lane. | 316 | | `parking_angle` | String | Optional | The angle in which passenger vehicles in this Curb Zone are meant to park. May take one of the following values:
  • `parallel`
  • `perpendicular`
  • `angled`
| 317 | | `num_spaces` | Integer | Optional | The number of demarcated spaces within this Curb Zone. Demarcated spaces may also be specified using [Curb Spaces](#curb-spaces). | 318 | | `street_side` | String | Optional | The cardinal or subcardinal direction representing the side of the roadway that this curb is on. May be `N`, `NE`, `E`, `SE`, `S`, `SW`, `W`, or `NW`. For cities with "grid directions", the side MAY be based on the grid direction rather than the closest true-north compass direction, but MUST NOT be more than 90 degrees away from the true compass direction. | 319 | | `median`| Boolean | Optional | If "true", this curb location is on the median of a street, rather than its edge. A median is a strip of land separating two roadways within the same street. Note that, for medians, `street_side` is interpreted relative to the roadway that the particular curb is on, so the curb along the median of the southern roadway of a divided street would have `street_side` of `N`. | 320 | | `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. | 321 | | `curb_area_ids`| Array of [UUID][uuid] | Optional | The ID(s) of the [Curb Areas](#curb-area) that this Curb Zone is a part of. If specified, the areas identified MUST be retrievable through the Curb API and its geographical area MUST contain that of the Curb Zone. | 322 | | `curb_space_ids`| Array of [UUID][uuid] | Optional | The ID(s) of the [Curb Spaces](#curb-space) that this Curb Zone contains. If specified, the spaces identified MUST be retrievable through the Curb API and its geographical area MUST be contained in this Curb Zone. | 323 | | `custom_attributes`| [Custom Attributes](/data-types.md#custom-attributes) JSON Object | Optional | Additional attributes (fields and data) to include in this [endpoint](/general-information.md#rest-endpoints). | 324 | | `curb_object_ids` | Array of [UUID][uuid] | Optional | The ID(s) of the [Curb Objects](#curb-object) that this Curb Zone is related to, in particular what Objects are in the Zone's areas of influence. For example, a pay station being used for multiple paid parking zones, a locker for a commercial loading zone, or a camera monitoring several zones. If specified, the objects identified MUST be retrievable through a Curbs API Objects endpoint. | 325 | | `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references to external data feeds impacting this Curb Zone. References external data that is relevant to this Zone now. If the external reference is temporary, it should be added, then removed when no longer relevant. This field can be changed without requiring a new `curb_zone_id`, as it does not impact the Zone's geographic, policy, rules, or other definitions. | 326 | 327 | [Top][toc] 328 | 329 | ### Curb Zone ID Stability 330 | 331 | The `curb_zone_id` field uniquely identifies a particular zone with one particular set of policies in a specific geographic area. 332 | 333 | - *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. 334 | - *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. 335 | 336 | [Top][toc] 337 | 338 | ## Curb Area 339 | 340 | Defines curb areas in a city and their properties. A Curb Area is a particular neighborhood or area 341 | of interest that includes one or more [Curb Zones](#curb-zone). Important notes about Curb Areas: 342 | 343 | - Curb Areas MAY overlap with other Curb Areas 344 | - Multiple Curb Areas MAY include the same Curb Zones 345 | - Curb Areas are not meant to be city-wide, and instead should be an area of interest around one 346 | or more Curb Zones that is no bigger than a neighborhood. 347 | - Unlike Zones, Areas may be updated as needed, with a new `curb_area_id` being optionally assigned by the city 348 | 349 | A Curb Area is represented as a JSON object, whose fields are as follows: 350 | 351 | | Name | Type | Required/Optional | Description | 352 | | ------ | ------ | ------------------- | ------------- | 353 | | `curb_area_id` | [UUID][uuid] | Required | The ID for the curb area. | 354 | | `geometry` | [Polygon][polygon] | Required | The spatial extent of this curb location. | 355 | | `name` | String | Optional | The name of this curb area for reference. | 356 | | `published_date` | [Timestamp][ts] | Required | The date/time that this curb area was first published in this data feed. | 357 | | `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. | 358 | | `curb_zone_ids` | Array of [UUIDs][uuid] | Required | The IDs of all the Curb Zones included within this Curb Area at the requested time. | 359 | | `custom_attributes`| [Custom Attributes](/data-types.md#custom-attributes) JSON Object | Optional | Additional attributes (fields and data) to include in this [endpoint](/general-information.md#rest-endpoints). | 360 | | `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references to external data feeds impacting this Curb Area. References external data that is relevant to this Area now. If the external reference is temporary, it should be added, then removed when no longer relevant. | 361 | 362 | [Top][toc] 363 | 364 | ## Curb Space 365 | 366 | Defines individual demarcated spaces within a Curb Zone. Important notes about Curb Spaces: 367 | 368 | - Curb Spaces may NOT overlap with other Curb Spaces 369 | - Curb Spaces must be wholly contained within or associated with a single Curb Zone 370 | - Unlike Zones, Spaces may be updated as needed, with a new `curb_space_id` being optionally assigned by the city 371 | 372 | A Curb Space is represented as a JSON object whose fields are as follows: 373 | 374 | | Name | Type | Required/Optional | Description | 375 | | ------ | ------ | ------------------- | ------------- | 376 | | `curb_space_id` | [UUID][uuid] | Required | The ID of the curb space. | 377 | | `geometry` | [Polygon][polygon] | Required | The spatial extent of this curb location. | 378 | | `name` | String | Optional | The name of this curb space for reference. | 379 | | `published_date` | [Timestamp][ts] | Required | The date/time that this curb area was first published in this data feed. | 380 | | `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. | 381 | | `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. | 382 | | `curb_object_ids` | Array of [UUID][uuid] | Conditionally Required | The ID(s) of the [Curb Objects](#curb-object) that this Curb Space is related to, in particular what Objects are in the Space's areas of influence. For example, a meter being used for two paid parking spcaes, a locker for a commercial loading space, or a camera monitoring several spaces. If specified, the objects identified MUST be retrievable through a Curbs API Objects endpoint. | 383 | | `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. | 384 | | `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. | 385 | | `width` | Integer | Optional | Width 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. | 386 | | `available` | Boolean | Optional | Whether this space is available for vehicles to park in at the specified time (‘True’ means the Space is available). | 387 | | `availability_time` | [Timestamp][ts] | Optional | If availability information is present, the most recent time that availability was computed for this space. | 388 | | `custom_attributes`| [Custom Attributes](/data-types.md#custom-attributes) JSON Object | Optional | Additional attributes (fields and data) to include in this [endpoint](/general-information.md#rest-endpoints). | 389 | | `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references to external data feeds impacting this Curb Space. References external data that is relevant to this Space now. If the external reference is temporary, it should be added, then removed when no longer relevant. | 390 | 391 | [Top][toc] 392 | 393 | ## Curb Object 394 | 395 | Defines individual assets located adjacent to, overlapping, within, or associated with a Curb Space or Curb Zone. Important notes about Curb Objects: 396 | 397 | - Curb Objects can be located anywhere within, beside, or overlapping with Curb Zones, Spaces, or other Curb Objects 398 | - Curb Objects must be associated with either a Curb Space or Curb Zone 399 | - Curb Objects do not typically have Curb Policies linked directly to them (unless the object is directly aligned with a single Policy, using the optional `curb_policy_id` field). Associated Curb Policies can be found by looking at the related Curb Zone (either directly or through the Curb Space). 400 | - Unlike Zones and similar to Spaces, Objects may be updated as needed, with a new `curb_object_id` being optionally assigned by the city 401 | 402 | A Curb Object is represented as a JSON object whose fields are as follows: 403 | 404 | | Name | Type | Required/Optional | Description | 405 | | ------ | ------ | ------------------- | ------------- | 406 | | `curb_object_id` | [UUID][uuid] | Required | The ID of the curb object. | 407 | | `geometry` | [Point][point] | Required |The spatial location of this curb object location. This can represent the approximate center of the object, or the centroid location of the object, depending on its size and shape. | 408 | | `curb_zone_id` | [UUID][uuid] | Conditionally Required | The ID of the Curb Zone this object is physically in or closest to. The geometry of the specified Curb Zone does not need to directly relate to the geometry of this object. Either a Zone or Space ID is required for an Object. | 409 | | `curb_space_id` | [UUID][uuid] | Conditionally Required | The ID of the Curb Space this object is physically in or closest to. The geometry of the specified Curb Space does not need to directly relate to the geometry of this object. Either a Zone or Space ID is required for an Object. | 410 | | `curb_policy_id` | [UUID][uuid] | Optional | ID of [Policy object](#policy) that is directly associcated with this curb object. For example, `signage` or `paint` that relates to a single policy. | 411 | | `lane_type` | [Lane Type][lane-type] | Optional | The type of lane the curb object is primarily located in. Value is one of [Lane Type][lane-type]. | 412 | | `object_type` | [Object Types](#object-types) | Required | The categrory of the curb object. Value is one of the [Object Types](#object-types). | 413 | | `name` | String | Required | A short name of this curb object for reference. | 414 | | `description` | String | Optional | A more detailed description of the object if needed. | 415 | | `owner` | String | Optional | The name of the agency, department, etc responsibile for maintaining this object. | 416 | | `operator` | String | Optional | The name of the agency, department, etc responsibile for operating this object. | 417 | | `object_shape` | [Polygon][polygon] | Optional | A simplified geometric outline of this object. Recommended for objects that are an unusual shape and may affect curb activities. | 418 | | `object_line` | [LineString][linestring] | Optional | A simplified geometric line defining this object. Recommended for objects that may affect or help define curb activities, like `paint`. | 419 | | `linear_distance` | Integer | Optional | Parallel distance from the side of the object to the linear referencing start point of the curb, in centimeters. | 420 | | `perpendicular_distance` | Integer | Optional | Perpendicular distance from the front of the object to the curb edge start/end, in centimeters. This distance can be negative or positive, with the positive direction being from the curb towards the sidewalk. | 421 | | `max_length` | Integer | Optional | Maximum, bounding box length of the object parallel to the curb, in centimeters. | 422 | | `max_depth` | Integer | Optional | Maximum, bounding box depth of the object perpendicular to the curb, in centimeters. | 423 | | `max_height` | Integer | Optional | Maximum, bounding box height of the object from the sidewalk/street surface, in centimeters. | 424 | | `published_date` | [Timestamp][ts] | Required | The date/time that this curb object was first published in this data feed. | 425 | | `last_updated_date` | [Timestamp][ts] | Required | The date/time that the properties of ths curb object were last updated. This helps consumers know that some fields may have changed. | 426 | | `custom_attributes`| [Custom Attributes](/data-types.md#custom-attributes) JSON Object | Optional | Additional attributes (fields and data) to include in this [endpoint](/general-information.md#rest-endpoints). | 427 | | `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references to external data feeds impacting this Curb Object. References external data that is relevant to this Object now. If the external reference is temporary, it should be added, then removed when no longer relevant. | 428 | 429 | [Top][toc] 430 | 431 | ### Object Types 432 | 433 | The following object types may be specified for Curb Objects. This list is NOT meant to be exhaustive as users have the ability to add objects to this list that may be unique to their city. Descriptions have been provided with each object type where warranted. New object types may be generated to reflect local curb uses, but when possible the following well-known recommended values should be used. If multiple similar values apply, then use the more descriptive/specific value when possible. Unique object type attributes for each object type are not included in this version of the specification. As use of Curb Objects grows or specific use cases become more involved, common object type attributes can be added. 434 | 435 | **Well-known values:** 436 | 437 | Mobility Related 438 | - `signage` - street sign or any regulation signs related to the curb 439 | - `bus_stop` - either a sign, shelter, or zone 440 | - `bike_rack` - somewhere to lock or store a bike 441 | - `scooter_parking` - dedicated location to lock or store scooters 442 | - `ev_charging` - charging station for electric devices 443 | - `ramp` - a curb drop down for accessibility needs 444 | - `meter` - a device to pay for parking, either single or multi space 445 | - `pay_station` - a device to pay for parking, applicable for an entire zone 446 | - `paint` - curb paint, defining a policy or rule 447 | 448 | Curbside Infrastructure 449 | - `lighting` 450 | - `signal_cabinet` 451 | - `utility_box` 452 | - `fire_hydrant` 453 | - `surveillance_camera` 454 | 455 | Curbside Obstacles 456 | - `barrier` 457 | - `bollard` 458 | - `street_trees` 459 | - `planter` 460 | - `drinking_fountain` 461 | - `toilet` 462 | - `bench` 463 | - `sculpture` 464 | - `art` 465 | - `fountain` 466 | - `solid_waste_bins` 467 | - `post_box` 468 | - `locker` 469 | 470 | Other 471 | - `food_vendor` 472 | 473 | [Top][toc] 474 | 475 | ## Policy 476 | 477 | 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. 478 | 479 | 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. 480 | 481 | Policies must be unique. A Policy may not have the exact same Policy object field values with a different `curb_policy_id`. For example, if the required or optional fields in two policies have the same values (either exactly identical or functionally identical), it is considered the same Policy, and must not be presented as two different policies in the data payload. 482 | 483 | A Policy is represented as a JSON object whose fields are as follows: 484 | 485 | | Name | Type | Required/Optional | Description | 486 | | ------ | ------ | ------------------- | ------------- | 487 | | `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. | 488 | | `name` | String | Optional | User friendly name of policy. | 489 | | `description` | String | Optional | Detailed description of policy. | 490 | | `published_date` | [Timestamp][ts] | Required | The date/time that this policy was first published in this data feed. | 491 | | `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 MAY ONLY have the same priority if the policies apply to disjoint User Classes or disjoint Activities. | 492 | | `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. | 493 | | `time_spans` | Array of [Time Spans](#time-span) | Optional | If specified, this regulation only applies at the times defined within. | 494 | | `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. | 495 | | `policy_color` | [Policy Color](#policy-color) | Optional | A JSON object that defines the official colors used to represent this specific policy, used in physical curb paint, digital and print maps, etc. | 496 | | `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references to external data sources impacting this Curb Policy. References external sources that are relevant to this Policy at the time of its creation. More specific and timely external references can be made in related Zones, Spaces, and Areas. This field can be changed without requiring a new `curb_policy_id`, as it does not impact the policy definitions. | 497 | 498 | [Top][toc] 499 | 500 | ### Rule 501 | 502 | A rule defines who is allowed to do what, and for how long, on a curb, per the policy. 503 | 504 | It is a JSON object with the following fields: 505 | 506 | | Name | Type | Required/Optional | Description | 507 | | ------ | ------ | ------------------- | ------------- | 508 | | `name` | String | Optional | User friendly name of rule. | 509 | | `description` | String | Optional | Detailed description of rule. | 510 | | `activity` | [Activity](#activities) String | Required | The activity that is forbidden or permitted by this regulation. Value MUST be one of the [activities](#activities). | 511 | | `max_stay` | Integer | Optional | The length of time (in units of `max_stay_unit`) for which the curb may be used under this regulation. If not specified, the curb may be used under this regulation indefinitely. May not be applicable for all [activities](#activities). | 512 | | `max_stay_unit` | Enum | Optional | The [Unit of Time](/general-information.md#unit-of-time-enum) associated with the `max_stay` value. Defaults to "minute". | 513 | | `no_return` | Integer | Optional | The length of time (in units of `no_return_unit`) that a user must vacate a Curb Zone before being allowed to return for another stay. Defaults to 0. May not be applicable for all [activities](#activities). | 514 | | `no_return_unit` | Enum | Optional | The [Unit of Time](/general-information.md#unit-of-time-enum) associated with the `no_return` value. Defaults to "minute". | 515 | | `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. The order of `user_classes` is not relevant, but a vehicle using a curb with this rule must match all `user_classes` contained in the array. | 516 | | `user_classes_except` | Array of [user class](#user-classes) Strings | Optional | If specified, this regulation applies only to users who **do not** match any of the [user classes](#user-classes) contained within. The order of `user_classes` is not relevant, but a vehicle using a curb with this rule must match all `user_classes` contained in the array. This field takes precidence over `user_classes` when present. | 517 | | `purposes` | Array of [purposes](#purposes) Strings | Optional | If specified, this describes allowed uses associated with curb zones, spaces, objects, activies, user classes, etc. If not specified, all purposes are allowed. The order of `purposes` is not relevant, but vehicle or operator activities must match any `purposes` contained in the array. | 518 | | `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. May not be applicable for all [activity](#activities). | 519 | 520 | [Top][toc] 521 | 522 | #### Activities 523 | 524 | The following activities may be specified for rules within a policy. The reason we have 525 | "positive" and "negative" versions of the same activities (like `loading` and `no parking`) 526 | is due to priorities: a `loading` rule that is higher priority than a `no loading` rule, 527 | for instance, implies that the Curb Zone does allow loading at the time in question, while a 528 | `no parking` rule would not. If "negative", `rate` array should be empty. 529 | 530 | - `parking` - implies that loading and stopping are also permitted 531 | - `no parking` - may not stop and leave vehicle unattended 532 | - `loading` - loading of goods; implies that stopping is also permitted 533 | - `no loading` - no loading allowed; implies that parking is also prohibited 534 | - `unloading` - unloading of goods; implies that stopping is also permitted 535 | - `no unloading` - no unloading allowed; implies that parking is also prohibited 536 | - `stopping` - stopping briefly to pick up or drop off passengers 537 | - `no stopping` - stopping, loading, unloading, and parking are all prohibited; not a typical travel lane 538 | - `travel` - represents curbside lanes typically intended for moving vehicles, like bus lanes, bike lanes, 539 | and rush-hour-only travel lanes; implies that parking, loading, unloading, and stopping are prohibited. 540 | - `no travel` - no travel allowed; implies it could be used for other activities 541 | 542 | [Top][toc] 543 | 544 | #### User Classes 545 | 546 | A user class represents any class of vehicles that is regulated by a city with respect to curb 547 | space. They can be defined by the vehicle's physical characteristics (e.g., trucks, vans, EVs), 548 | the presence/absence of a particular permit (e.g., residential parking permits), or even by the 549 | intent or destination of the driver, for things like hotel or school unloading zones. 550 | 551 | These are not meant to be a mirror to similarly named items in the Events API, but instead serve a 552 | unique purpose of describing locally defined regulations at a curb. 553 | 554 | This array of `user_classes` serves as an 'AND' function. A vehicle must have all the properties listed 555 | in the array to use the curb. For example, an accessible EV bus will use `accessible` AND `electric` 556 | AND `bus`. To create 'OR' values at the same curb, you must create a new rule 557 | with the new array of values. 558 | 559 | New user classes MAY be generated to reflect local regulations, but when possible, 560 | the following well-known recommended values should be used. If multiple similar values apply, then use the more 561 | descriptive/specific value when possible. 562 | 563 | **Well-known values:** 564 | 565 | Vehicle types 566 | - `bicycle` 567 | - `bus` 568 | - `cargo_bicycle` 569 | - `car` 570 | - `moped` 571 | - `motorcycle` 572 | - `scooter` 573 | - `shuttle` 574 | - `truck` 575 | - `van` 576 | 577 | Vehicle properties 578 | - `accessible` 579 | - `autonomous` 580 | - `combustion` 581 | - `electric` 582 | - `electric_assist` 583 | - `human` 584 | 585 | #### Purposes 586 | 587 | A purpose represents the kinds of activities taking place with respect to curb 588 | space or parking areas. 589 | 590 | This array of `purposes` serves as an 'OR' function. A vehicle perform an event with any of the purposes listed 591 | in the array to use the curb. For example, a pickup and drop off zone for people and goods can use `delivery` OR `taxi` 592 | OR `rideshare`. To create 'AND' values at the same curb, you must create a new rule 593 | with the new array of values. 594 | 595 | New purposes MAY be generated to reflect local regulations, but when possible, 596 | the following well-known recommended values should be used. If multiple similar values apply, then use the more 597 | descriptive/specific value when possible. 598 | 599 | **Well-known values:** 600 | 601 | Purpose 602 | - `construction` 603 | - `delivery` 604 | - `disabled_parking_permit` 605 | - `emergency_use` 606 | - `freight` 607 | - `parking` 608 | - `permit` 609 | - `rideshare` 610 | - `carshare` 611 | - `school` 612 | - `service_vehicles` 613 | - `special_events` 614 | - `taxi` 615 | - `utilities` 616 | - `valet` 617 | - `vending` 618 | - `waste_management` 619 | 620 | [Top][toc] 621 | 622 | ### Time Span 623 | 624 | 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: 625 | 626 | ``` 627 | { 628 | "days_of_week": ["mon", "tue"], 629 | "time_of_day_start": "10:00", 630 | "time_of_day_end": "13:00" 631 | } 632 | ``` 633 | 634 | A Time Span is represented as a JSON object whose fields are as follows: 635 | 636 | | Name | Type | Required/Optional | Description | 637 | | ------ | ------ | ------------------- | ------------- | 638 | | `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. | 639 | | `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. | 640 | | `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"`). | 641 | | `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]`). | 642 | | `weeks_of_month` | Array of integers | Optional | An array of weeks of the month when this Time Span applies, specified as integers (1-5), to represent ordinal weeks. E.g. "2" would be the 2nd week of the month. | 643 | | `months` | Array of integers | Optional | If specified, this Time Span applies only during these months (1=January, 12=December). | 644 | | `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)), in the local timezone. If unspecified, this Time Span starts at midnight. | 645 | | `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)), in the local timezone. 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. | 646 | | `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`
| 647 | | `designated_period_except` | Boolean | Optional | If specified and `true`, all fields in this Time Span are describing a period in which the assocated rule does not apply. (e.g., if `designated_period` is `snow emergency` and `designated_period_except` is `true`, the rule does not apply on snow days. If `days_of_week` is `['sun']`, the rule does not apply on Sundays.) This field takes precidence over `designated_period` when present. | 648 | 649 | **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. 650 | 651 | [Top][toc] 652 | 653 | ### Rate 654 | 655 | 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: 656 | 657 | | Name | Type | Required/Optional | Description | 658 | | ------ | ------ | ------------------- | ------------- | 659 | | `rate` | Integer | Required | The rate for this space in cents (or the smallest denomination of local currency) per `rate_unit`. | 660 | | `rate_unit` | Enum | Required | The unit of time associated with the rate. One of "second", "minute", "hour", "day", "week", "month", "quarter", "year". | 661 | | `rate_unit_period` | Enum | Optional | The period of time that the `rate_unit` covers. One of "rolling" or "calendar". If not specified, **defaults** to "rolling". When **rolling**, the `rate_unit` begins (inclusive) at the timestamp of the event and ends (exclusive) when one full `rate_unit` has elapsed. For example, with `{"rate_unit": "month", "rate_unit_period": "rolling"}` the `rate_unit` for an event starting at `2022-02-25 19:25:52` would be interpreted as ranging from the start of the event - `2022-02-25 19:25:52` (inclusive) - to the timestamp when one "month" has elapsed: `2022-03-25 19:25:52` (exclusive). E.g. from the 25th of one month to the 25th of the next month. When **calendar**, the `rate_unit` begins (inclusive) at the start of the `rate_unit` in question and ends (exclusive) when one full `rate_unit` has elapsed. For example, with `{"rate_unit": "month", "rate_unit_period": "calendar"}` the `rate_unit` for an event starting at `2022-02-25 19:25:52` would be interpreted as ranging from the start of the "month" - `2022-02-01 00:00:00` (inclusive) - to the end of the "month": `2022-03-01 00:00:00` (exclusive). E.g. from the 25th of the month to the end of the current calendar month only. The "week" `rate_unit` is defined as starting on Monday, per the ISO 8601 standard. See [example](/curbs/examples.md#curb-policy-rate-units) for other scenarios in action. | 662 | | `increment_duration` | Integer | Optional | If specified, this is the smallest number of `rate_unit`s a user can pay for (e.g., if `increment_duration` is `15` and `rate_unit` is `minute`, a user can pay for 15, 30, 45, etc. minutes). | 663 | | `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 currency units as `rate`. | 664 | | `start_duration` | Integer | Optional | The number of `rate_unit`s 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. | 665 | | `end_duration` | Integer | Optional | The number of `rate_unit`s after which the rate stops applying (_exclusive_, see [Range Boundaries](/general-information.md#range-boundaries)). If not specified, this rate ends when the vehicle departs. | 666 | | `maximum_fee` | Integer | Optional | The maximum amount in cents a user of a curb can pay for a particular parking event. | 667 | 668 | [Top][toc] 669 | 670 | ## Location Reference 671 | 672 | A Location Reference defines a linear reference for a given Curb Zone. A linear reference defines a Curb Zone's position by reference to a linear feature, like a street centerline or edge-of-pavement line. Linear referencing systems can be global, like [SharedStreets linear references](https://sharedstreets.io/) or [OpenLR](http://www.openlr.org/index.html), or local to a particular city. 673 | 674 | A Location Reference is a JSON object with the following fields: 675 | 676 | | Name | Type | Required/Optional | Description | 677 | | ------ | ------ | ------------------- | ------------- | 678 | | `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://yourcityname.gov/LR`: custom city LR, direct link if possible
| 679 | | `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. | 680 | | `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)). | 681 | | `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. | 682 | | `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. | 683 | 684 | [Top][toc] 685 | 686 | ## Previous Policy 687 | 688 | 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. 689 | 690 | A Previous Policy is a JSON object with the following fields: 691 | 692 | | Name | Type | Required/Optional | Description | 693 | | ------ | ------ | ------------------- | ------------- | 694 | | `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. | 695 | | `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)). | 696 | | `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)). | 697 | 698 | [Top][toc] 699 | 700 | ## Policy Color 701 | 702 | Information about colors that apply to a specific [Policy](#policy), which in turn connects to a physical or digital [curb zone](#curb-zone). Colors reflect the physical paint color at the curb zone. Displaying visually on a map or other location may or may not align with the physical colors, per the needs of the agency. Colors are defined with RGB hex values, and should approximate real-world paint or print as closely as possible, but may not capture the entire color gamut. 703 | 704 | A Policy Color is a JSON object with the following fields: 705 | 706 | | Name | Type | Required/Optional | Description | 707 | | ------------------------ | ---- | ------------------- | ------------- | 708 | | `primary_color` | Hex | Required | The **6 digit hexidecimal triplet value** of the primary curb color, in standard capitalized RRGGBB format, without a leading hash symbol ("#"). E.g. "839D8F", "FF00FF". | 709 | | `primary_pattern_type` | Enum | Optional | One of `solid`, `long_dash`, `short_dash`, `dot`, `dot_dash`, `diagonal` to define the type of pattern on the `primary_color`. | 710 | | `primary_border_color` | Hex | Optional | The 6 digit hex value of the `primary_color` border color. | 711 | | `primary_border_pattern_type` | Enum | Optional | One of `solid`, `long_dash`, `short_dash`, `dot`, `dot_dash`, `diagonal` to define the type of pattern on the `primary_border_color`. | 712 | | `secondary_color` | Hex | Optional | The 6 digit hex value of the secondary curb color. | 713 | | `secondary_border_color` | Hex | Optional | The 6 digit hex value of the `secondary_color` border color. | 714 | | `secondary_border_pattern_type` | Enum | Optional | One of `solid`, `long_dash`, `short_dash`, `dot`, `dot_dash`, `diagonal` to define the type of pattern on the `secondary_border_color`. | 715 | 716 | [Top][toc] 717 | 718 | # Examples 719 | 720 | See the [CDS Curbs Examples](https://github.com/openmobilityfoundation/curb-data-specification/wiki/CDS-Curbs-Examples) wiki page for code examples of specific Curbs use cases, and ideas on how Curbs can be implemented. 721 | 722 | [Top][toc] 723 | 724 | # Schema 725 | 726 | For details on the CDS schema in OpenAPI format and on Stoplight, please reference the [CDS OpenAPI](https://github.com/openmobilityfoundation/cds-openapi) repository. 727 | 728 | [Top][toc] 729 | 730 | [external-reference]: ../data-types.md#external-reference 731 | [lane-type]: ../data-types.md#lane-type 732 | [toc]: #table-of-contents 733 | [uuid]: /general-information.md#uuid 734 | [ts]: /general-information.md#timestamp 735 | [polygon]: /general-information.md#polygon 736 | [linestring]: /general-information.md#linestring 737 | [point]: /general-information.md#point 738 | --------------------------------------------------------------------------------