├── .github ├── ISSUE_TEMPLATE │ ├── add-agency-id.md │ ├── add-provider-id.md │ ├── bug_report.md │ └── feature-request---proposal.md ├── PULL_REQUEST_TEMPLATE │ ├── pull_request_template.md │ └── release-candidate.md └── pull_request_template.md ├── .gitignore ├── CODEOWNERS ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── ReleaseGuidelines.md ├── ReleaseNotes.md ├── agencies.csv ├── agency └── README.md ├── data-types.md ├── general-information.md ├── geography ├── README.md └── examples │ ├── README.md │ ├── distribution-zone-8.geojson │ ├── distribution-zone-8.json │ ├── geographies.geojson │ ├── geographies.json │ ├── municipal-boundary.geojson │ ├── municipal-boundary.json │ ├── no-ride-zone.geojson │ ├── no-ride-zone.json │ ├── operating-area.geojson │ ├── operating-area.json │ ├── slow-ride-zone.geojson │ ├── slow-ride-zone.json │ ├── stop.geojson │ └── stop.json ├── jurisdiction ├── README.md └── examples │ ├── README.md │ └── jurisdictions.json ├── metrics ├── README.md ├── core_metrics.md ├── dockless_metrics.md ├── examples │ ├── README.md │ ├── activities.json │ └── activities_response.json └── metrics_methodology.md ├── modes ├── README.md ├── car-share-state-machine-diagram.svg ├── car-share.md ├── delivery-robots-state-machine-diagram.svg ├── delivery-robots.md ├── event_types.md ├── micromobility-state-machine-diagram.svg ├── micromobility.md ├── passenger-services-state-machine-diagram.svg ├── passenger-services.md └── vehicle_states.md ├── policy ├── README.md └── examples │ ├── README.md │ └── requirements.md ├── provider ├── README.md └── examples.md ├── providers.csv └── schema └── README.md /.github/ISSUE_TEMPLATE/add-agency-id.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Add Agency ID 3 | about: Create Agency ID for use in MDS 4 | title: 'Add Agency ID: [Agency Name]' 5 | labels: admin 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Note:** See the [Adding an MDS Agency ID](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Adding-an-MDS-Agency-ID) page for more help. 11 | 12 | Opening this issue will allow you as a city or governmental agency get an official agency ID for use across MDS globally, and include in your Requirements URL. 13 | 14 | **Fields needed from you for the [agencies.csv file](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/agencies.csv).** 15 | 16 | _All fields are required._ 17 | 18 | 1. **agency_country_iso_code** - Two letter ISO country code where your agency is located. 19 | - ... 20 | 1. **agency_state** - Geographic abbreviation or name of the state where your agency is located. 21 | - ... 22 | 1. **agency_city** - Geographic name of the city where your agency is located. 23 | - ... 24 | 1. **agency_name** - Full name of your governmental city/agency. 25 | - ... 26 | 1. **agency_id** - A random UUID version 4. There are lots of way to generate a unique UUID, like using this website. 27 | - ... 28 | 1. **department_url** - URL to the home page of your agency's department. 29 | - ... 30 | 1. **requirement_url** - Full https:// URL where your current Policy Requirements endpoint is located. 31 | - ... 32 | 33 | Additionally, please provide your name and role within your agency to help with verification. 34 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/add-provider-id.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Add Provider ID 3 | about: Create Provider ID for use in MDS 4 | title: 'Add Provider ID: [Provider Name]' 5 | labels: admin 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Note:** See the [Adding an MDS Provider ID](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Adding-an-MDS-Provider-ID) page for more help. 11 | 12 | Opening this issue will allow you as a mobility service provider or data source provider to get an official provider ID for use across MDS globally. 13 | 14 | **Fields needed from you for the [providers.csv file](https://github.com/openmobilityfoundation/mobility-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. **mode_id** - The mode that you support. Use the mode short identifier from `micromobility`, `passenger-services`, `delivery-robots`, `car-share`. Register a unique ID for each mode you support. 21 | - ... 22 | 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). 23 | - ... 24 | 1. **url** - URL to the home page of your company. 25 | - ... 26 | 1. **mds_api_url** - Full https:// base URL where your root MDS feeds are located. 27 | - ... 28 | 1. **gbfs_api_url** - Full https:// base URL where your public GBFS feeds are located. 29 | - ... 30 | 31 | Additionally, please provide your name and role within your agency to help with verification. 32 | - ... 33 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Describe the bug** 11 | A clear and concise description of what the bug is. 12 | 13 | **To Reproduce** 14 | Steps to reproduce the behavior: 15 | 16 | **Expected behavior** 17 | A clear and concise description of what you expected to happen. 18 | 19 | **Additional context** 20 | Add any other context about the problem here. 21 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature-request---proposal.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 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). 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 | * `agency` 31 | * `policy` 32 | * `provider` 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 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE/pull_request_template.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Default 3 | about: Suggest changes to MDS 4 | title: 5 | 6 | --- 7 | 8 | # MDS 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/mobility-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 spec(s) will this pull request impact? 34 | 35 | * `agency` 36 | * `policy` 37 | * `provider` 38 | 39 | ## Additional context 40 | 41 | Add any other context or screenshots about the feature request here. 42 | -------------------------------------------------------------------------------- /.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 | assignees: jfh01 7 | 8 | --- 9 | 10 | ### Summary 11 | 12 | The Release Candidate for MDS `X.Y.Z` has been submitted: 13 | 14 | Please use this pull request to track Technology Council and OMF Board feedback and/or requested changes. 15 | 16 | ### Action Item 17 | 18 | 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). 19 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Default 3 | about: Suggest changes to MDS 4 | title: 5 | 6 | --- 7 | 8 | # MDS 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/mobility-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 spec(s) will this pull request impact? 34 | 35 | * `agency` 36 | * `policy` 37 | * `provider` 38 | 39 | ## Additional context 40 | 41 | Add any other context or screenshots about the feature request here. 42 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .venv/ 2 | .vscode 3 | .DS_Store 4 | __pycache__ -------------------------------------------------------------------------------- /CODEOWNERS: -------------------------------------------------------------------------------- 1 | ## Below is the MDS CODEOWNERS file, which dictates who is required for review on any given file. 2 | 3 | ## All MDS approvals 4 | * @openmobilityfoundation/omf-admin 5 | 6 | ## MDS Working Group 7 | * @openmobilityfoundation/mds-maintainers @openmobilityfoundation/omf-admin 8 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | Particpation with the OMF is governed by the OMF's [Code of Conduct](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md) and [Participation Policies](https://github.com/openmobilityfoundation/governance/raw/main/documents/OMFParticipationPolicies.pdf). 4 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # MDS Contributor Guidelines 2 | 3 | **See the new [MDS Contributor Guidelines](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) document for details.** 4 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 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 | -------------------------------------------------------------------------------- /ReleaseGuidelines.md: -------------------------------------------------------------------------------- 1 | # MDS Release Guidelines 2 | 3 | MDS will see regular updates and new [releases](https://github.com/openmobilityfoundation/mobility-data-specification/releases). 4 | 5 | **See the new [MDS Release Guidelines](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md) document for details.** 6 | 7 | -------------------------------------------------------------------------------- /agencies.csv: -------------------------------------------------------------------------------- 1 | agency_country_iso_code,agency_state,agency_city,agency_name,agency_id,department_url,requirement_url 2 | CA,British Columbia,Kelowna,City of Kelowna,31e836fc-72da-4b2e-b553-8227d77a9b7a,https://www.kelowna.ca/roads-transportation/active-transportation/cycling/bikeshare-permit-program, 3 | CO,Cundinamarca,Bogotá,Bogotá,85eac875-ab70-469f-8a85-cc5ef22e78d0,https://www.movilidadbogota.gov.co/web/, 4 | DE,Baden-Württemberg,Ulm,Stadt Ulm,68f28fb8-d177-43f4-b7e8-a286fe0ddca0,https://www.ulm.de/de-de, 5 | US,CA,Long Beach,City of Long Beach,188ed65d-a81e-40b9-b0b2-aeb85436610a,https://www.longbeach.gov/goactivelb/, 6 | US,CA,Los Angeles,Los Angeles,d82d8584-dfa6-4396-93f0-5a36288b9eb1,https://ladot.lacity.org/projects/transportation-services/shared-mobility/micromobility, 7 | US,CA,San Francisco,San Francisco Municipal Transportation Agency,8e03693b-0153-446c-8bc0-c31f8a5a7ed8,https://www.sfmta.com/projects/powered-scooter-share-permit-and-pilot-program,https://github.com/openmobilityfoundation/agency-program-requirements/raw/main/requirement/SFMTA-1.2.0.json 8 | US,CA,San Jose,San Jose,801cb4b8-8725-449c-bdb9-7e9ac0e10b5b,https://www.sanjoseca.gov/your-government/departments-offices/transportation/micro-mobility, 9 | US,CA,Santa Monica,Santa Monica,e4e7c0f6-c6aa-4919-a4de-565e4fe9fa57,https://www.smgov.net/Departments/PCD/Transportation/Shared-Mobility-Services/, 10 | US,CO,Denver,Denver,c3d07b63-f602-4837-9525-7285f5ef286b,https://www.denvergov.org/content/denvergov/en/transportation-infrastructure/programs-services/dockless-mobility.html, 11 | US,DC,Washington,District of Columbia,8aca1cf2-ffa5-46d8-b747-20cf00a7c7f1,https://ddot.dc.gov/page/dockless-vehicle-permits-district, 12 | US,FL,Miami,City of Miami,5b36be11-7d5d-45ab-9c89-105cf6aa8645,https://www.miamigov.com/Services/Transportation/Miami-Scooter-Pilot-Program, 13 | US,IL,Chicago,Chicago,d2ed9de6-2d2d-477c-a843-7d150d2310ed,https://www.chicago.gov/city/en/depts/cdot/supp_info/escooter-share-pilot-project.html, 14 | US,KY,Louisville,Louisville Metro,44bc31a7-464b-4ed9-b52e-8e74630826bd,https://louisvilleky.gov/government/public-works/dockless-find-and-ride-vehicles, 15 | US,MI,Detroit,Detroit,5814742e-78ba-4ac1-a628-c414ecc45448,https://detroitmi.gov/departments/department-public-works/complete-streets/scooters, 16 | US,MN,Minneapolis,Minneapolis,88303227-48d6-4088-a690-65b4dcf381f7,http://www.minneapolismn.gov/publicworks/trans/WCMSP-212816, 17 | US,OR,Portland,Portland,7d600eb6-f967-40ea-a212-33917f9b48ae,https://www.portlandoregon.gov/transportation/, https://api.ridereport.com/policy/pdx/requirements 18 | US,PA,Philadelphia,Philadelphia,fa2d0c5a-a716-473c-808b-be3b23e022ee,http://www.phillyotis.com/portfolio-item/dockless-bike-share-pilot/, 19 | US,PA,Pittsburgh,Pittsburgh,f3c50422-7e3e-4efe-88c7-99da3b36c24d,https://pittsburghpa.gov/domi/bikeplan, 20 | US,TX,Austin,City of Austin,296220ae-c90a-4383-9a97-0bc6cf1adf18,https://austintexas.gov/department/shared-mobility-services, 21 | US,WA,Seattle,City of Seattle,9acf6e41-f145-49ad-be7f-d910e978fc36,https://www.seattle.gov/transportation/projects-and-programs/programs/bike-program/bike-share, 22 | -------------------------------------------------------------------------------- /agency/README.md: -------------------------------------------------------------------------------- 1 | # Mobility Data Specification: **Agency** 2 | 3 | MDS Agency Icon 4 | 5 | The Agency API endpoints are intended to be implemented by regulatory agencies and consumed by mobility providers. Data is **pushed** to agencies by providers. Providers query the Agency API when events (such as a trip start or vehicle status change) occur in their systems. 6 | 7 | This specification contains a collection of RESTful APIs used to specify the digital relationship between *mobility as a service* providers and the agencies that regulate them. 8 | 9 | ## Table of Contents 10 | 11 | * [General Information](#general-information) 12 | * [Authorization](#authorization) 13 | * [Versioning](#versioning) 14 | * [Modes](#modes) 15 | * [Responses and Error Messages](#responses-and-error-messages) 16 | * [GBFS](#gbfs) 17 | * [Vehicles](#vehicles) 18 | * [Vehicle - Register](#vehicle---register) 19 | * [Vehicle - Update](#vehicle---update) 20 | * [Vehicle - List](#vehicle---list) 21 | * [Vehicle - Status](#vehicle---status) 22 | * [Trips](#trips) 23 | * [Telemetry](#telemetry) 24 | * [Events](#events) 25 | * [Stops](#stops) 26 | * [Stops - Register](#stops---register) 27 | * [Stops - Update](#stops---update) 28 | * [Stops - Readback](#stops---readback) 29 | * [Reports](#reports) 30 | * [Reports - Register](#reports---register) 31 | 32 | ## General information 33 | 34 | This specification uses data types including timestamps, UUIDs, and vehicle state definitions as described in the MDS [General Information][general] document. 35 | 36 | [Top][toc] 37 | 38 | ### Authorization 39 | 40 | MDS Agency endpoint producers **SHALL** provide authorization for API endpoints via a bearer token based auth system. When making requests, the endpoints expect `provider_id` to be part of the claims in a [JSON Web Token](https://jwt.io/) (JWT) `access_token` in the `Authorization` header, in the form `Authorization: Bearer `. The token issuance, expiration and revocation policies are at the discretion of the agency. [JSON Web Token](/general-information.md#json-web-tokens) is the recommended format. 41 | 42 | General authorization details are specified in the [Authorization section](/general-information.md#authorization) in MDS General Information. 43 | 44 | [Top][toc] 45 | 46 | ### Versioning 47 | 48 | `Agency` APIs must handle requests for specific versions of the specification from clients. 49 | 50 | Versioning must be implemented as specified in the [Versioning section][versioning]. 51 | 52 | [Top][toc] 53 | 54 | ### Modes 55 | 56 | MDS is intended to be used for multiple transportation modes, including its original micromobility (e-scooters, bikes, etc.) mode, as well as additional modes such as taxis, car share, and delivery bots. A given `provider_id` shall be associated with a single mobility [mode][modes], so that the mode does not have to be specified in each data structure and API call. A provider implementing more than one mode shall [register](/README.md#providers-using-mds) a unique `provider_id` for each mode. 57 | 58 | [Top][toc] 59 | 60 | ### Responses and Error Messages 61 | 62 | The response to a client request must include a valid HTTP status code defined in the [IANA HTTP Status Code Registry][iana]. 63 | 64 | The response must set the `Content-Type` header as specified in the [Versioning section][versioning]. 65 | 66 | Response bodies must be a `UTF-8` encoded JSON object 67 | 68 | See the [Responses][responses], [Error Messages][error-messages], and [Bulk Responses][bulk-responses] sections, and the [schema][schema] for more details. 69 | 70 | [Top][toc] 71 | 72 | ### GBFS 73 | 74 | See the [GBFS Requirement](/README.md#gbfs-requirement) language for more details. 75 | 76 | [Top][toc] 77 | 78 | ### Data Schema 79 | 80 | See the [Endpoints](#endpoints) below for information on their specific schema, and the [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for full details and interactive documentation. 81 | 82 | [Top][toc] 83 | 84 | ## Vehicles 85 | 86 | The `/vehicles` endpoints allow providers to register and update the properties of their fleet vehicles, and query current vehicle properties and status. 87 | 88 | ### Vehicle - Register 89 | 90 | The `/vehicles` registration endpoint is used to register vehicles for use in the Agency's jurisdiction. 91 | 92 | **Endpoint**: `/vehicles` 93 | **Method:** `POST` 94 | **Payload:** An array of [Vehicles](/data-types.md#vehicles) 95 | 96 | #### Responses 97 | 98 | _Possible HTTP Status Codes_: 99 | 201, 100 | 400, 101 | 401, 102 | 406, 103 | 409, 104 | 500 105 | 106 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 107 | 108 | [Top][toc] 109 | 110 | #### Error Codes: 111 | 112 | | `error` | `error_description` | `error_details`[] | 113 | | -------------------- | ------------------------------------------------- | ------------------------------- | 114 | | `bad_param` | A validation error occurred | Array of parameters with errors | 115 | | `missing_param` | A required parameter is missing | Array of missing parameters | 116 | | `already_registered` | A vehicle with `device_id` is already registered | | 117 | 118 | ### Vehicle - Update 119 | 120 | The `/vehicles` update endpoint is used to change vehicle information, should some aspect of the vehicle change, such as the `vehicle_id`. Each vehicle must already be registered. 121 | 122 | **Endpoint**: `/vehicles` 123 | **Method:** `PUT` 124 | **Payload:** An array of [Vehicles](/data-types.md#vehicles) 125 | 126 | #### Responses 127 | 128 | _Possible HTTP Status Codes_: 129 | 200, 130 | 400, 131 | 401, 132 | 406, 133 | 409, 134 | 500 135 | 136 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 137 | 138 | #### Error Codes: 139 | 140 | | `error` | `error_description` | `error_details`[] | 141 | | -------------------- | ------------------------------------------------- | ------------------------------- | 142 | | `bad_param` | A validation error occurred | Array of parameters with errors | 143 | | `unregistered` | This `device_id` is unregistered | | 144 | 145 | [Top][toc] 146 | 147 | ### Vehicle - List 148 | 149 | The `/vehicles` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles. Providers can only retrieve data for vehicles in their registered fleet. Contains vehicle properties that do not change often. 150 | 151 | **Endpoint**: `/vehicles/{device_id}` 152 | **Method:** `GET` 153 | **Payload:** An array of [Vehicles](/data-types.md#vehicles) 154 | 155 | _Path Parameters:_ 156 | 157 | | Path Parameters | Type | Required/Optional | Description | 158 | | ------------ | ---- | ----------------- | ------------------------------------------- | 159 | | `device_id` | UUID | Optional | If provided, retrieve the specified vehicle | 160 | 161 | If `device_id` is specified, `GET` will return an array with a single vehicle record, otherwise it will be a list of vehicle records with pagination details per the [JSON API](https://jsonapi.org/format/#fetching-pagination) spec: 162 | 163 | ```json 164 | { 165 | "version": "2.0.0", 166 | "vehicles": [ ... ] 167 | "links": { 168 | "first": "https://...", 169 | "last": "https://...", 170 | "prev": "https://...", 171 | "next": "https://..." 172 | } 173 | } 174 | ``` 175 | 176 | #### Responses 177 | 178 | _Possible HTTP Status Codes_: 179 | 200, 180 | 400 (with parameter), 181 | 401, 182 | 404, 183 | 406, 184 | 500 185 | 186 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 187 | 188 | [Top][toc] 189 | 190 | ### Vehicle - Status 191 | 192 | The `/vehicles/status` endpoint returns information about the specified vehicle (if a device_id is provided) or a list of known vehicles current state. Providers can only retrieve data for vehicles in their registered fleet. Contains specific vehicle properties that are updated frequently. 193 | 194 | **Endpoint**: `/vehicles/status/{device_id}` 195 | **Method:** `GET` 196 | **Payload:** An array of [Vehicles](/data-types.md#vehicle-status) objects 197 | 198 | _Path Parameters:_ 199 | 200 | | Path Parameters | Type | Required/Optional | Description | 201 | | ------------ | ---- | ----------------- | ------------------------------------------- | 202 | | `device_id` | UUID | Optional | If provided, retrieve the specified vehicle | 203 | 204 | If `device_id` is specified, `GET` will return an array with a vehicle status record, otherwise it will be a list of vehicle records with pagination details per the [JSON API](https://jsonapi.org/format/#fetching-pagination) spec: 205 | 206 | ```json 207 | { 208 | "version": "2.0.0", 209 | "vehicles_status": [ ... ] 210 | "links": { 211 | "first": "https://...", 212 | "last": "https://...", 213 | "prev": "https://...", 214 | "next": "https://..." 215 | } 216 | } 217 | ``` 218 | 219 | #### Responses 220 | 221 | _Possible HTTP Status Codes_: 222 | 200, 223 | 400 (with parameter), 224 | 401, 225 | 404, 226 | 406, 227 | 500 228 | 229 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 230 | 231 | [Top][toc] 232 | 233 | ## Trips 234 | 235 | The Trips endpoint serves two purposes: 236 | 237 | * Definitively indicating that a Trip (a sequence of events linked by a trip_id) has been completed. For example, from analyzing only the raw Vehicle Events feed, if a trip crosses an Agency's jurisdictional boundaries but does not end within the jurisdiction (last event_type seen is a `leave_jurisdiction`), this can result in a 'dangling trip'. The Trips endpoint satisfies this concern, by acting as a final indication that a trip has been finished, even if it ends outside of jurisdictional boundaries; if a trip has intersected an Agency's jurisdictional boundaries at all during a trip, it is expected that a Provider will send a Trip payload to the Agency following the trip's completion. 238 | * Providing information to an Agency regarding an entire trip, without extending any of the Vehicle Event payloads, or changing any requirements on when Vehicle Events should be sent. 239 | 240 | **Endpoint:** `/trips` 241 | **Method:** `POST` 242 | **Payload:** Array of [Trips](/data-types.md#trips) 243 | 244 | ### Responses 245 | 246 | _Possible HTTP Status Codes_: 247 | 201, 248 | 400, 249 | 401, 250 | 404, 251 | 406, 252 | 500 253 | 254 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 255 | 256 | ### Trip Errors: 257 | 258 | | `error` | `error_description` | `error_details`[] | 259 | | -------------------- | ------------------------------------------------- | ------------------------------- | 260 | | `bad_param` | A validation error occurred | Array of parameters with errors | 261 | | `missing_param` | A required parameter is missing | Array of missing parameters | 262 | | `unregistered` | This `device_id` is unregistered | | 263 | 264 | [Top][toc] 265 | 266 | ## Telemetry 267 | 268 | The vehicle `/telemetry` endpoint allows a Provider to send vehicle telemetry data in a batch for any number of vehicles in the fleet. 269 | 270 | **Endpoint**: `/telemetry` 271 | **Method**: `POST` 272 | **Payload**: An array of vehicle [Telemetry][vehicle-telemetry] 273 | 274 | ### Responses 275 | 276 | _Possible HTTP Status Codes_: 277 | 201, 278 | 400, 279 | 401, 280 | 404, 281 | 406, 282 | 500 283 | 284 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 285 | 286 | ### Telemetry Errors: 287 | 288 | | `error` | `error_description` | `error_details`[] | 289 | | -------------------- | ------------------------------------------------- | ------------------------------- | 290 | | `bad_param` | A validation error occurred | Array of parameters with errors | 291 | | `missing_param` | A required parameter is missing | Array of missing parameters | 292 | | `unregistered` | This `device_id` is unregistered | | 293 | 294 | [Top][toc] 295 | 296 | ## Events 297 | 298 | The vehicle `/events` endpoint allows the Provider to submit events describing the state changes of multiple vehicles. 299 | 300 | **Endpoint:** `/events` 301 | **Method:** `POST` 302 | **Payload:** An array of vehicle [Events](/data-types.md#events) 303 | 304 | ### Responses 305 | 306 | _Possible HTTP Status Codes_: 307 | 201, 308 | 400, 309 | 401, 310 | 404, 311 | 406, 312 | 500 313 | 314 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 315 | 316 | ### Event Errors: 317 | 318 | | `error` | `error_description` | `error_details`[] | 319 | | ------- | ------------------- | ----------------- | 320 | | `bad_param` | A validation error occurred | Array of parameters with errors | 321 | | `missing_param` | A required parameter is missing | Array of missing parameters | 322 | | `unregistered` | This `device_id` is unregistered | | 323 | 324 | [Top][toc] 325 | 326 | ## Stops 327 | 328 | ### Stops - Register 329 | 330 | The `/stops` endpoint allows an agency to register city-managed Stops, or a provider to register self-managed Stops. 331 | 332 | **Endpoint:** `/stops` 333 | **Method:** `POST` 334 | **Payload**: An array of [Stops][stops] 335 | 336 | ### Responses 337 | 338 | _Possible HTTP Status Codes_: 339 | 201, 340 | 400, 341 | 401, 342 | 406, 343 | 409, 344 | 500 345 | 346 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 347 | 348 | #### Stops Register Errors: 349 | 350 | | `error` | `error_description` | `error_details`[] | 351 | | -------------------- | ------------------------------------------------- | ------------------------------- | 352 | | `bad_param` | A validation error occurred | Array of parameters with errors | 353 | | `missing_param` | A required parameter is missing | Array of missing parameters | 354 | | `already_registered` | A stop with `stop_id` is already registered | | 355 | 356 | 403 Unauthorized Response: 357 | 358 | **None** 359 | 360 | [Top][toc] 361 | 362 | ### Stops - Update 363 | 364 | **Endpoint:** `/stops` 365 | **Method:** `PUT` 366 | **Payload**: An array of of [Stop][stops] information, where the permitted changeable fields are defined as: 367 | 368 | | Field | Required/Optional | Description | 369 | |------------------------|-------------------|-------------------| 370 | | stop_id | Required |See [Stops][stops] | 371 | | last_updated | Optional |See [Stops][stops] | 372 | | status | Optional |See [Stops][stops] | 373 | | rental_methods | Optional |See [Stops][stops] | 374 | | num_vehicles_available | Optional |See [Stops][stops] | 375 | | num_vehicles_disabled | Optional |See [Stops][stops] | 376 | | num_places_available | Optional |See [Stops][stops] | 377 | | num_places_disabled | Optional |See [Stops][stops] | 378 | | devices | Optional |See [Stops][stops] | 379 | 380 | ### Responses 381 | 382 | _Possible HTTP Status Codes_: 383 | 200, 384 | 400, 385 | 401, 386 | 404, 387 | 406, 388 | 500 389 | 390 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 391 | 392 | #### Stops update Errors: 393 | 394 | | `error` | `error_description` | `error_details`[] | 395 | | -------------------- | ------------------------------------------------- | ------------------------------- | 396 | | `bad_param` | A validation error occurred | Array of parameters with errors | 397 | | `missing_param` | A required parameter is missing | Array of missing parameters | 398 | | `unregistered` | No stop with `stop_id` is already registered | | 399 | 400 | [Top][toc] 401 | 402 | ### Stops - Readback 403 | 404 | **Endpoint:** `/stops/{stop_id}` 405 | **Method:** `GET` 406 | **Payload:** An array of [Stops][stops] 407 | 408 | _Path Parameters:_ 409 | 410 | | Path Parameters | Type | Required/Optional | Description | 411 | | ------------ | ---- | ----------------- | ------------------------------------------- | 412 | | `stop_id` | UUID | Optional | If provided, retrieve the specified stop | 413 | 414 | If `stop_id` is specified, `GET` will return an array with a single stop record, otherwise it will be a list of all stop records. 415 | 416 | ### Responses 417 | 418 | _Possible HTTP Status Codes_: 419 | 200, 420 | 401, 421 | 404, 422 | 406, 423 | 500 424 | 425 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 426 | 427 | [Top][toc] 428 | 429 | ## Reports 430 | 431 | Reports are information that providers can send back to agencies containing aggregated data that is not contained within other MDS endpoints, like counts of special groups of riders. These supplemental reports are not a substitute for other MDS Provider endpoints. 432 | 433 | The authenticated reports are monthly, historic flat files that may be pre-generated by the provider. 434 | 435 | [Top][toc] 436 | 437 | ## Reports - Register 438 | 439 | The `/reports` endpoint allows an agency to register aggregated report counts in CSV structure. 440 | 441 | **Endpoint:** `/reports` 442 | **Method:** `POST` 443 | **Payload**: A CSV of [Reports][reports] 444 | 445 | ### Responses 446 | 447 | _Possible HTTP Status Codes_: 448 | 201, 449 | 400, 450 | 401, 451 | 406, 452 | 500 453 | 454 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 455 | 456 | #### Reports Register Errors: 457 | 458 | | `error` | `error_description` | `error_details`[] | 459 | | -------------------- | ------------------------------------------------- | ------------------------------- | 460 | | `bad_param` | A validation error occurred | Array of parameters with errors | 461 | 462 | 400 Unauthorized Response: 463 | 464 | **None** 465 | 466 | [Top][toc] 467 | 468 | [accessibility-options]: /general-information.md#accessibility-options 469 | [beta]: /general-information.md#beta-features 470 | [bulk-responses]: /general-information.md#bulk-responses 471 | [general]: /general-information.md 472 | [geography-driven-events]: /general-information.md#geography-driven-events 473 | [error-messages]: /general-information.md#error-messages 474 | [hdop]: https://en.wikipedia.org/wiki/Dilution_of_precision_(navigation) 475 | [iana]: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml 476 | [modes]: /modes/README.md 477 | [propulsion-types]: /data-types.md#propulsion-types 478 | [reports]: /data-types.md#reports 479 | [responses]: /general-information.md#responses 480 | [schema]: /schema/ 481 | [stops]: /data-types.md#stops 482 | [telemetry-data]: /data-types.md#telemetry 483 | [trip-data]: /data-types.md#trips 484 | [toc]: #table-of-contents 485 | [ts]: /general-information.md#timestamps 486 | [vehicle]: /data-types.md#vehicles 487 | [vehicle-types]: /data-types.md#vehicle-types 488 | [vehicle-states]: /modes/vehicle_states.md 489 | [vehicle-event-types]: /modes/event_types.md 490 | [vehicle-event]: /data-types.md#events 491 | [vehicle-telemetry]: /data-types.md#telemetry 492 | [versioning]: /general-information.md#versioning 493 | [error-message]: /general-information.md#error-messages 494 | -------------------------------------------------------------------------------- /general-information.md: -------------------------------------------------------------------------------- 1 | # Mobility Data Specification: **General information** 2 | 3 | This document contains specifications that are shared between the various MDS [APIs and endpoints](/README.md#endpoints). 4 | 5 | ## Table of Contents 6 | 7 | - [Authorization](#authorization) 8 | - [Beta Features](#beta-features) 9 | - [Costs and Currencies](#costs-and-currencies) 10 | - [Data Types](#data-types) 11 | - [Definitions](#definitions) 12 | - [Devices](#devices) 13 | - [Field Types](#field-types) 14 | - [Conditionally Required Fields](#conditionally-required-fields) 15 | - [Optional Fields](#optional-fields) 16 | - [Required if Applicable](#required-if-applicable-fields) 17 | - [GBFS Compatibility](#gbfs-compatibility) 18 | - [Geographic Data](#geographic-data) 19 | - [Intersection Operation](#intersection-operation) 20 | - [Geography-Driven Events](#geography-driven-events) 21 | - [Responses](#responses) 22 | - [Error Messages](#error-messages) 23 | - [Bulk Responses](#bulk-responses) 24 | - [Failure Details](#failure-details) 25 | - [Strings](#strings) 26 | - [Timestamps](#timestamps) 27 | - [Trips](#trips) 28 | - [UUIDs](#uuids) 29 | - [Vehicle States](#vehicle-states) 30 | - [Versioning](#versioning) 31 | 32 | ## Authorization 33 | 34 | Outlines shared authorization details and methods across all MDS APIs. 35 | 36 | ### Endpoint Requirements 37 | 38 | All MDS Provider, Agency, and Metrics APIs require authentication, as outlined. 39 | 40 | If implementing MDS Policy, Geography, and/or Jurisdiction APIs and endpoints, an agency must make them unauthenticated and public. This allows transparency for the public to see how the city is regulating, holds the city accountable for their policy decisions, and reduces the technical burden on providers to use these endpoints. A side benefit is that this allows third parties to ingest this information into their applications and services for public benefit. 41 | 42 | As of MDS 0.3.0, `gbfs.json` is required. The required GBFS endpoints should be made available publicly. See Provider [#realtime-data](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/provider#realtime-data) for more information about how to implement GBFS for dockless systems. 43 | 44 | ### Header 45 | 46 | The `Authorization` header is sent as part of an HTTP request. Example: 47 | 48 | ``` 49 | GET /trips HTTP/1.1 50 | Host: api.provider.co 51 | Authorization: Bearer 52 | ``` 53 | 54 | More info on how to document [Bearer Auth in swagger](https://swagger.io/docs/specification/authentication/bearer-authentication/). 55 | 56 | ### JSON Web Tokens 57 | 58 | JSON Web Token ([JWT](https://jwt.io/introduction/)) is **RECOMMENDED** as the token format. 59 | 60 | JWTs provide a safe, secure way to verify the identity of an agency and provide access to MDS resources without providing access to other, potentially sensitive data. 61 | 62 | > 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. 63 | 64 | MDS API producers **MAY** include any metadata in the JWT they wish that helps to route, log, permission, or debug agency requests, leaving their internal implementation flexible. 65 | 66 | JWT provides a helpful [debugger](https://jwt.io/#debugger) for testing your token and verifying security. 67 | 68 | ### OAuth 2.0 69 | 70 | 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. 71 | 72 | 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. 73 | 74 | If an MDS endpoint producer implements this auth scheme, it **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 parsable way. 75 | 76 | [Top][toc] 77 | 78 | ## Beta Features 79 | 80 | In some cases, features within MDS 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. 81 | 82 | Despite this, MDS 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 MDS community via GitHub issues or pull requests. This will inform the refinements that transform beta features into fully proven, stable parts of the specification. You may leave feedback on the appropriate open [feedback issue](https://github.com/openmobilityfoundation/mobility-data-specification/issues?q=is%3Aissue+is%3Aopen+label%3Abeta) tagged with the `beta` label. 83 | 84 | 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. Note that [schemas](/schema) may not be defined for some beta features until they are promoted out of beta. 85 | 86 | Working Groups and their Steering Committees are expected to review beta designated features and [feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues?q=is%3Aissue+is%3Aopen+label%3Abeta) 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. 87 | 88 | [Top][toc] 89 | 90 | ## Field Types 91 | 92 | ### Conditionally Required Fields 93 | 94 | Conditionally required fields **must** be provided in MDS data feeds from operators if the data is available from the operator, and/or the public agency requests it as part of its permit, RFP, contract, operating agreement, SLA, [Requirements](./policy#requirement) file, or via other authority. Or as part of the conditional requirement as stated in the field's descritpion. 95 | 96 | [Top][toc] 97 | 98 | ### Optional Fields 99 | 100 | Optional fields **may** be provided in MDS data feeds from operators if the data is available from the operator, and/or the public agency requests it as part of its permit, RFP, contract, operating agreement, SLA, [Requirements](./policy#requirement) file, or via other authority. 101 | 102 | [Top][toc] 103 | 104 | ### Required if Applicable Fields 105 | 106 | Required if Applicable fields **must** be provided in MDS data feeds from operators if the data is available from the operator, and/or the public agency requests it as part of its permit, RFP, contract, operating agreement, SLA, [Requirements](./policy#requirement) file, or via other authority, and/or the field is relevant to the current provider/mode/program as defined by the public agency. 107 | 108 | [Top][toc] 109 | 110 | ## Costs and Currencies 111 | 112 | 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). 113 | 114 | If the currency field is null, USD cents is implied. 115 | 116 | [Top][toc] 117 | 118 | ## Data Types 119 | 120 | Shared data structures including [vehicles](/data-types.md#vehicles), [vehicle events](/data-types.md#vehicle-state-events), [vehicle telemetry](/data-types.md#telemetry-data), and [trips](/data-types.md#trips) can be found in the [Data Types](/data-types.md) page. 121 | 122 | Standard [JSON data type definitions](https://en.wikipedia.org/wiki/JSON#Data_types) apply when feeds are in JSON format. The spec may also have more specific formatting requests, like enumeration (an enumerated set of approved values), object (an unordered key-value mapping of integer, strings, and symbols), map (an ordered mapping of any data types), integer (whole number), float (number with up to 8 decimal places), double (number with up 16 decimal places), etc. 123 | 124 | [Top][toc] 125 | 126 | ## Definitions 127 | 128 | Defining terminology and abbreviations used throughout MDS. 129 | 130 | - **API** - Application Programming Interface - A function or set of functions that allow one software application to access or communicate with features of a different software application or service. 131 | - **API Endpoint** - A point at which an API connects with a software application or service. 132 | - **DOT** - Department of Transportation, usually a city-run agency. 133 | - **Jurisdiction** - An agency’s area of legal authority to manage and regulate a mobility program in the real world. Note there is also an MDS API called [Jurisdiction](/jurisdiction), which is a way to digitally represent this. 134 | - **PROW** - Public Right of Way - the physical infrastructure reserved for transportation purposes, examples include sidewalks, curbs, bike lanes, transit lanes and stations, traffic lanes and signals, and public parking. 135 | 136 | [Top][toc] 137 | 138 | ## Devices 139 | 140 | MDS defines the _device_ as the unit that transmits GPS or GNSS signals for a particular vehicle. A given device must have a UUID (`device_id` below) that is unique within the Provider's fleet. 141 | 142 | Additionally, `device_id` must remain constant for the device's lifetime of service, regardless of the vehicle components that house the device. 143 | 144 | [Top][toc] 145 | 146 | ## GBFS Compatibility 147 | 148 | Some of the fields in the `Stops` definition are using notions which are currently not in MDS, such as `rental_methods`. These fields are included for compatibility with GBFS. 149 | 150 | [Top][toc] 151 | 152 | ## Geographic Data 153 | 154 | References to geographic datatypes (Point, MultiPolygon, etc.) imply coordinates encoded in the [WGS 84 (EPSG:4326)][wgs84] standard GPS or GNSS projection expressed as [Decimal Degrees][decimal-degrees]. When points are used, you may assume a 20 meter buffer around the point when needed. 155 | 156 | ### Intersection Operation 157 | 158 | For the purposes of this specification, the intersection of two geographic datatypes is defined according to the [`ST_Intersects` PostGIS operation][st-intersects] 159 | 160 | > 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). 161 | > 162 | > 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. 163 | 164 | [Top][toc] 165 | 166 | ## Geography-Driven Events 167 | 168 | **[Beta feature](/general-information.md#beta-features):** _Yes (as of 1.1.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/670) 169 | 170 | Geography-Driven Events (GDE) is an MDS feature for Agencies to perform complete Policy compliance monitoring without precise location data. Geography-Driven Events describe individual vehicles in realtime – not just aggregate data. However, rather than receiving the exact location of a vehicle, Agencies receive information about the vehicle's current geographic region. The regions used for Geography-Driven Events correspond to the Geographies in an Agency's current Policy. In this way, the data-shared using Geography-Driven Events is matched to an Agency's particular regulatory needs. 171 | 172 | See [this example](/policy/examples/requirements.md#geography-driven-events) for how to implement GDE using [Policy Requirements](/policy#requirement). 173 | 174 | Here's how it works in practice: 175 | 176 | 1. The Agency creates a geographic Policy Area for a local regulatory need 177 | 178 | _Scooters traveling within downtown during peak hours incur a $0.20 fee._ 179 | 180 | 2. Providers notify the Agency in real-time about events in the Policy Area. 181 | 182 | _At 5:21pm scooter X7123 entered downtown._ 183 | 184 | 3. The Agency can refine their data needs over time by revising their published Policy Areas. 185 | 186 | _Agency adds rule disallowing parking on waterfront path, begins receiving data on events within area._ 187 | 188 | Agencies that wish to use Geography-Driven Events do so by requiring a new `event_geographies` field in status events. When an Agency is using Geography-Driven Events, Providers must emit a new `changed_geographies` status event whenever a vehicle in a trip enters or leaves a Geography managed by a Policy. 189 | 190 | During the Beta period for this feature, location and telemetry data remain required fields. This allows Agencies to test Geography-Driven Events, measuring its accuracy and efficacy against regulatory systems based on precise location data. After the beta period, if Geography-Driven Events is deemed by the OMF to be accurate and effective, the specification will evolve to allow cities to use Geography-Driven Events in lieu of location or telemetry data. 191 | 192 | [Top][toc] 193 | 194 | ## Responses 195 | 196 | - **200:** OK: operation successful. 197 | - **201:** Created: `POST` operations, new object(s) created 198 | - **400:** Bad request. 199 | - **401:** Unauthorized: Invalid, expired, or insufficient scope of token. 200 | - **404:** Not Found: Object does not exist, returned on `GET` or `POST` operations if the object does not exist. 201 | - **406:** MDS version in Accept header is unsupported or invalid. 202 | - **409:** Conflict: `POST` operations when an object already exists and an update is not possible. 203 | - **500:** Internal server error: In this case, the answer should contain an `application/json` body with an [error message](#error-messages) for troubleshooting. 204 | 205 | ### Error Messages 206 | 207 | ```jsonc 208 | { 209 | "error": "...", 210 | "error_description": "...", 211 | "error_details": ["...", "..."] 212 | } 213 | ``` 214 | 215 | | Field | Type | Field Description | 216 | | ------------------- | -------- | --------------------------------------------------- | 217 | | `error` | String | Error message string | 218 | | `error_description` | String | Human readable error description (can be localized) | 219 | | `error_details` | String[] | Array of error details | 220 | 221 | ### Bulk Responses 222 | 223 | For multi-record POST and PUT calls, e.g. sending Events using the Agency API, the bulk-response structure describes a list of failures is as follows: 224 | 225 | ```jsonc 226 | { 227 | "success": "...", 228 | "total": "...", 229 | "failures": [ { // list of failure details 230 | "item": { ... }, // copy of the item with the problem 231 | "error": "...", 232 | "error_description": "...", 233 | "error_details": [ "...", "..." ] 234 | }, { 235 | // additional failure records 236 | } ] 237 | } 238 | ``` 239 | 240 | | Field | Type | Field Description | 241 | | ---------- | ------------------------------------- | --------------------------------------------------------------- | 242 | | `success` | Integer | Number of successfully written records | 243 | | `total` | Integer | Total number of provided records | 244 | | `failures` | [Failure Details](#failure-details)[] | Array of details about failed records (empty if all successful) | 245 | 246 | ### Failure Details 247 | 248 | | Field | Type | Field Description | 249 | | ------------------- | -------------------- | --------------------------------------------------- | 250 | | `item` | Vehicle, Event, etc. | Invalid submitted item | 251 | | `error` | Enum | Error code | 252 | | `error_description` | String | Human readable error description (can be localized) | 253 | | `error_details` | String[] | Array of fields with errors, if applicable | 254 | 255 | [Top][toc] 256 | 257 | ## Strings 258 | 259 | All String fields, such as `vehicle_id`, are limited to a maximum of 255 characters. 260 | 261 | [Top][toc] 262 | 263 | ## Timestamps 264 | 265 | A `timestamp` refers to integer milliseconds since Unix epoch. 266 | 267 | [Top][toc] 268 | 269 | ## Trips 270 | 271 | Counting trips is a common analysis with MDS data, but in some instances when 272 | a user rents a vehicle the rental may end up being very short because the 273 | vehicle is unusable or because the customer changes their mind. 274 | To facilitate a common definition of trips for analysis, MDS defines a trip 275 | as a user taking control of a vehicle for 60 seconds or more. 276 | If a user reserves a vehicle and cancels before taking control of the vehicle 277 | that reservation does not count as a trip, nor does a user taking control of 278 | the vehicle and canceling or ending the trip in under 60 seconds. 279 | 280 | Providers are still expected to report all trips and trip related events in 281 | all MDS endpoints, but parties may use this definition as a shared reference 282 | at the recommendation of the MDS community when analyzing trips. 283 | 284 | [Top][toc] 285 | 286 | ## UUIDs 287 | 288 | Object identifiers are described via Universally Unique Identifiers [(UUIDs)](https://en.wikipedia.org/wiki/Universally_unique_identifier). For example, the `device_id` field used to uniquely identify a vehicle is a UUID. 289 | 290 | MDS uses Version 1 UUIDs by default. Version 4 UUIDs may be used where noted. 291 | 292 | [Top][toc] 293 | 294 | ## Vehicle States 295 | 296 | See new location within [vehicle states](/modes/vehicle_states.md) in [modes](/modes#vehicle-states). 297 | 298 | [Top][toc] 299 | 300 | ### Event Types 301 | 302 | See new location within [event types](/modes/event_types.md) in [modes](/modes#event-types). 303 | 304 | [Top][toc] 305 | 306 | ### Vehicle State Events 307 | 308 | See new location within [individual modes](/modes#list-of-supported-modes) in [modes](/modes#state-transitions). 309 | 310 | [Top][toc] 311 | 312 | ### State Machine Diagram 313 | 314 | See new location within [individual modes](/modes#list-of-supported-modes) in [modes](/modes#state-machine-diagram). 315 | 316 | [Top][toc] 317 | 318 | ## Versioning 319 | 320 | MDS APIs must handle requests for specific versions of the specification from clients. 321 | 322 | Versioning must be implemented through the use of a custom media-type, `application/vnd.mds+json`, combined with a required `version` parameter. The one exception is the `/reports` endpoint, which returns CSV files instead of JSON, and so uses `text/vnd.mds+csv` as its media-type. 323 | 324 | 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.mds+json;version=1.0`. Only major and minor versions are allowed and required in the media-type version string (not [patch](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md#versioning) releases). 325 | 326 | Clients must specify the version they are targeting through the `Accept` header. For example: 327 | 328 | ```http 329 | Accept: application/vnd.mds+json;version=2.0 330 | ``` 331 | 332 | Since versioning was not available from the start, the following APIs provide a fallback version if the `Accept` header is not set as specified above: 333 | 334 | - The `provider` API must respond as if version `0.2` was requested. 335 | - The `agency` API must respond as if version `0.3` was requested. 336 | - The `policy` API must respond as if version `0.4` was requested. 337 | 338 | If an unsupported or invalid version is requested, the API must respond with a status of `406 Not Acceptable`. 339 | 340 | [Top][toc] 341 | 342 | [decimal-degrees]: https://en.wikipedia.org/wiki/Decimal_degrees 343 | [st-intersects]: https://postgis.net/docs/ST_Intersects.html 344 | [toc]: #table-of-contents 345 | [wgs84]: https://en.wikipedia.org/wiki/World_Geodetic_System 346 | -------------------------------------------------------------------------------- /geography/README.md: -------------------------------------------------------------------------------- 1 | # Mobility Data Specification: Geography 2 | 3 | MDS Geography Icon 4 | 5 | This specification contains a collection of RESTful APIs used to read Geographies (descriptions of geographical information, e.g. multi-polygons, currently represented via GeoJSON). 6 | 7 | Geographical data has many applications in the context of mobility, such as the description of municipal boundaries, locations for pick-up and drop-off zones, and areas of temporary closure for special events or emergencies. This API is intended to support a variety of other APIs, including the Policy API. 8 | 9 | Geographical data will be stored as GeoJSON and read from either `geographies.json` or the `/geographies` endpoint, referenced by UUID. Geography data once published through this API shall be treated as immutable, to ensure that any rules or regulations referring to the boundaries cannot be retroactively changed. A Geography may be deprecated and replaced by updated version with a new UUID. 10 | 11 | ## Table of Contents 12 | 13 | - [General Information](#general-information) 14 | - [Authorization](#authorization) 15 | - [Versioning](#versioning) 16 | - [Distribution](#distribution) 17 | - [Flat Files](#flat-files) 18 | - [Response Format](#response-format) 19 | - [Schema](#schema) 20 | - [Geography Fields](#geography-fields) 21 | - [Previous Geographies](#previous-geographies) 22 | - [Geography Type](#geography-type) 23 | - [File Format](#file-format) 24 | - [Endpoints](#endpoints) 25 | - [Geography](#geography) 26 | - [Geographies](#geographies) 27 | - [Examples](#examples) 28 | 29 | ## General Information 30 | 31 | The following information applies to all `geography` API endpoints. 32 | 33 | [Top][toc] 34 | 35 | ### Authorization 36 | 37 | This endpoint should be made public. Authorization is not required. 38 | 39 | [Top][toc] 40 | 41 | ### Versioning 42 | 43 | MDS APIs must handle requests for specific versions of the specification from clients. 44 | 45 | Versioning must be implemented as specified in the [Versioning section][versioning]. 46 | 47 | [Top][toc] 48 | 49 | ## Distribution 50 | 51 | Geographies shall be published by regulatory agencies or their authorized delegates as JSON objects. These JSON objects shall be served by either [flat files](#flat-files) or via [REST API endpoints](#endpoints). In either case, geography data shall follow the [schema](#schema) outlined below. 52 | 53 | Published geographies, should be treated as immutable data. Obsoleting or otherwise changing a geography is accomplished by publishing a new geography with a field named `prev_geographies`, a list of UUID references to the geography or policies geographies by the new geography. 54 | 55 | Geographical data shall be represented as GeoJSON `FeatureCollection` objects. Typically no part of the geographical data should be outside the [municipality boundary][muni-boundary] unless an agency has the authority to regulate there. 56 | 57 | Geographies should be re-fetched at an agreed upon interval between providers and agencies, or when either entity requests it. 58 | 59 | [Top][toc] 60 | 61 | ### Flat Files 62 | 63 | To use a flat file, geographies shall be represented in one (1) file equivalent to the /geographies endpoint: 64 | 65 | - `geographies.json` in Geography API 66 | 67 | The files shall be structured like the output of the [REST endpoints](#endpoints) above. 68 | 69 | The publishing Agency should establish and communicate to providers how frequently these files should be polled. 70 | 71 | The `last_updated` field in the payload wrapper should be set to the time of publishing a revision, so that it is simple to identify a changed file. 72 | 73 | [Top][toc] 74 | 75 | ### Response Format 76 | 77 | See the [Responses][responses] and [Error Messages][error-messages] sections. 78 | 79 | [Top][toc] 80 | 81 | ## Schema 82 | 83 | See the [Endpoints](#endpoints) below for links to specific data objects, and the [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for full details and interactive documentation. 84 | 85 | [Top][toc] 86 | 87 | ### Geography Fields 88 | 89 | | Name | Type | Required/Optional | Description | 90 | | ---------------- | --------- | --- | --------------------------------------------------------------------------------------------- | 91 | | `name` | String | Required | Name of geography | 92 | | `description` | String | [Optional](../general-information.md#optional-fields) | Detailed description of geography | 93 | | `geography_type` | String | [Optional](../general-information.md#optional-fields) | Type of geography, e.g. `municipal_boundary` or `council_district` or custom text. See [Geography Type](#geography-type). | 94 | | `geography_id` | UUID | Required | Unique ID of geography | 95 | | `geography_json` | JSON | Required | The GeoJSON that defines the geographical coordinates. | 96 | | `effective_date` | [timestamp][ts] | [Optional](../general-information.md#optional-fields) | The date at which a Geography is considered "live". Must be at or after `published_date`. | 97 | | `published_date` | [timestamp][ts] | Required | Time that the geography was published, i.e. made immutable | 98 | | `retire_date` | [timestamp][ts] | [Optional](../general-information.md#optional-fields) | Time that the geography is slated to retire. Once the retire date is passed, new policies can no longer reference it and old policies referencing it should be updated. Retired geographies should continue to be returned in the geographies list. Must be after `effective_date`. Geographies referencing others with `prev_geographies` immediately replace the previous ones. | 99 | | `prev_geographies` | UUID[] | [Optional](../general-information.md#optional-fields) | Unique IDs of prior geographies replaced by this one | 100 | 101 | [Top][toc] 102 | 103 | ### Previous Geographies 104 | 105 | Obsoleting or otherwise changing a geography is accomplished by publishing a new geography with the `prev_geographies` field, which is a list of UUID references to the geography or geographies superseded by the new geography. The previous geographies are also published in the `/geographies` endpoint. Using it allows agencies to look back historically at previously published geographies, for analysis, historic reference, or an auditable change trail. 106 | 107 | This field is optional can be omitted by the publishing Agency. 108 | 109 | [Top][toc] 110 | 111 | ### Geography Type 112 | 113 | Type of geography. These specific types are recommendations based on ones commonly defined by agencies. Others may be created by the Agency as needed, or the optional `geography_type` field may be omitted. 114 | 115 | `geography_type` does not imply policy or required actions by providers, but instead is for organizational and discovery purposes within the standalone Geography API. Geographies need to be referenced from other areas of MDS to be meaningfully applied. 116 | 117 | | Value | Description | 118 | | ----- | ----------- | 119 | | `municipal_boundary` | Edge of a city | 120 | | `policy_zone` | Zone where [Policy](/policy) rules could be in effect, like operating area, distribution/equity zones, no/slow ride zone, no parking, etc | 121 | | `county_boundary` | Edge of a county | 122 | | `stop` | See [Stops](/general-information.md#stops) | 123 | | `council_district` | City council district | 124 | | `political_district` | Politically defined voting area | 125 | | `neighborhood` | Neighborhood area | 126 | | `market_area` | Economic area | 127 | | `opportunity_zone` | Defined Opportunity Zone | 128 | | `overlay_district` | Agency overlay district | 129 | | `post_code` | Zip or postal code | 130 | | `traffic_zone` | Transportation planning area | 131 | | `property_line` | One or more property lines | 132 | | `right_of_way` | Public right of way area | 133 | | `census_block` | Census block | 134 | | `census_block_group` | Census block group | 135 | | `census_tract` | Census tract | 136 | 137 | [Top][toc] 138 | 139 | ## File format 140 | 141 | Note: to use flat files rather than REST endpoints, Geography objects should be stored in `geographies.json`. The `geographies.json` file will look like the output of `GET /geographies`. 142 | 143 | Example `geographies.json` 144 | 145 | ```jsonc 146 | { 147 | "version": "2.0.0", 148 | "last_updated": "1682984274000", 149 | "geographies": [ 150 | { 151 | // Geography 1 152 | }, 153 | { 154 | // Geography 2 155 | } 156 | ] 157 | } 158 | ``` 159 | 160 | #### Responses 161 | 162 | _Possible HTTP Status Codes_: 163 | 200, 164 | 404, 165 | 406, 166 | 500 167 | 168 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 169 | 170 | [Top][toc] 171 | 172 | ## Endpoints 173 | 174 | Responses must set the `Content-Type` header, as specified in the [Provider versioning](../provider/README.md#versioning) section. They must also specify the API version in the JSON-formatted response body, under the `version` key. 175 | 176 | The Geography API consists of the following endpoints: 177 | 178 | ### Geography 179 | 180 | **Endpoint**: `/geographies/{geography_id}` 181 | **Method**: `GET` 182 | **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. 183 | 184 | #### Path Parameters 185 | 186 | | Path Parameter | Type | Required/Optional | Description | 187 | | -------------- | ---- | ----------------- | ------------------------------------------------- | 188 | | `geography_id` | UUID | Required | Unique identifier for a single specific Geography | 189 | 190 | Returns: Details of a single Geography based on a UUID. 191 | 192 | Response body: 193 | 194 | ```js 195 | { 196 | "version": "2.0.0", 197 | "geography": { 198 | "geography_id": UUID, 199 | "geography_type": string, 200 | "name": string, 201 | "description": string, 202 | "published_date": timestamp, 203 | "effective_date": timestamp, 204 | "prev_geographies": UUID[], 205 | "geography_json": GeoJSON FeatureCollection 206 | } 207 | } 208 | ``` 209 | 210 | #### Responses 211 | 212 | _Possible HTTP Status Codes_: 213 | 200, 214 | 400 (with parameter), 215 | 404, 216 | 406, 217 | 500 218 | 219 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 220 | 221 | [Top][toc] 222 | 223 | ### Geographies 224 | 225 | **Endpoint**: `/geographies` 226 | **Method**: `GET` 227 | **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. 228 | 229 | Returns: All geography objects 230 | 231 | Response body: 232 | 233 | ```jsonc 234 | { 235 | "version": "2.0.0", 236 | "last_updated": "1682984274000", 237 | "geographies": [ 238 | { 239 | // Geography 1 240 | }, 241 | { 242 | // Geography 2 243 | } 244 | ] 245 | } 246 | ``` 247 | 248 | #### Responses 249 | 250 | _Possible HTTP Status Codes_: 251 | 200, 252 | 404, 253 | 406, 254 | 500 255 | 256 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 257 | 258 | [Top][toc] 259 | 260 | ## Examples 261 | 262 | See the [Geography Examples](examples/README.md) for ways these can be implemented and geometry previews. 263 | 264 | [Top][toc] 265 | 266 | [bulk-responses]: /general-information.md#bulk-responses 267 | [error-messages]: /general-information.md#error-messages 268 | [responses]: /general-information.md#responses 269 | [schema]: /schema/ 270 | [ts]: /general-information.md#timestamps 271 | [versioning]: /general-information.md#versioning 272 | [muni-boundary]: ../provider/README.md#municipality-boundary 273 | [toc]: #table-of-contents 274 | -------------------------------------------------------------------------------- /geography/examples/README.md: -------------------------------------------------------------------------------- 1 | # Geography Examples 2 | 3 | This file presents a series of example [Geography](/geography) files to use as reference and to see previews online. 4 | 5 | ## Table of Contents 6 | 7 | - [All Geographies](#all-geographies) 8 | - [Municipal Boundary](#municipal-boundary) 9 | - [Operating Area](#operating-area) 10 | - [Distribution Zone](#distribution-zone) 11 | - [No Ride Zone](#no-ride-zone) 12 | - [Slow Ride Zone](#slow-ride-zone) 13 | - [Stop](#stop) 14 | 15 | ## All Geographies 16 | 17 | All of the examples below will be presented within the single [/geographies](/geography#geographies) endpoint. 18 | 19 | **File with full geometry**: [`geographies.json`](geographies.json) 20 | 21 | **GeoJSON sample to view all geometries together in a preview**: [`geographies.geojson`](geographies.geojson) 22 | 23 | _Note GeoJSON example files are just for your reference and to generate a preview on Github. The GeoJSON files alone are not part of MDS._ 24 | 25 | ## Municipal Boundary 26 | 27 | Shows the muncipal boundaries of a regulating entity, which may be larger than the permitted operating area. 28 | 29 | **File with full geometry**: [`municipal-boundary.json`](municipal-boundary.json) 30 | 31 | **GeoJSON part of file with preview**: [`municipal-boundary.geojson`](municipal-boundary.geojson) 32 | 33 | ```json 34 | { 35 | "version": "1.2.0", 36 | "geography": { 37 | "geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208", 38 | "geography_type": "municipal_boundary", 39 | "name": "Municipal Boundary", 40 | "description": "Full municipal jurisdiction for the combined city/county", 41 | "effective_date": 1570034561834, 42 | "published_date": 1570035222868, 43 | "prev_geographies": [ 44 | "40d78c83-493f-40ad-8aba-a1ef036c5ffa" 45 | ], 46 | "geography_json": MUNICIPAL_BOUNDARY_GEOGRAPHY 47 | } 48 | } 49 | ``` 50 | 51 | [Top](#table-of-contents) 52 | 53 | ## Operating Area 54 | 55 | Boundaries of a city's permitted operating area for provider vehicles. 56 | 57 | **File with full geometry**: [`operating-area.json`](operating-area.json) 58 | 59 | **GeoJSON part of file with preview**: [`operating-area.geojson`](operating-area.geojson) 60 | 61 | ```json 62 | { 63 | "version": "1.2.0", 64 | "geography": { 65 | "geography_id": "8ad39dc3-005b-4348-9d61-c830c54c161b", 66 | "geography_type": "operating_area", 67 | "name": "Operating Area", 68 | "description": "Municipal permitted operating area for devices", 69 | "effective_date": 1570034561834, 70 | "published_date": 1570035222868, 71 | "prev_geographies": [ 72 | "6100b029-a943-439c-b344-72bcc8e78d15", 73 | "5ce17f69-d869-4103-b414-9f213fd6347d" 74 | ], 75 | "geography_json": OPERATING_AREA_GEOGRAPHY 76 | } 77 | } 78 | ``` 79 | 80 | [Top](#table-of-contents) 81 | 82 | ## Distribution Zone 83 | 84 | Boundaries of one of 9 areas in a city where vehicles can be distibuted and reblananced. 85 | 86 | **File with full geometry**: [`distribution-zone-8.json`](distribution-zone.json) 87 | 88 | **GeoJSON part of file with preview**: [`distribution-zone-8.geojson`](distribution-zone.geojson) 89 | 90 | ```json 91 | { 92 | "version": "1.2.0", 93 | "geography": { 94 | "geography_id": "70a91abc-0d9f-43a9-8e6a-763142dc6c94", 95 | "geography_type": "distribution_zone", 96 | "name": "Distribution Zone #8", 97 | "description": "Distribution area for reblancing vehicles. One of 9 zones in the city.", 98 | "effective_date": 1570034561834, 99 | "published_date": 1570035222868, 100 | "prev_geographies": [ 101 | "036e9c50-ae67-4135-a9e1-31df1f76f4a2", 102 | "3198dd92-749f-48e9-93ff-dd6ef4ec4149", 103 | "ba5ed96c-3d64-4bf7-a3ad-5e1b9fae5841" 104 | ], 105 | "geography_json": DISTRIBUTION_ZONE_GEOGRAPHY 106 | } 107 | } 108 | ``` 109 | 110 | [Top](#table-of-contents) 111 | 112 | ## No Ride Zone 113 | 114 | Boundaries of areas in a city where vehicles are not allowed be ridden by riders. 115 | 116 | **File with full geometry**: [`no-ride-zone.json`](no-ride-zone.json) 117 | 118 | **GeoJSON part of file with preview**: [`no-ride-zone.geojson`](no-ride-zone.geojson) 119 | 120 | ```json 121 | { 122 | "version": "1.2.0", 123 | "geography": { 124 | "geography_id": "fc277865-79d3-4f0e-8459-53e9a647db99", 125 | "geography_type": "slow_ride_zone", 126 | "name": "Slow Ride Zones", 127 | "description": "Areas where vehicles are to be ridden at a reduced top speed", 128 | "effective_date": 1570034561834, 129 | "published_date": 1570035222868, 130 | "geography_json": NO_RIDE_ZONE_GEOGRAPHY 131 | } 132 | } 133 | ``` 134 | 135 | [Top](#table-of-contents) 136 | 137 | ## Slow Ride Zone 138 | 139 | Boundaries of areas in a city where vehicles are to be ridden at a slower top speed than what is allowed in the rest of the operating area. 140 | 141 | **File with full geometry**: [`slow-ride-zone.json`](slow-ride-zone.json) 142 | 143 | **GeoJSON part of file with preview**: [`slow-ride-zone.geojson`](slow-ride-zone.geojson) 144 | 145 | ```json 146 | { 147 | "version": "1.2.0", 148 | "geography": { 149 | "geography_id": "8ad39dc3-005b-4348-9d61-c830c54c161b", 150 | "geography_type": "operating_area", 151 | "name": "Operating Area", 152 | "description": "Municipal permitted operating area for devices", 153 | "effective_date": 1570034561834, 154 | "published_date": 1570035222868, 155 | "prev_geographies": [ 156 | "6100b029-a943-439c-b344-72bcc8e78d15", 157 | "5ce17f69-d869-4103-b414-9f213fd6347d" 158 | ], 159 | "geography_json": SLOW_RIDE_ZONE_GEOGRAPHY 160 | } 161 | } 162 | ``` 163 | 164 | [Top](#table-of-contents) 165 | 166 | 167 | ## Stop 168 | 169 | Designated stoping areas for vehicles. In this example the recommended parking locations are spray-painted on the sidewalk. Note these are represented as `Point` geometry types, not `MultiPolygon` like other examples. 170 | 171 | **File with full geometry**: [`stop.json`](stop.json) 172 | 173 | **GeoJSON part of file with preview**: [`stop.geojson`](stop.geojson) 174 | 175 | ```json 176 | { 177 | "version": "1.2.0", 178 | "geography": { 179 | "geography_id": "d1328cdb-92fe-4267-85e0-a9fe5653268e", 180 | "geography_type": "stop", 181 | "name": "Parking areas", 182 | "description": "Highlands area preferred parking locations", 183 | "effective_date": 1570034561834, 184 | "published_date": 1570035222868, 185 | "prev_geographies": [ 186 | "789f677f-38eb-4397-a2ec-eca3f5c2ccb7", 187 | "fa4a3d92-706b-4400-8f44-0170b2ad632b", 188 | "1d4587ae-5cc4-4950-9ac8-aec3f558dd39", 189 | "e8ed9fc7-f0e2-4117-ae7b-6607ff60c413" 190 | ], 191 | "geography_json": SLOW_RIDE_ZONE_GEOGRAPHY 192 | } 193 | } 194 | ``` 195 | 196 | [Top](#table-of-contents) 197 | 198 | -------------------------------------------------------------------------------- /geography/examples/municipal-boundary.geojson: -------------------------------------------------------------------------------- 1 | { 2 | "type": "FeatureCollection", 3 | "name": "municipal-boundary", 4 | "crs": { 5 | "type": "name", 6 | "properties": { 7 | "name": "urn:ogc:def:crs:OGC:1.3:CRS84" 8 | } 9 | }, 10 | "features": [ 11 | { 12 | "type": "Feature", 13 | "properties": { 14 | "OBJECTID": 5, 15 | "Id": 0, 16 | "Sq_Mi": 60.550265754, 17 | "Shape_Leng": 185901.063827, 18 | "Shape_Area": 1663704916.55 19 | }, 20 | "geometry": { 21 | "type": "MultiPolygon", 22 | "coordinates": [ 23 | [ 24 | [ 25 | [ 26 | -85.58527205, 27 | 38.33943051 28 | ], 29 | [ 30 | -85.57472593, 31 | 38.33397682 32 | ], 33 | [ 34 | -85.56132152, 35 | 38.33712447 36 | ], 37 | [ 38 | -85.46820576, 39 | 38.28530907 40 | ], 41 | [ 42 | -85.40489897, 43 | 38.26372993 44 | ], 45 | [ 46 | -85.42882965, 47 | 38.11838268 48 | ], 49 | [ 50 | -85.47990054, 51 | 38.10012788 52 | ], 53 | [ 54 | -85.5156694, 55 | 38.0888458 56 | ], 57 | [ 58 | -85.55727019, 59 | 38.0738407 60 | ], 61 | [ 62 | -85.71257769, 63 | 38.08731067 64 | ], 65 | [ 66 | -85.87491706, 67 | 38.04249755 68 | ], 69 | [ 70 | -85.9127894, 71 | 38.02065209 72 | ], 73 | [ 74 | -85.91386636, 75 | 38.01084294 76 | ], 77 | [ 78 | -85.92296871, 79 | 38.00835825 80 | ], 81 | [ 82 | -85.93439332, 83 | 37.99721021 84 | ], 85 | [ 86 | -85.94504404, 87 | 38.00242617 88 | ], 89 | [ 90 | -85.92365375, 91 | 38.02485602 92 | ], 93 | [ 94 | -85.91897861, 95 | 38.04069909 96 | ], 97 | [ 98 | -85.91615965, 99 | 38.06363497 100 | ], 101 | [ 102 | -85.90503869, 103 | 38.08999571 104 | ], 105 | [ 106 | -85.90447161, 107 | 38.10704281 108 | ], 109 | [ 110 | -85.90909604, 111 | 38.14234149 112 | ], 113 | [ 114 | -85.90694183, 115 | 38.16551688 116 | ], 117 | [ 118 | -85.8960499, 119 | 38.18545067 120 | ], 121 | [ 122 | -85.87498805, 123 | 38.20769732 124 | ], 125 | [ 126 | -85.85167377, 127 | 38.22260746 128 | ], 129 | [ 130 | -85.8388626, 131 | 38.24053623 132 | ], 133 | [ 134 | -85.83604951, 135 | 38.2654566 136 | ], 137 | [ 138 | -85.82906505, 139 | 38.27655435 140 | ], 141 | [ 142 | -85.81454622, 143 | 38.28300985 144 | ], 145 | [ 146 | -85.78805785, 147 | 38.28835803 148 | ], 149 | [ 150 | -85.77307441, 151 | 38.28576107 152 | ], 153 | [ 154 | -85.76092171, 155 | 38.2719139 156 | ], 157 | [ 158 | -85.74159518, 159 | 38.26766835 160 | ], 161 | [ 162 | -85.67996168, 163 | 38.29758455 164 | ], 165 | [ 166 | -85.65437319, 167 | 38.32535197 168 | ], 169 | [ 170 | -85.6386343, 171 | 38.36385737 172 | ], 173 | [ 174 | -85.63781707, 175 | 38.38023911 176 | ], 177 | [ 178 | -85.56941279, 179 | 38.34175185 180 | ], 181 | [ 182 | -85.58527205, 183 | 38.33943051 184 | ] 185 | ] 186 | ] 187 | ] 188 | } 189 | } 190 | ] 191 | } -------------------------------------------------------------------------------- /geography/examples/municipal-boundary.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": "1.2.0", 3 | "geography": { 4 | "geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208", 5 | "geography_type": "municipal_boundary", 6 | "name": "Municipal Boundary", 7 | "description": "Full municipal jurisdiction for the combined city/county", 8 | "effective_date": 1570034561834, 9 | "published_date": 1570035222868, 10 | "prev_geographies": [ 11 | "40d78c83-493f-40ad-8aba-a1ef036c5ffa" 12 | ], 13 | "geography_json": { 14 | "type": "FeatureCollection", 15 | "name": "municpal-area", 16 | "crs": { 17 | "type": "name", 18 | "properties": { 19 | "name": "urn:ogc:def:crs:OGC:1.3:CRS84" 20 | } 21 | }, 22 | "features": [ 23 | { 24 | "type": "Feature", 25 | "properties": { 26 | "OBJECTID": 5, 27 | "Id": 0, 28 | "Sq_Mi": 60.550265754, 29 | "Shape_Leng": 185901.063827, 30 | "Shape_Area": 1663704916.55 31 | }, 32 | "geometry": { 33 | "type": "MultiPolygon", 34 | "coordinates": [ 35 | [ 36 | [ 37 | [ 38 | -85.58527205, 39 | 38.33943051 40 | ], 41 | [ 42 | -85.57472593, 43 | 38.33397682 44 | ], 45 | [ 46 | -85.56132152, 47 | 38.33712447 48 | ], 49 | [ 50 | -85.46820576, 51 | 38.28530907 52 | ], 53 | [ 54 | -85.40489897, 55 | 38.26372993 56 | ], 57 | [ 58 | -85.42882965, 59 | 38.11838268 60 | ], 61 | [ 62 | -85.47990054, 63 | 38.10012788 64 | ], 65 | [ 66 | -85.5156694, 67 | 38.0888458 68 | ], 69 | [ 70 | -85.55727019, 71 | 38.0738407 72 | ], 73 | [ 74 | -85.71257769, 75 | 38.08731067 76 | ], 77 | [ 78 | -85.87491706, 79 | 38.04249755 80 | ], 81 | [ 82 | -85.9127894, 83 | 38.02065209 84 | ], 85 | [ 86 | -85.91386636, 87 | 38.01084294 88 | ], 89 | [ 90 | -85.92296871, 91 | 38.00835825 92 | ], 93 | [ 94 | -85.93439332, 95 | 37.99721021 96 | ], 97 | [ 98 | -85.94504404, 99 | 38.00242617 100 | ], 101 | [ 102 | -85.92365375, 103 | 38.02485602 104 | ], 105 | [ 106 | -85.91897861, 107 | 38.04069909 108 | ], 109 | [ 110 | -85.91615965, 111 | 38.06363497 112 | ], 113 | [ 114 | -85.90503869, 115 | 38.08999571 116 | ], 117 | [ 118 | -85.90447161, 119 | 38.10704281 120 | ], 121 | [ 122 | -85.90909604, 123 | 38.14234149 124 | ], 125 | [ 126 | -85.90694183, 127 | 38.16551688 128 | ], 129 | [ 130 | -85.8960499, 131 | 38.18545067 132 | ], 133 | [ 134 | -85.87498805, 135 | 38.20769732 136 | ], 137 | [ 138 | -85.85167377, 139 | 38.22260746 140 | ], 141 | [ 142 | -85.8388626, 143 | 38.24053623 144 | ], 145 | [ 146 | -85.83604951, 147 | 38.2654566 148 | ], 149 | [ 150 | -85.82906505, 151 | 38.27655435 152 | ], 153 | [ 154 | -85.81454622, 155 | 38.28300985 156 | ], 157 | [ 158 | -85.78805785, 159 | 38.28835803 160 | ], 161 | [ 162 | -85.77307441, 163 | 38.28576107 164 | ], 165 | [ 166 | -85.76092171, 167 | 38.2719139 168 | ], 169 | [ 170 | -85.74159518, 171 | 38.26766835 172 | ], 173 | [ 174 | -85.67996168, 175 | 38.29758455 176 | ], 177 | [ 178 | -85.65437319, 179 | 38.32535197 180 | ], 181 | [ 182 | -85.6386343, 183 | 38.36385737 184 | ], 185 | [ 186 | -85.63781707, 187 | 38.38023911 188 | ], 189 | [ 190 | -85.56941279, 191 | 38.34175185 192 | ], 193 | [ 194 | -85.58527205, 195 | 38.33943051 196 | ] 197 | ] 198 | ] 199 | ] 200 | } 201 | } 202 | ] 203 | } 204 | } 205 | } 206 | -------------------------------------------------------------------------------- /geography/examples/no-ride-zone.geojson: -------------------------------------------------------------------------------- 1 | { 2 | "type": "FeatureCollection", 3 | "name": "no-ride-zone", 4 | "crs": { 5 | "type": "name", 6 | "properties": { 7 | "name": "urn:ogc:def:crs:OGC:1.3:CRS84" 8 | } 9 | }, 10 | "features": [ 11 | { 12 | "type": "Feature", 13 | "properties": { 14 | "FID": 1, 15 | "NAME": "American Printing House for the Blind", 16 | "SHAPE_Length": 0.008786699248095768, 17 | "SHAPE_Area": 2.4292961698961585e-06 18 | }, 19 | "geometry": { 20 | "type": "MultiPolygon", 21 | "coordinates": [ 22 | [ 23 | [ 24 | [ 25 | -85.71327111, 26 | 38.25848578 27 | ], 28 | [ 29 | -85.7145899, 30 | 38.25621372 31 | ], 32 | [ 33 | -85.71459281, 34 | 38.25621466 35 | ], 36 | [ 37 | -85.71522925, 38 | 38.25641957 39 | ], 40 | [ 41 | -85.7134008, 42 | 38.25956836 43 | ], 44 | [ 45 | -85.71269938, 46 | 38.25947038 47 | ], 48 | [ 49 | -85.71326986, 50 | 38.25848793 51 | ], 52 | [ 53 | -85.71327111, 54 | 38.25848578 55 | ] 56 | ] 57 | ] 58 | ] 59 | } 60 | }, 61 | { 62 | "type": "Feature", 63 | "properties": { 64 | "FID": 2, 65 | "NAME": "KY School for the Blind", 66 | "SHAPE_Length": 0.012435195555633537, 67 | "SHAPE_Area": 6.229622820920614e-06 68 | }, 69 | "geometry": { 70 | "type": "MultiPolygon", 71 | "coordinates": [ 72 | [ 73 | [ 74 | [ 75 | -85.71459281, 76 | 38.25621466 77 | ], 78 | [ 79 | -85.7145899, 80 | 38.25621372 81 | ], 82 | [ 83 | -85.71327111, 84 | 38.25848578 85 | ], 86 | [ 87 | -85.71227601, 88 | 38.25813677 89 | ], 90 | [ 91 | -85.71204161, 92 | 38.25855033 93 | ], 94 | [ 95 | -85.71159414, 96 | 38.2593398 97 | ], 98 | [ 99 | -85.71075294, 100 | 38.25941936 101 | ], 102 | [ 103 | -85.71075293, 104 | 38.25941881 105 | ], 106 | [ 107 | -85.71056428, 108 | 38.25943936 109 | ], 110 | [ 111 | -85.71074694, 112 | 38.25912091 113 | ], 114 | [ 115 | -85.71074692, 116 | 38.25911986 117 | ], 118 | [ 119 | -85.71200893, 120 | 38.25692731 121 | ], 122 | [ 123 | -85.71275985, 124 | 38.25562265 125 | ], 126 | [ 127 | -85.71459402, 128 | 38.25621258 129 | ], 130 | [ 131 | -85.71459281, 132 | 38.25621466 133 | ] 134 | ] 135 | ] 136 | ] 137 | } 138 | }, 139 | { 140 | "type": "Feature", 141 | "properties": { 142 | "FID": 6, 143 | "NAME": "Louisville Extreme Park", 144 | "SHAPE_Length": 0.003190486845852509, 145 | "SHAPE_Area": 5.84308612752141e-07 146 | }, 147 | "geometry": { 148 | "type": "MultiPolygon", 149 | "coordinates": [ 150 | [ 151 | [ 152 | [ 153 | -85.74076188, 154 | 38.25675413 155 | ], 156 | [ 157 | -85.74033647, 158 | 38.25746045 159 | ], 160 | [ 161 | -85.74026824, 162 | 38.2574506 163 | ], 164 | [ 165 | -85.74017398, 166 | 38.25749829 167 | ], 168 | [ 169 | -85.73970603, 170 | 38.25745777 171 | ], 172 | [ 173 | -85.73966427, 174 | 38.25741181 175 | ], 176 | [ 177 | -85.7397857, 178 | 38.25692035 179 | ], 180 | [ 181 | -85.73989459, 182 | 38.25692254 183 | ], 184 | [ 185 | -85.73997195, 186 | 38.25671414 187 | ], 188 | [ 189 | -85.74016274, 190 | 38.25672959 191 | ], 192 | [ 193 | -85.74017108, 194 | 38.25669372 195 | ], 196 | [ 197 | -85.74076188, 198 | 38.25675413 199 | ] 200 | ] 201 | ] 202 | ] 203 | } 204 | }, 205 | { 206 | "type": "Feature", 207 | "properties": { 208 | "FID": 9, 209 | "NAME": "Kentucky Exposition Center", 210 | "SHAPE_Length": 0.06213523936093914, 211 | "SHAPE_Area": 0.00012913879497045022 212 | }, 213 | "geometry": { 214 | "type": "MultiPolygon", 215 | "coordinates": [ 216 | [ 217 | [ 218 | [ 219 | -85.74985389, 220 | 38.20634694 221 | ], 222 | [ 223 | -85.74935347, 224 | 38.20640105 225 | ], 226 | [ 227 | -85.74876787, 228 | 38.20642765 229 | ], 230 | [ 231 | -85.74815792, 232 | 38.20644501 233 | ], 234 | [ 235 | -85.74740824, 236 | 38.20642603 237 | ], 238 | [ 239 | -85.7467669, 240 | 38.20638657 241 | ], 242 | [ 243 | -85.74596683, 244 | 38.20626809 245 | ], 246 | [ 247 | -85.74512329, 248 | 38.20609295 249 | ], 250 | [ 251 | -85.74447931, 252 | 38.20592478 253 | ], 254 | [ 255 | -85.74395635, 256 | 38.20576459 257 | ], 258 | [ 259 | -85.7434141, 260 | 38.20554744 261 | ], 262 | [ 263 | -85.74265757, 264 | 38.20519474 265 | ], 266 | [ 267 | -85.74155182, 268 | 38.20460811 269 | ], 270 | [ 271 | -85.74098444, 272 | 38.20434358 273 | ], 274 | [ 275 | -85.73978801, 276 | 38.20375332 277 | ], 278 | [ 279 | -85.73877965, 280 | 38.20319879 281 | ], 282 | [ 283 | -85.73724097, 284 | 38.20241738 285 | ], 286 | [ 287 | -85.73683058, 288 | 38.20214607 289 | ], 290 | [ 291 | -85.73636457, 292 | 38.20181348 293 | ], 294 | [ 295 | -85.73594015, 296 | 38.20144697 297 | ], 298 | [ 299 | -85.73553913, 300 | 38.20104203 301 | ], 302 | [ 303 | -85.73513675, 304 | 38.20057035 305 | ], 306 | [ 307 | -85.73488646, 308 | 38.20014918 309 | ], 310 | [ 311 | -85.7346991, 312 | 38.19985118 313 | ], 314 | [ 315 | -85.73449626, 316 | 38.1993865 317 | ], 318 | [ 319 | -85.73431798, 320 | 38.19894057 321 | ], 322 | [ 323 | -85.73414389, 324 | 38.19810838 325 | ], 326 | [ 327 | -85.73408145, 328 | 38.19771343 329 | ], 330 | [ 331 | -85.73400692, 332 | 38.19731863 333 | ], 334 | [ 335 | -85.73397264, 336 | 38.19711881 337 | ], 338 | [ 339 | -85.73672593, 340 | 38.19584885 341 | ], 342 | [ 343 | -85.73890388, 344 | 38.19458974 345 | ], 346 | [ 347 | -85.74042529, 348 | 38.19365248 349 | ], 350 | [ 351 | -85.74065301, 352 | 38.19370917 353 | ], 354 | [ 355 | -85.74082205, 356 | 38.19385005 357 | ], 358 | [ 359 | -85.74090876, 360 | 38.19402774 361 | ], 362 | [ 363 | -85.7409581, 364 | 38.1942238 365 | ], 366 | [ 367 | -85.7410067, 368 | 38.1943841 369 | ], 370 | [ 371 | -85.74111595, 372 | 38.19455554 373 | ], 374 | [ 375 | -85.74127853, 376 | 38.19475014 377 | ], 378 | [ 379 | -85.74144574, 380 | 38.19480165 381 | ], 382 | [ 383 | -85.74281591, 384 | 38.19422388 385 | ], 386 | [ 387 | -85.74272262, 388 | 38.19409396 389 | ], 390 | [ 391 | -85.7433496, 392 | 38.19373429 393 | ], 394 | [ 395 | -85.74295194, 396 | 38.1931255 397 | ], 398 | [ 399 | -85.74499434, 400 | 38.19218747 401 | ], 402 | [ 403 | -85.74529018, 404 | 38.19261876 405 | ], 406 | [ 407 | -85.74590449, 408 | 38.19237844 409 | ], 410 | [ 411 | -85.74613822, 412 | 38.19272709 413 | ], 414 | [ 415 | -85.74360243, 416 | 38.19390986 417 | ], 418 | [ 419 | -85.74416041, 420 | 38.19496956 421 | ], 422 | [ 423 | -85.74363753, 424 | 38.19525042 425 | ], 426 | [ 427 | -85.74384167, 428 | 38.19562925 429 | ], 430 | [ 431 | -85.74484092, 432 | 38.19611113 433 | ], 434 | [ 435 | -85.74556494, 436 | 38.19642966 437 | ], 438 | [ 439 | -85.74606584, 440 | 38.1965484 441 | ], 442 | [ 443 | -85.74714363, 444 | 38.19680874 445 | ], 446 | [ 447 | -85.74820621, 448 | 38.1970633 449 | ], 450 | [ 451 | -85.74843383, 452 | 38.19711402 453 | ], 454 | [ 455 | -85.74885653, 456 | 38.19710263 457 | ], 458 | [ 459 | -85.74918168, 460 | 38.1971223 461 | ], 462 | [ 463 | -85.74947738, 464 | 38.1971781 465 | ], 466 | [ 467 | -85.74990241, 468 | 38.19727992 469 | ], 470 | [ 471 | -85.75003869, 472 | 38.19729605 473 | ], 474 | [ 475 | -85.75005611, 476 | 38.20033544 477 | ], 478 | [ 479 | -85.74953855, 480 | 38.20050897 481 | ], 482 | [ 483 | -85.74872056, 484 | 38.20076384 485 | ], 486 | [ 487 | -85.74779783, 488 | 38.20106773 489 | ], 490 | [ 491 | -85.74701831, 492 | 38.20135785 493 | ], 494 | [ 495 | -85.74683261, 496 | 38.20150923 497 | ], 498 | [ 499 | -85.74678952, 500 | 38.20161707 501 | ], 502 | [ 503 | -85.74740365, 504 | 38.20356408 505 | ], 506 | [ 507 | -85.74765167, 508 | 38.20387082 509 | ], 510 | [ 511 | -85.74729548, 512 | 38.20417935 513 | ], 514 | [ 515 | -85.74708392, 516 | 38.2041761 517 | ], 518 | [ 519 | -85.74710166, 520 | 38.20467056 521 | ], 522 | [ 523 | -85.74974622, 524 | 38.20449714 525 | ], 526 | [ 527 | -85.7498448, 528 | 38.20634587 529 | ], 530 | [ 531 | -85.74985389, 532 | 38.20634694 533 | ] 534 | ] 535 | ] 536 | ] 537 | } 538 | } 539 | ] 540 | } -------------------------------------------------------------------------------- /geography/examples/no-ride-zone.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": "1.2.0", 3 | "geography": { 4 | "geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208", 5 | "geography_type": "no_ride_zone", 6 | "name": "No Ride Zones", 7 | "description": "Areas where vehicles are not allowed to be ridden", 8 | "effective_date": 1570034561834, 9 | "published_date": 1570035222868, 10 | "prev_geographies": [ 11 | "40d78c83-493f-40ad-8aba-a1ef036c5ffa" 12 | ], 13 | "geography_json": { 14 | "type": "FeatureCollection", 15 | "name": "no-ride-zone", 16 | "crs": { 17 | "type": "name", 18 | "properties": { 19 | "name": "urn:ogc:def:crs:OGC:1.3:CRS84" 20 | } 21 | }, 22 | "features": [ 23 | { 24 | "type": "Feature", 25 | "properties": { 26 | "FID": 1, 27 | "NAME": "American Printing House for the Blind", 28 | "SHAPE_Length": 0.008786699248095768, 29 | "SHAPE_Area": 2.4292961698961585e-06 30 | }, 31 | "geometry": { 32 | "type": "MultiPolygon", 33 | "coordinates": [ 34 | [ 35 | [ 36 | [ 37 | -85.71327111, 38 | 38.25848578 39 | ], 40 | [ 41 | -85.7145899, 42 | 38.25621372 43 | ], 44 | [ 45 | -85.71459281, 46 | 38.25621466 47 | ], 48 | [ 49 | -85.71522925, 50 | 38.25641957 51 | ], 52 | [ 53 | -85.7134008, 54 | 38.25956836 55 | ], 56 | [ 57 | -85.71269938, 58 | 38.25947038 59 | ], 60 | [ 61 | -85.71326986, 62 | 38.25848793 63 | ], 64 | [ 65 | -85.71327111, 66 | 38.25848578 67 | ] 68 | ] 69 | ] 70 | ] 71 | } 72 | }, 73 | { 74 | "type": "Feature", 75 | "properties": { 76 | "FID": 2, 77 | "NAME": "KY School for the Blind", 78 | "SHAPE_Length": 0.012435195555633537, 79 | "SHAPE_Area": 6.229622820920614e-06 80 | }, 81 | "geometry": { 82 | "type": "MultiPolygon", 83 | "coordinates": [ 84 | [ 85 | [ 86 | [ 87 | -85.71459281, 88 | 38.25621466 89 | ], 90 | [ 91 | -85.7145899, 92 | 38.25621372 93 | ], 94 | [ 95 | -85.71327111, 96 | 38.25848578 97 | ], 98 | [ 99 | -85.71227601, 100 | 38.25813677 101 | ], 102 | [ 103 | -85.71204161, 104 | 38.25855033 105 | ], 106 | [ 107 | -85.71159414, 108 | 38.2593398 109 | ], 110 | [ 111 | -85.71075294, 112 | 38.25941936 113 | ], 114 | [ 115 | -85.71075293, 116 | 38.25941881 117 | ], 118 | [ 119 | -85.71056428, 120 | 38.25943936 121 | ], 122 | [ 123 | -85.71074694, 124 | 38.25912091 125 | ], 126 | [ 127 | -85.71074692, 128 | 38.25911986 129 | ], 130 | [ 131 | -85.71200893, 132 | 38.25692731 133 | ], 134 | [ 135 | -85.71275985, 136 | 38.25562265 137 | ], 138 | [ 139 | -85.71459402, 140 | 38.25621258 141 | ], 142 | [ 143 | -85.71459281, 144 | 38.25621466 145 | ] 146 | ] 147 | ] 148 | ] 149 | } 150 | }, 151 | { 152 | "type": "Feature", 153 | "properties": { 154 | "FID": 6, 155 | "NAME": "Louisville Extreme Park", 156 | "SHAPE_Length": 0.003190486845852509, 157 | "SHAPE_Area": 5.84308612752141e-07 158 | }, 159 | "geometry": { 160 | "type": "MultiPolygon", 161 | "coordinates": [ 162 | [ 163 | [ 164 | [ 165 | -85.74076188, 166 | 38.25675413 167 | ], 168 | [ 169 | -85.74033647, 170 | 38.25746045 171 | ], 172 | [ 173 | -85.74026824, 174 | 38.2574506 175 | ], 176 | [ 177 | -85.74017398, 178 | 38.25749829 179 | ], 180 | [ 181 | -85.73970603, 182 | 38.25745777 183 | ], 184 | [ 185 | -85.73966427, 186 | 38.25741181 187 | ], 188 | [ 189 | -85.7397857, 190 | 38.25692035 191 | ], 192 | [ 193 | -85.73989459, 194 | 38.25692254 195 | ], 196 | [ 197 | -85.73997195, 198 | 38.25671414 199 | ], 200 | [ 201 | -85.74016274, 202 | 38.25672959 203 | ], 204 | [ 205 | -85.74017108, 206 | 38.25669372 207 | ], 208 | [ 209 | -85.74076188, 210 | 38.25675413 211 | ] 212 | ] 213 | ] 214 | ] 215 | } 216 | }, 217 | { 218 | "type": "Feature", 219 | "properties": { 220 | "FID": 9, 221 | "NAME": "Kentucky Exposition Center", 222 | "SHAPE_Length": 0.06213523936093914, 223 | "SHAPE_Area": 0.00012913879497045022 224 | }, 225 | "geometry": { 226 | "type": "MultiPolygon", 227 | "coordinates": [ 228 | [ 229 | [ 230 | [ 231 | -85.74985389, 232 | 38.20634694 233 | ], 234 | [ 235 | -85.74935347, 236 | 38.20640105 237 | ], 238 | [ 239 | -85.74876787, 240 | 38.20642765 241 | ], 242 | [ 243 | -85.74815792, 244 | 38.20644501 245 | ], 246 | [ 247 | -85.74740824, 248 | 38.20642603 249 | ], 250 | [ 251 | -85.7467669, 252 | 38.20638657 253 | ], 254 | [ 255 | -85.74596683, 256 | 38.20626809 257 | ], 258 | [ 259 | -85.74512329, 260 | 38.20609295 261 | ], 262 | [ 263 | -85.74447931, 264 | 38.20592478 265 | ], 266 | [ 267 | -85.74395635, 268 | 38.20576459 269 | ], 270 | [ 271 | -85.7434141, 272 | 38.20554744 273 | ], 274 | [ 275 | -85.74265757, 276 | 38.20519474 277 | ], 278 | [ 279 | -85.74155182, 280 | 38.20460811 281 | ], 282 | [ 283 | -85.74098444, 284 | 38.20434358 285 | ], 286 | [ 287 | -85.73978801, 288 | 38.20375332 289 | ], 290 | [ 291 | -85.73877965, 292 | 38.20319879 293 | ], 294 | [ 295 | -85.73724097, 296 | 38.20241738 297 | ], 298 | [ 299 | -85.73683058, 300 | 38.20214607 301 | ], 302 | [ 303 | -85.73636457, 304 | 38.20181348 305 | ], 306 | [ 307 | -85.73594015, 308 | 38.20144697 309 | ], 310 | [ 311 | -85.73553913, 312 | 38.20104203 313 | ], 314 | [ 315 | -85.73513675, 316 | 38.20057035 317 | ], 318 | [ 319 | -85.73488646, 320 | 38.20014918 321 | ], 322 | [ 323 | -85.7346991, 324 | 38.19985118 325 | ], 326 | [ 327 | -85.73449626, 328 | 38.1993865 329 | ], 330 | [ 331 | -85.73431798, 332 | 38.19894057 333 | ], 334 | [ 335 | -85.73414389, 336 | 38.19810838 337 | ], 338 | [ 339 | -85.73408145, 340 | 38.19771343 341 | ], 342 | [ 343 | -85.73400692, 344 | 38.19731863 345 | ], 346 | [ 347 | -85.73397264, 348 | 38.19711881 349 | ], 350 | [ 351 | -85.73672593, 352 | 38.19584885 353 | ], 354 | [ 355 | -85.73890388, 356 | 38.19458974 357 | ], 358 | [ 359 | -85.74042529, 360 | 38.19365248 361 | ], 362 | [ 363 | -85.74065301, 364 | 38.19370917 365 | ], 366 | [ 367 | -85.74082205, 368 | 38.19385005 369 | ], 370 | [ 371 | -85.74090876, 372 | 38.19402774 373 | ], 374 | [ 375 | -85.7409581, 376 | 38.1942238 377 | ], 378 | [ 379 | -85.7410067, 380 | 38.1943841 381 | ], 382 | [ 383 | -85.74111595, 384 | 38.19455554 385 | ], 386 | [ 387 | -85.74127853, 388 | 38.19475014 389 | ], 390 | [ 391 | -85.74144574, 392 | 38.19480165 393 | ], 394 | [ 395 | -85.74281591, 396 | 38.19422388 397 | ], 398 | [ 399 | -85.74272262, 400 | 38.19409396 401 | ], 402 | [ 403 | -85.7433496, 404 | 38.19373429 405 | ], 406 | [ 407 | -85.74295194, 408 | 38.1931255 409 | ], 410 | [ 411 | -85.74499434, 412 | 38.19218747 413 | ], 414 | [ 415 | -85.74529018, 416 | 38.19261876 417 | ], 418 | [ 419 | -85.74590449, 420 | 38.19237844 421 | ], 422 | [ 423 | -85.74613822, 424 | 38.19272709 425 | ], 426 | [ 427 | -85.74360243, 428 | 38.19390986 429 | ], 430 | [ 431 | -85.74416041, 432 | 38.19496956 433 | ], 434 | [ 435 | -85.74363753, 436 | 38.19525042 437 | ], 438 | [ 439 | -85.74384167, 440 | 38.19562925 441 | ], 442 | [ 443 | -85.74484092, 444 | 38.19611113 445 | ], 446 | [ 447 | -85.74556494, 448 | 38.19642966 449 | ], 450 | [ 451 | -85.74606584, 452 | 38.1965484 453 | ], 454 | [ 455 | -85.74714363, 456 | 38.19680874 457 | ], 458 | [ 459 | -85.74820621, 460 | 38.1970633 461 | ], 462 | [ 463 | -85.74843383, 464 | 38.19711402 465 | ], 466 | [ 467 | -85.74885653, 468 | 38.19710263 469 | ], 470 | [ 471 | -85.74918168, 472 | 38.1971223 473 | ], 474 | [ 475 | -85.74947738, 476 | 38.1971781 477 | ], 478 | [ 479 | -85.74990241, 480 | 38.19727992 481 | ], 482 | [ 483 | -85.75003869, 484 | 38.19729605 485 | ], 486 | [ 487 | -85.75005611, 488 | 38.20033544 489 | ], 490 | [ 491 | -85.74953855, 492 | 38.20050897 493 | ], 494 | [ 495 | -85.74872056, 496 | 38.20076384 497 | ], 498 | [ 499 | -85.74779783, 500 | 38.20106773 501 | ], 502 | [ 503 | -85.74701831, 504 | 38.20135785 505 | ], 506 | [ 507 | -85.74683261, 508 | 38.20150923 509 | ], 510 | [ 511 | -85.74678952, 512 | 38.20161707 513 | ], 514 | [ 515 | -85.74740365, 516 | 38.20356408 517 | ], 518 | [ 519 | -85.74765167, 520 | 38.20387082 521 | ], 522 | [ 523 | -85.74729548, 524 | 38.20417935 525 | ], 526 | [ 527 | -85.74708392, 528 | 38.2041761 529 | ], 530 | [ 531 | -85.74710166, 532 | 38.20467056 533 | ], 534 | [ 535 | -85.74974622, 536 | 38.20449714 537 | ], 538 | [ 539 | -85.7498448, 540 | 38.20634587 541 | ], 542 | [ 543 | -85.74985389, 544 | 38.20634694 545 | ] 546 | ] 547 | ] 548 | ] 549 | } 550 | } 551 | ] 552 | } 553 | } 554 | } 555 | -------------------------------------------------------------------------------- /geography/examples/stop.geojson: -------------------------------------------------------------------------------- 1 | { 2 | "type": "FeatureCollection", 3 | "name": "stop", 4 | "crs": { 5 | "type": "name", 6 | "properties": { 7 | "name": "urn:ogc:def:crs:OGC:1.3:CRS84" 8 | } 9 | }, 10 | "features": [ 11 | { 12 | "type": "Feature", 13 | "properties": { 14 | "OBJECTID": 1 15 | }, 16 | "geometry": { 17 | "type": "Point", 18 | "coordinates": [ 19 | -85.72414507, 20 | 38.24042011 21 | ] 22 | } 23 | }, 24 | { 25 | "type": "Feature", 26 | "properties": { 27 | "OBJECTID": 2 28 | }, 29 | "geometry": { 30 | "type": "Point", 31 | "coordinates": [ 32 | -85.72437939, 33 | 38.24011916 34 | ] 35 | } 36 | }, 37 | { 38 | "type": "Feature", 39 | "properties": { 40 | "OBJECTID": 3 41 | }, 42 | "geometry": { 43 | "type": "Point", 44 | "coordinates": [ 45 | -85.72069195, 46 | 38.23832865 47 | ] 48 | } 49 | }, 50 | { 51 | "type": "Feature", 52 | "properties": { 53 | "OBJECTID": 4 54 | }, 55 | "geometry": { 56 | "type": "Point", 57 | "coordinates": [ 58 | -85.71587376, 59 | 38.23551889 60 | ] 61 | } 62 | }, 63 | { 64 | "type": "Feature", 65 | "properties": { 66 | "OBJECTID": 5 67 | }, 68 | "geometry": { 69 | "type": "Point", 70 | "coordinates": [ 71 | -85.70957051, 72 | 38.23219427 73 | ] 74 | } 75 | }, 76 | { 77 | "type": "Feature", 78 | "properties": { 79 | "OBJECTID": 6 80 | }, 81 | "geometry": { 82 | "type": "Point", 83 | "coordinates": [ 84 | -85.70925854, 85 | 38.23187126 86 | ] 87 | } 88 | }, 89 | { 90 | "type": "Feature", 91 | "properties": { 92 | "OBJECTID": 7 93 | }, 94 | "geometry": { 95 | "type": "Point", 96 | "coordinates": [ 97 | -85.70439811, 98 | 38.23076038 99 | ] 100 | } 101 | }, 102 | { 103 | "type": "Feature", 104 | "properties": { 105 | "OBJECTID": 8 106 | }, 107 | "geometry": { 108 | "type": "Point", 109 | "coordinates": [ 110 | -85.70500586, 111 | 38.23066181 112 | ] 113 | } 114 | }, 115 | { 116 | "type": "Feature", 117 | "properties": { 118 | "OBJECTID": 9 119 | }, 120 | "geometry": { 121 | "type": "Point", 122 | "coordinates": [ 123 | -85.69432105, 124 | 38.22454108 125 | ] 126 | } 127 | } 128 | ] 129 | } -------------------------------------------------------------------------------- /geography/examples/stop.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": "1.2.0", 3 | "geography": { 4 | "geography_id": "d1328cdb-92fe-4267-85e0-a9fe5653268e", 5 | "geography_type": "stop", 6 | "name": "Parking areas", 7 | "description": "Highlands area preferred parking locations", 8 | "effective_date": 1570034561834, 9 | "published_date": 1570035222868, 10 | "prev_geographies": [ 11 | "789f677f-38eb-4397-a2ec-eca3f5c2ccb7", 12 | "fa4a3d92-706b-4400-8f44-0170b2ad632b", 13 | "1d4587ae-5cc4-4950-9ac8-aec3f558dd39", 14 | "e8ed9fc7-f0e2-4117-ae7b-6607ff60c413" 15 | ], 16 | "geography_json": { 17 | "type": "FeatureCollection", 18 | "name": "stops", 19 | "crs": { 20 | "type": "name", 21 | "properties": { 22 | "name": "urn:ogc:def:crs:OGC:1.3:CRS84" 23 | } 24 | }, 25 | "features": [ 26 | { 27 | "type": "Feature", 28 | "properties": { 29 | "OBJECTID": 1 30 | }, 31 | "geometry": { 32 | "type": "Point", 33 | "coordinates": [ 34 | -85.72414507, 35 | 38.24042011 36 | ] 37 | } 38 | }, 39 | { 40 | "type": "Feature", 41 | "properties": { 42 | "OBJECTID": 2 43 | }, 44 | "geometry": { 45 | "type": "Point", 46 | "coordinates": [ 47 | -85.72437939, 48 | 38.24011916 49 | ] 50 | } 51 | }, 52 | { 53 | "type": "Feature", 54 | "properties": { 55 | "OBJECTID": 3 56 | }, 57 | "geometry": { 58 | "type": "Point", 59 | "coordinates": [ 60 | -85.72069195, 61 | 38.23832865 62 | ] 63 | } 64 | }, 65 | { 66 | "type": "Feature", 67 | "properties": { 68 | "OBJECTID": 4 69 | }, 70 | "geometry": { 71 | "type": "Point", 72 | "coordinates": [ 73 | -85.71587376, 74 | 38.23551889 75 | ] 76 | } 77 | }, 78 | { 79 | "type": "Feature", 80 | "properties": { 81 | "OBJECTID": 5 82 | }, 83 | "geometry": { 84 | "type": "Point", 85 | "coordinates": [ 86 | -85.70957051, 87 | 38.23219427 88 | ] 89 | } 90 | }, 91 | { 92 | "type": "Feature", 93 | "properties": { 94 | "OBJECTID": 6 95 | }, 96 | "geometry": { 97 | "type": "Point", 98 | "coordinates": [ 99 | -85.70925854, 100 | 38.23187126 101 | ] 102 | } 103 | }, 104 | { 105 | "type": "Feature", 106 | "properties": { 107 | "OBJECTID": 7 108 | }, 109 | "geometry": { 110 | "type": "Point", 111 | "coordinates": [ 112 | -85.70439811, 113 | 38.23076038 114 | ] 115 | } 116 | }, 117 | { 118 | "type": "Feature", 119 | "properties": { 120 | "OBJECTID": 8 121 | }, 122 | "geometry": { 123 | "type": "Point", 124 | "coordinates": [ 125 | -85.70500586, 126 | 38.23066181 127 | ] 128 | } 129 | }, 130 | { 131 | "type": "Feature", 132 | "properties": { 133 | "OBJECTID": 9 134 | }, 135 | "geometry": { 136 | "type": "Point", 137 | "coordinates": [ 138 | -85.69432105, 139 | 38.22454108 140 | ] 141 | } 142 | } 143 | ] 144 | } 145 | } 146 | } 147 | -------------------------------------------------------------------------------- /jurisdiction/README.md: -------------------------------------------------------------------------------- 1 | # Mobility Data Specification: Jurisdiction 2 | 3 | MDS Jurisdiction Icon 4 | 5 | This specification details the purpose, use cases, and schema for Jurisdictions. Jurisdictions are an optional service that are served by a coordinated group of agencies. Jurisdictions should be unauthenticated and public. Note that Jurisdictions serves a different purpose from the [Geography](/geography) API, though it does reference areas within Geography by ID. 6 | 7 | ## Table of Contents 8 | 9 | - [Background](#background) 10 | - [Beta Feature](#beta-feature) 11 | - [Authorization](#authorization) 12 | - [Use Cases](#use-cases) 13 | - [Distribution](#distribution) 14 | - [Schema](#schema) 15 | - [REST Endpoints](#rest-endpoints) 16 | - [Get Jurisdictions](#get-jurisdictions) 17 | - [Get Jurisdiction](#get-jurisdiction) 18 | - [Flat Files](#flat-files) 19 | - [Examples](#examples) 20 | 21 | ## Background 22 | 23 | City and transportation agencies need to regulate mobility within their own jurisdictions. Within a collection of agencies under a single MDS software deployment, those agencies need to coordinate and share relevant data between one another when their jurisdictions overlap. 24 | 25 | The jurisdictions API helps to solve the following problems when implementing MDS in a multi-jurisdictional environment: 26 | 27 | - Giving agencies a mechanism to communicate boundaries between one another and to mobility providers. 28 | - Some agencies manage multiple overlapping jurisdictions and need a mechanism to administer scope and permissions to data. 29 | 30 | A jurisdiction is: 31 | 32 | - A representation of an agency’s authority to the outside world 33 | - Human-readable name 34 | - Uniquely identified 35 | - Purview to make rules over physical boundaries and modal boundaries (e.g. a jurisdiction could be for taxis only) 36 | - A way of tracking revisions in an agency's authority 37 | 38 | [Top][toc] 39 | 40 | ## Beta Feature 41 | 42 | The Jurisdictions API and all of its endpoints are marked as a [beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features) starting in the 1.1.0 release. It has not been tested in real world scenarios, and may be adjusted in future releases. 43 | 44 | **[Beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features)**: _Yes (as of 1.1.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/673) 45 | 46 | [Top][toc] 47 | 48 | ### Authorization 49 | 50 | This endpoint should be made public. Authorization is not required. 51 | 52 | [Top][toc] 53 | 54 | ## Use Cases 55 | 56 | ### 1. Defining boundaries and what the vehicle state `elsewhere` means 57 | 58 | For a single jurisdiction MDS deployment, a city designates a jurisdiction that providers can reference and know in what area to send events. When a trip leaves the LADOT jurisdiction, providers need to send an event with the vehicle state set to `elsewhere`. 59 | 60 | Cities and agencies contained within the MPO would internally be able filter for their own jurisdictional data. This would allow mobility providers to not need to send MDS data to multiple MDS instances. 61 | 62 | In addition, Agency authority have an explicit revision mechanism through a canonical API. 63 | 64 | ### 2. Clarifying overlapping authority 65 | 66 | Agencies and mobility providers would be able to understand agency authority in a geographical area and in what mobility mode through a list of jurisdictions.. 67 | 68 | Example: LADOT has jurisdictional authority over the city of Los Angeles for micromobility permitting, and jurisdictional authority over the county of Los Angeles for taxi permitting. 69 | 70 | ### 3. Access scoping 71 | 72 | Example: A SaaS company contracts with Miami-Dade County to provide MDS. There are 34 cities within the county. Miami-Dade County needs to assign permissions to each city to control who writes policy, based on jurisdictions. A Jurisdictions object with a stable identifier can be used for access control. 73 | 74 | ### 4. Agencies need to grant application access 75 | 76 | Example: The City of Miami has different data visualization tools from the city of Coral Gables 77 | Those tools can be granted data access from the SaaS tool based on the jurisdiction's stable identifier. 78 | 79 | [Top][toc] 80 | 81 | ## Distribution 82 | 83 | Jurisdictions can be served by agencies through the following REST API, or via [flat-files](#flat-files). See [Authorization](#authorization). 84 | 85 | [Top][toc] 86 | 87 | ## Schema 88 | 89 | See the [Endpoints](#endpoints) below for information on their specific schema, and the [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for full details and interactive documentation. 90 | 91 | A Jurisdiction optionally contains a reference to a Geography object. 92 | 93 | When a Jurisdiction is updated, the old version should remain in the back-end for archival purposes. 94 | 95 | An individual `Jurisdiction` object is defined by the following fields: 96 | 97 | | Name | Type | Required / Optional | Description | 98 | | ----------------- | --------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 99 | | `jurisdiction_id` | UUID | Required | Unique ID of Jurisdiction. This field is immutable. | 100 | | `agency_key` | String | Required | A unique string key for the Jurisdiction. This field must also be immutable. Allows for easier management of Jurisdiction-based access control in JWTs. | 101 | | `agency_name` | String | [Optional](../general-information.md#optional-fields) | Human-readable agency name for display purposes. | 102 | | `description` | String | Required | Description of Jurisdiction. | 103 | | `geography_id` | UUID | [Optional](../general-information.md#optional-fields) | The unique ID of the geography covered by this Jurisdiction. | 104 | | `mode_ids` | String[] | Required | Use this field to specify an array of what mobility [modes][modes] a jurisdiction applies to. | 105 | | `timestamp` | timestamp | Required | Creation or update time of a Jurisdiction. | 106 | 107 | Formatted in JSON, a Jurisdiction object should look like this: 108 | 109 | ``` 110 | { 111 | "jurisdiction_id": UUID, 112 | "agency_key": string, 113 | "agency_name": string, 114 | "geography_id": UUID, 115 | "mode_ids": [ 116 | string 117 | ], 118 | "timestamp": Timestamp 119 | } 120 | ``` 121 | [Top][toc] 122 | 123 | ## REST Endpoints 124 | 125 | ### Format 126 | 127 | All response fields must use `lower_case_with_underscores`. 128 | 129 | Responses must set the `Content-Type` header, as specified in the [Provider versioning](../provider/README.md#versioning) section. They must also specify the current API version being served in the JSON-formatted response body, under the `version` key. 130 | 131 | Response bodies must be a `UTF-8` encoded JSON object. 132 | 133 | [Top][toc] 134 | 135 | ### HTTP Response Codes 136 | 137 | The response to a client request must include a valid HTTP status code defined in the [IANA HTTP Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) 138 | 139 | [Top][toc] 140 | 141 | ### Get Jurisdictions 142 | 143 | Gets all of an agency's Jurisdictions. Served by agencies. 144 | 145 | **Endpoint:** `/jurisdictions/` 146 | **Method:** `GET` 147 | **[Beta feature][beta]:** _Yes (as of 1.1.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/673) 148 | **Schema:** [`jurisdiction` schema](#schema) 149 | **`data` Payload:** `{ "jurisdiction": [] }`, an array of [jurisdiction](#schema) objects 150 | 151 | _Query Parameters:_ 152 | 153 | | Query Parameters | Type | R/O | Description | 154 | | ------------ | --------- | --- | ---------------------------------------------- | 155 | | `effective` | Timestamp | O | See the state of all the Jurisdictions (i.e. which ones are effective) at that point in time. If not supplied, the default is to show only Jurisdictions that are currently in effect. | 156 | 157 | #### Responses 158 | 159 | _Possible HTTP Status Codes_: 160 | 200, 161 | 400 (with parameter), 162 | 404, 163 | 406, 164 | 500 165 | 166 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 167 | 168 | [Top][toc] 169 | 170 | ### GET Jurisdiction 171 | 172 | Gets a single Jurisdictions. Served by agencies. 173 | 174 | **Endpoint:** `/jurisdictions/{jurisdiction_id}` 175 | **Method:** `GET` 176 | **[Beta feature][beta]:** _Yes (as of 1.1.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/673) 177 | **Schema:** [`jurisdiction` schema](#schema) 178 | **`data` Payload:** `{ "jurisdiction": [] }`, an array of [jurisdiction](#schema) objects 179 | 180 | _Path Parameters:_ 181 | 182 | | Path Parameters | Type | R/O | Description | 183 | | ------------ | --------- | --- | ---------------------------------------------- | 184 | | `jurisdiction_id` | UUID | R | Single jurisdiction to return | 185 | 186 | _Query Parameters:_ 187 | 188 | | Query Parameters | Type | R/O | Description | 189 | | ------------ | --------- | --- | ---------------------------------------------- | 190 | | `effective` | Timestamp | O | See the version of the Jurisdiction that was in effect at that point in time. | 191 | 192 | #### Responses 193 | 194 | _Possible HTTP Status Codes_: 195 | 200, 196 | 400 (with parameter), 197 | 404, 198 | 406, 199 | 500 200 | 201 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 202 | 203 | [Top][toc] 204 | 205 | ## Flat Files 206 | 207 | To use flat files, Jurisdictions shall be represented in the following files: 208 | 209 | - `jurisdictions.json` 210 | - `geographies.json` 211 | 212 | The format and content of `jurisdictions.json` should resemble the responses from `GET /jurisdictions`. 213 | 214 | The publishing Agency should establish and communicate to interested parties how frequently these files should be polled. 215 | 216 | The `last_updated` field in the payload wrapper should be set to the time of publishing a revision, so that it is simple to identify a changed file. 217 | 218 | ### Responses 219 | 220 | _Possible HTTP Status Codes_: 221 | 200, 222 | 404, 223 | 406, 224 | 500 225 | 226 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 227 | 228 | [Top][toc] 229 | 230 | ## Examples 231 | 232 | See the [Jurisdiction Examples](examples/README.md) for a sample `jurisdictions.json` file. 233 | 234 | See the [Geography Examples](/geography/examples/README.md) for an example `geographies.json`. 235 | 236 | [Top][toc] 237 | 238 | [bulk-responses]: /general-information.md#bulk-responses 239 | [modes]: /modes#list-of-supported-modes 240 | [responses]: /general-information.md#responses 241 | [schema]: /schema/ 242 | [toc]: #table-of-contents 243 | -------------------------------------------------------------------------------- /jurisdiction/examples/README.md: -------------------------------------------------------------------------------- 1 | # Jurisdiction Examples 2 | 3 | This file presents an example of how to format a flat file, should an agency prefer to serve flat files instead of implementing a REST API. 4 | 5 | **`jurisdictions.json`** file: [`jurisdictions.json`](jurisdictions.json) 6 | 7 | ```js 8 | { 9 | "version": "1.2.0", 10 | "updated": "1570035222868", 11 | "end_date": "1570035222868", 12 | "jurisdictions": 13 | [ 14 | { 15 | "jurisdiction_id": "240edf69-9f2b-457c-accf-e8156e78811f", 16 | "agency_key": "miami-dade-county", 17 | "agency_name": "County of Miami-Dade", 18 | "mobility_modes": ["taxi"], 19 | "geography_id": "e95cb0f7-41eb-4bdd-8b1d-92b0593a7df1" 20 | }, 21 | { 22 | "jurisdiction_id": "3c71f367-7c7d-49c7-94d0-21b9e7259c1b", 23 | "agency_key": "miami", 24 | "agency_name": "City of Miami", 25 | "mobility_modes": ["micromobility"], 26 | "geography_id": "a3ddc3f6-b476-4784-bae7-f0141bb534f6" 27 | }, 28 | { 29 | "jurisdiction_id": "9fc51c56-9ac3-497a-b575-07097aa147cb", 30 | "agency_key": "coral-gables", 31 | "agency_name": "City of Coral Gables", 32 | "mobility_modes": [], 33 | "geography_id": "ad4b47d3-bb49-4122-ad19-5d517490baa6" 34 | } 35 | ] 36 | } 37 | ``` 38 | -------------------------------------------------------------------------------- /jurisdiction/examples/jurisdictions.json: -------------------------------------------------------------------------------- 1 | 2 | { 3 | "version": "1.2.0", 4 | "updated": "1570035222868", 5 | "end_date": "1570035222868", 6 | "jurisdictions": 7 | [ 8 | { 9 | "jurisdiction_id": "240edf69-9f2b-457c-accf-e8156e78811f", 10 | "agency_key": "miami-dade-county", 11 | "agency_name": "County of Miami-Dade", 12 | "mobility_modes": ["taxi"], 13 | "geography_id": "e95cb0f7-41eb-4bdd-8b1d-92b0593a7df1" 14 | }, 15 | { 16 | "jurisdiction_id": "3c71f367-7c7d-49c7-94d0-21b9e7259c1b", 17 | "agency_key": "miami", 18 | "agency_name": "City of Miami", 19 | "mobility_modes": ["micromobility"], 20 | "geography_id": "a3ddc3f6-b476-4784-bae7-f0141bb534f6" 21 | }, 22 | { 23 | "jurisdiction_id": "9fc51c56-9ac3-497a-b575-07097aa147cb", 24 | "agency_key": "coral-gables", 25 | "agency_name": "City of Coral Gables", 26 | "mobility_modes": [], 27 | "geography_id": "ad4b47d3-bb49-4122-ad19-5d517490baa6" 28 | } 29 | ] 30 | } 31 | -------------------------------------------------------------------------------- /metrics/README.md: -------------------------------------------------------------------------------- 1 | # Mobility Data Specification: Metrics 2 | 3 | MDS Metrics Icon 4 | 5 | The Metrics API endpoints are intended to be implemented by regulatory agencies, their third party appointed representatives, or city designated partners for requesting **historical** calculated [core metrics](core_metrics.md) and aggregations of MDS data. The Metrics API allows viewing of aggregate report data derived from some MDS endpoints that may be used for use cases like compliance, program effectiveness, and alignment on counts. The metrics [methodology](/metrics/metrics_methodology.md) definitions may be used by providers and third parties in their own calculations. 6 | 7 | [Metrics Examples](examples) are available with sample implementations. 8 | 9 | ## Table of Contents 10 | 11 | - [General Information](#general-information) 12 | - [Implementation](#implementation) 13 | - [Authorization](#authorization) 14 | - [Data Requirements](#data-requirements) 15 | - [Beta Feature](#beta-feature) 16 | - [Date and Time Format](#date-and-time-format) 17 | - [Data Schema](#data-schema) 18 | - [Data Redaction](#data-redaction) 19 | - [Metrics Discovery API](#metrics-discovery-api) 20 | - [Metrics Query API](#metrics-query-api) 21 | - [Examples](#examples) 22 | 23 | ## General Information 24 | 25 | Objectives: 26 | 27 | - Cities need a number of clearly defined best practice metrics for operating, measuring, and managing emerging micro mobility programs using MDS data. 28 | - There is currently no standard counting methodology that mobility providers and cities have agreed upon. This consequently causes friction when establishing a new mobility program and evaluating its impact. 29 | - Cities need to rely upon trusted data sources upon which to perform longer term studies on citizen impact. 30 | - Mobility providers would like consistent rules between each city deployment in order to make their operations more scalable. 31 | 32 | [Top][toc] 33 | 34 | ## Implementation 35 | 36 | Here are initial design use cases and scenarios for Metrics. 37 | 38 | ### Agencies 39 | 40 | **_Note:_** Metrics is designed to be served by agencies or their designated third parties. 41 | 42 | - Use Metrics to share aggregate data derived from disaggregated MDS feeds (e.g., Provider or Agency) with other city employees, city departments, vendors, trusted partners, and academic researchers, either via authenticated API access or extracted metrics data. 43 | - Share agency MDS calculations back to providers to reduce disagreements about compliance, allowing a shared understanding and alignment on billing, enforcement, and policy, using a well-defined [methodology](/metrics/metrics_methodology.md). 44 | - Generating data which could then be used to feed reports to the public. 45 | - For agency internal and external use in visualizations, analysis, or other applications. 46 | 47 | ### Third Parties 48 | 49 | **_Note:_** Metrics is not designed as a substitute for disaggregated data. See the [Data Requirements](#data-requirements) section for details. 50 | 51 | - Agencies may designate third party partners to implement Metrics on their behalf. 52 | - Aggregate MDS data consistently from providers and make metrics available to agencies or research partners. 53 | 54 | ### Providers 55 | 56 | **_Note:_** Metrics is not designed to be served by providers, only by agencies and their designated partners. 57 | 58 | - The Metrics [methodology](/metrics/metrics_methodology.md) definitions may be referenced and used by providers for consistency in their own MDS calculations. 59 | 60 | [Top][toc] 61 | 62 | ## Authorization 63 | 64 | ### For Agencies hosting the Metrics API 65 | 66 | MDS Metrics endpoint producers **SHALL** provide authorization for API endpoints via a bearer token based auth system. When making requests, the endpoints expect one of two scopes `metrics:read` or `metrics:read:provider` to be present as part of the `scope` claims in a [JSON Web Token](https://jwt.io/) (JWT) `access_token` in the `Authorization` header, in the form `Authorization: Bearer `. The token issuance, expiration and revocation policies are at the discretion of the agency. [JSON Web Token](/general-information.md#json-web-tokens) is the recommended format. 67 | 68 | If a client has a `metrics:read` scope, they are permitted to read _all_ metrics available via the Metrics API. 69 | 70 | If a client has a `metrics:read:provider` scope, they are only permitted to read metrics which pertain to a particular `provider_id` claim in the aforementioned [JWT](https://jwt.io/) `access_token`. 71 | 72 | Further scopes and requirements may be added at the discretion of the agency, depending on their particular access control needs. 73 | 74 | General authorization details are specified in the [Authorization section](/general-information.md#authorization) in MDS General Information. 75 | 76 | [Top][toc] 77 | 78 | ## Data Requirements 79 | 80 | The Metrics API does not replace required MDS Provider and Agency endpoints (e.g., [trips](/provider#trips), [events](/provider#events), [vehicles](/provider#vehicles), etc.) in any way. City regulators use disaggregated data access for policy, data validation, auditing, and operational needs, and the Metrics API is not designed to serve these purposes. 81 | 82 | Metrics may be a supplement for other more granular MDS data, and may be used to solve a few of a city's use cases and share with key partners. 83 | 84 | [Top][toc] 85 | 86 | ## Beta Feature 87 | 88 | **[Beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features)**: _Yes (as of 1.0.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/671) 89 | 90 | The Metrics API and all of its endpoints are marked as a [beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features). It has not been tested in real world scenarios, and may be adjusted in future releases. 91 | 92 | [Top][toc] 93 | 94 | ## Date and Time Format 95 | 96 | All dates and times (datetime) are [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted strings (YYYY-MM-DDTHHMM), with minute granularity supported and time zone (default UTC) or included offset. Dates and times may also be specified using a numeric *Unix epoch/timestamp* 97 | 98 | All interval durations (duration) are [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) duration format strings (e.g. PT15M, PT1H, P1D). 99 | 100 | [Top][toc] 101 | 102 | ## Data Schema 103 | 104 | See the [Endpoints](#endpoints) below for information on their specific schema, and the [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for full details and interactive documentation. 105 | 106 | [Top][toc] 107 | 108 | ## Data Redaction 109 | 110 | Some combinations of dimensions, filters, time, and geography may return a small count of trips, which could increase a privacy risk of re-identification. To correct for that, Metrics does not return data below a certain count of results. This data redaction is called k-anonymity, and the threshold is set at a k-value of 10. For more explanation of this methodology, see our [Data Redaction Guidance document](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Data-Redaction). 111 | 112 | **If the query returns fewer than `10` trips in a count, then that row's count value is returned as "-1".** Note "0" values are also returned as "-1" since the goal is to group both low and no count values together for privacy. 113 | 114 | The OMF suggests a k-value of 10 is an appropriate starting point for safe anonymization, absent analysis and a further decision from the agency. As Metrics is in [beta](#beta-feature), this value may be adjusted in future releases and/or may become dynamic to account for specific categories of use cases and users. To improve the specification and to inform future guidance, beta users are encouraged to share their feedback and questions about k-values on this [discussion thread](https://github.com/openmobilityfoundation/mobility-data-specification/discussions/622). 115 | 116 | The k-value being used is always returned in the Metrics Query API [response](/metrics#response-1) to provide important context for the data consumer on the data redaction that is occurring. 117 | 118 | Using k-anonymity will reduce, but not necessarily eliminate the risk that an individual could be re-identified in a dataset, and this data should still be treated as sensitive. This is just one part of good privacy protection practices, which you can read more about in our [MDS Privacy Guide for Cities](https://github.com/openmobilityfoundation/governance/blob/main/documents/OMF-MDS-Privacy-Guide-for-Cities.pdf). 119 | 120 | [Top][toc] 121 | 122 | ## Metrics Discovery API 123 | 124 | ### Method 125 | 126 | `GET /metrics` 127 | 128 | Returns a discovery response describing the supported metrics, times, intervals, dimensions and filters. 129 | 130 | ### Parameters 131 | 132 | None. 133 | 134 | ### Response 135 | 136 | | Name | Type | Required | Comments | 137 | | ------------------ | ---------- | -------- | --------------------------------------------------------------------------------------------------------- | 138 | | `metrics` | metric[] | Yes | List of supported metrics. | 139 | | `metric.measures` | string[] | Yes | List of measure names. [See metric names](core_metrics.md) | 140 | | `metric.since` | datetime | Yes | Earliest supported start date for fetching metrics.  Minute (MM) must be divisible by minimum `interval`. | 141 | | `metric.intervals` | duration[] | Yes | A list of interval durations in ascending order.  Minimum (first) interval duration is the default. | 142 | | `max_intervals` | integer | Yes | Maximum number intervals that can be returned. | 143 | | `dimensions` | string[] | Yes | List of supported dimensions. [See dimensions.](core_metrics.md#dimensions) | 144 | | `filters` | string[] | Yes | List of supported filters for metrics. [See filters.](core_metrics.md#filters) | 145 | 146 | ### Response Schema 147 | 148 | ```js 149 | { 150 | "metrics": [ 151 | { 152 | "measures": [string], 153 | "since": datetime, 154 | "intervals": [duration] 155 | } 156 | ], 157 | "max_intervals": number, 158 | "dimensions": [string], 159 | "filters": [string] 160 | } 161 | ``` 162 | 163 | ### Responses 164 | 165 | _Possible HTTP Status Codes_: 166 | 200, 167 | 404, 168 | 500 169 | 170 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 171 | 172 | ## Metrics Query API 173 | 174 | ### Method 175 | 176 | `POST /metrics` 177 | 178 | Supports querying one or more metrics with the following parameters. 179 | 180 | ### Parameters 181 | 182 | | Query Parameters | Type | Required | Comments | 183 | | --------------- | -------- | -------- | ------------------------------------------------------------------------------- | 184 | | `measures` | string[] | Yes | list of measures to return. [See metric names](core_metrics.md) | 185 | | `interval` | duration | Yes | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) duration for metrics intervals. | 186 | | `start_date` | datetime | Yes | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted start date or numeric timestamp to fetch metrics. | 187 | | `end_date` | datetime | No | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted end date or numeric timestamp to fetch metrics. | 188 | | `timezone` | timezone | No | TZ Database time zone name (default: "UTC") | 189 | | `dimensions` | string[] | No | List of dimension names. [See dimensions.](core_metrics.md#dimensions) | 190 | | `filters` | filter[] | No | Filters for metrics to return of format [See filters.](core_metrics.md#filters) | 191 | | `filter.name` | string | No | Name of filter (e.g. 'vehicle_type') | 192 | | `filter.values` | string[] | No | List of values to filter for (e.g ['car', 'moped']) | 193 | 194 | Note: If `timezone` is specified then `start_date`, `end_date`, and all _datetime_ column values will be 195 | converted to the specified time zone. If not, parameters will be converted to and the results will be 196 | displayed in UTC. If `start_date` is specified as a numeric _Unix timestamp_ then all _datetime_ column values will be 197 | displayed using numeric _Unix timestamp_ values as well. The `timezone` parameter is not allowed when using numeric 198 | _Unix timestamp_ values. 199 | 200 | Note: If `end_date` is specified, all intervals that *begin* between the specified `start_date` and the `end_date` *(inclusive)* are fetched. If `end_date` is not specified, only the interval that begins *on* the specified `start_date` is fetched. 201 | 202 | ### Response 203 | 204 | All named fields are required to be returned in response. Non-relevant values can be empty. 205 | 206 | | Name | Type | Comments | 207 | | -------------------- | ---------- | -------------------------------------------------------------------- | 208 | | `id` | uuid | Unique id for query | 209 | | `query.measures` | string[] | From request. | 210 | | `query.interval` | duration | From Request. | 211 | | `query.start_date` | datetime | From Request. | 212 | | `query.end_date` | datetime | From Request. | 213 | | `query.timezone` | timezone | From Request. | 214 | | `query.k_value` | integer | The k-anonymity value used in any [data redaction](#data-redaction). | 215 | | `query.dimensions` | string[] | From Request. | 216 | | `query.filters` | filter[] | From Request. | 217 | | `columns` | column[] | Array of column information | 218 | | `column.name` | string | Name of metric or dimension column. | 219 | | `column.column_type` | string | Type of column: `measure` or `dimension`. | 220 | | `column.data_type` | string | Data type of column: `datetime`, `string`, `integer`, `float`. | 221 | | `rows` | values[][] | Array of row arrays containing the dimension and metric values. | 222 | 223 | ### Response Schema 224 | 225 | ```js 226 | { 227 | "id": string, 228 | "query": { 229 | "measures": [string], 230 | "interval": duration, 231 | "start_date": datetime, 232 | "end_date": datetime, 233 | "dimensions": [string], 234 | "timezone": string, 235 | "k_value": 10, 236 | "filters": [ 237 | { 238 | "name": string, 239 | "values": [string] 240 | } 241 | ] 242 | }, 243 | "columns": [ 244 | { 245 | "name": string, 246 | "column_type": string, 247 | "data_type": string 248 | } 249 | ], 250 | "rows": [ 251 | [string | number] 252 | ] 253 | } 254 | ``` 255 | 256 | ### Responses 257 | 258 | _Possible HTTP Status Codes_: 259 | 200, 260 | 400 (with parameter), 261 | 404, 262 | 500 263 | 264 | See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. 265 | 266 | [Top][toc] 267 | 268 | ## Examples 269 | 270 | See the [Metrics Examples](examples) for ways these can be implemented. 271 | 272 | [Top][toc] 273 | 274 | [bulk-responses]: /general-information.md#bulk-responses 275 | [responses]: /general-information.md#responses 276 | [toc]: #table-of-contents 277 | [schema]: /schema/ 278 | -------------------------------------------------------------------------------- /metrics/core_metrics.md: -------------------------------------------------------------------------------- 1 | # MDS Core Metrics 2 | 3 | The core metrics are a set of defined, consistent MDS metrics definitions that provide building blocks for other MDS [metrics](/metrics), regardless of vehicle type. 4 | 5 | ## Table of Contents 6 | 7 | - [Metrics Definitions](#metrics-definitions) 8 | - [Dimensions](#dimensions) 9 | - [Filters](#filters) 10 | - [Other MDS Metrics](#other-mds-metrics) 11 | 12 | # Metrics Definitions 13 | 14 | The table below represents supported MDS core metrics and definition. All metrics are aggregated by time interval and geographic areas. This [document](metrics_methodology.md) provides methodologies and sample calculations of MDS metrics. 15 | 16 | | Number | Metric | Description | 17 | | ------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | 18 | | 1.1 | vehicles.[status].avg | The average number of vehicles in [MDS status](/agency#vehicle-events). | 19 | | 1.2 | vehicles.[status].min | The minimum number of vehicles in [MDS status](/agency#vehicle-events). | 20 | | 1.3 | vehicles.[status].max | The maximum number of vehicles in [MDS status](/agency#vehicle-events). | 21 | | 1.4 | vehicles.[status].duration.sum | The total duration (in seconds) vehicles spent in a specified [MDS status](/agency#vehicle-events). | 22 | | 1.5 | events.[event_type].count | The number of [MDS event type](/agency#vehicle-events) received. | 23 | | 1.6 | trips.[start_loc/end_loc].count | The number of trips aggregated by either the start or first enter, or end or final leave locations. | 24 | | 1.7 | trips.[start_loc/end_loc].duration.avg | The average trip duration (in seconds) aggregated by either the start or first enter, or end or final leave locations. | 25 | | 1.8 | trips.[start_loc/end_loc].duration.med | The median trip duration (in seconds) aggregated by either the start or first enter, or end or final leave locations. | 26 | | 1.9 | trips.[start_loc/end_loc].duration.std | The standard deviation trip duration (in seconds) aggregated by either the start or first enter, or end or final leave locations. | 27 | | 1.10 | trips.[start_loc/end_loc].duration.sum | The total sum of trip duration (in seconds) aggregated by either the start or first enter, or end or final leave locations. | 28 | | 1.11 | trips.[start_loc/end_loc].distance.avg | The average trip distance (in meters) aggregated by either the start or first enter, or end or final leave locations. | 29 | | 1.12 | trips.[start_loc/end_loc].distance.med | The median trip distance (in meters) aggregated by either the start or first enter, or end or final leave locations. | 30 | | 1.13 | trips.[start_loc/end_loc].distance.std | The standard deviation trip distance (in meters) aggregated by either the start or first enter, or end or final leave locations. | 31 | | 1.14 | trips.[start_loc/end_loc].distance.sum | The total sum of trip distance (in meters) aggregated by either the start or first enter, or end or final leave locations. | 32 | 33 | [Top][toc] 34 | 35 | ## Dimensions 36 | 37 | The following represent the suggested MDS core metric dimensions: 38 | 39 | | Dimension | Description | 40 | | ------------------ | --------------------------------------------------------------------------- | 41 | | provider_id | Transportation provider id issued by OMF and [tracked here](/providers.csv) | 42 | | geography_id | [MDS Geography](/geography) | 43 | | vehicle_type | [Vehicle Type](/agency#vehicle-type) defined by MDS | 44 | 45 | [Top][toc] 46 | 47 | ## Filters 48 | 49 | The following represent the suggested MDS core metric filters: 50 | 51 | | Filter | Description | 52 | | ------------------ | ------------------------------------------------------------------------------------------------- | 53 | | provider_id | Transportation provider id issued by OMF and [tracked here](/providers.csv) | 54 | | geography_id | [MDS Geography](/geography) | 55 | | geography_type | [MDS Geography Type](/geography#geography-type) e.g. census_block, jurisdiction, council_district | 56 | | vehicle_type | [Vehicle Type](/agency#vehicle-type) defined by MDS | 57 | 58 | [Top][toc] 59 | 60 | # Other MDS Metrics 61 | 62 | - [MDS Dockless Metrics](dockless_metrics.md) 63 | 64 | [Top][toc] 65 | 66 | [toc]: #table-of-contents 67 | -------------------------------------------------------------------------------- /metrics/dockless_metrics.md: -------------------------------------------------------------------------------- 1 | ## MDS Dockless Metrics 2 | 3 | MDS dockless metrics are a set of defined metrics and compound metrics useful for measuring dockless vehicle activity with MDS data. Dockless metrics measure vehicle activity when they are in the public right of way, which means vehicles were in either available, unavailable, reserved, or trip state. 4 | 5 | The table below represents supported MDS dockless metrics extension and definition. All metrics are aggregated by time interval and geographic areas. This [document](metrics_methodology.md) provides methodologies and sample calculations of MDS metrics. 6 | 7 | | No | Metric | Description | 8 | | ---- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | 9 | | 2.1 | dockless.deployed.avg | The average number of vehicles in the public right of way. | 10 | | 2.2 | dockless.deployed.avg.min | The minimum of the average number of vehicles in the public right of way. | 11 | | 2.3 | dockless.deployed.min | The minimum number of vehicles in the public right of way. | 12 | | 2.4 | dockless.deployed.avg.max | The maximum average number of vehicles in the public right of way. | 13 | | 2.5 | dockless.deployed.max | The maximum number of vehicles in the public right of way. | 14 | | 2.6 | dockless.active.avg | The average number of vehicles in the public right of way that have at least one trip during the interval, i.e. hourly. | 15 | | 2.7 | dockless.inactive.avg | The average number of vehicles in the public right of way that have no trip during the interval. | 16 | | 2.8 | dockless.utilization.idle.percent | The percentage of time vehicles spent not in trip to the total time vehicles spent in the public right of way. | 17 | | 2.9 | dockless.utilization.active.percent | The percentage of vehicles that had at least one trip during the interval. | 18 | | 2.10 | dockless.utilization.trips_per_vehicle.avg | The average number of trips for all vehicles in the public right of way during the interval. | 19 | -------------------------------------------------------------------------------- /metrics/examples/README.md: -------------------------------------------------------------------------------- 1 | # Metrics Examples 2 | 3 | This file represents a series of examples of [Metrics](/metrics) to use as templates. 4 | 5 | ## Table of Contents 6 | 7 | - [Metrics Discovery API](metrics-discovery-api) 8 | - [Metrics Query API](metrics-query-api) 9 | 10 | ## Metrics Discovery API 11 | 12 | Returns a discovery response describing the supported metrics, times, intervals, dimensions and filters. 13 | 14 | #### Request 15 | 16 | ```js 17 | GET /metrics 18 | ``` 19 | 20 | #### Response 21 | 22 | ```json 23 | { 24 | "metrics": [ 25 | { 26 | "measures": ["dockless.deployed.avg"], 27 | "since": "2019-01-01T00:00-07", 28 | "intervals": ["PT1H"] 29 | }, 30 | { 31 | "measures": ["vehicles.available.count", "trips.end_loc.count"], 32 | "since": "2018-01-01T00:00-07", 33 | "intervals": ["PT15M", "PT1H", "P1D"] 34 | } 35 | ], 36 | "max_intervals": 10000, 37 | "dimensions": [ 38 | "provider_id", 39 | "vehicle_type", 40 | "geography_id" 41 | ], 42 | "filters": [ 43 | "provider_id", 44 | "vehicle_type", 45 | "geography_type", 46 | "geography_id" 47 | ] 48 | } 49 | ``` 50 | 51 | ## Metrics Query API 52 | 53 | ### Example: Activities 54 | 55 | This metrics will pull daily vehicle deployment and the number of trips made by each vehicle type for all providers. 56 | 57 | File: [`activities.json`](activities.json) (request) 58 | 59 | File: [`activities_response.json`](activities_response.json) (response) 60 | 61 | #### Request 62 | 63 | ```js 64 | POST /metrics 65 | { 66 | "measures": ["dockless.deployed.avg","trips.end_loc.count"], 67 | "interval": "P1D", 68 | "start_date": "2019-10-21T00:00-07", 69 | "end_date": "2019-10-28T00:00-07", 70 | "dimensions": ["geography_id", "vehicle_type"], 71 | "filters": [ 72 | { 73 | "name": "geography_type", 74 | "values": ["census_block"] 75 | } 76 | ] 77 | } 78 | ``` 79 | 80 | #### Reponse 81 | 82 | ```json 83 | { 84 | "id": "44428624-186b-4fc3-a7fb-124f487464a1", 85 | "query": { 86 | "measures": [ 87 | "dockless.deployed.avg", 88 | "trips.end_loc.count" 89 | ], 90 | "interval": "P1D", 91 | "start_date": "2019-10-21T00:00-07", 92 | "end_date": "2019-10-28T00:00-07", 93 | "dimensions": ["vehicle_type"], 94 | "timezone": "UTC", 95 | "k_value": 10, 96 | "filters": [] 97 | }, 98 | "columns": [ 99 | { 100 | "name": "interval_start", 101 | "column_type": "dimension", 102 | "data_type": "datetime" 103 | }, 104 | { 105 | "name": "geography_id", 106 | "column_type": "dimension", 107 | "data_type": "uuid" 108 | }, 109 | { 110 | "name": "vehicle_type", 111 | "column_type": "dimension", 112 | "data_type": "string" 113 | }, 114 | { 115 | "name": "dockless.deployed.avg", 116 | "column_type": "measure", 117 | "data_type": "float" 118 | }, 119 | { 120 | "name": "trips.end_loc.count", 121 | "column_type": "measure", 122 | "data_type": "integer" 123 | } 124 | ], 125 | "rows": [ 126 | ["2019-10-21T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 456.12, 69], 127 | ["2019-10-22T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 235.23, 114], 128 | ["2019-10-23T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 124.13, 46], 129 | ["2019-10-24T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 123.45, 36], 130 | ["2019-10-25T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 223.56, -1], 131 | ["2019-10-26T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 1981.89, 10967], 132 | ["2019-10-27T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 4562.55, 25271], 133 | ["2019-10-21T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 456.12, 69], 134 | ["2019-10-22T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 235.23, 114], 135 | ["2019-10-23T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 124.13, 46], 136 | ["2019-10-24T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 123.45, 36], 137 | ["2019-10-25T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 223.56, -1], 138 | ["2019-10-26T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 1981.89, 10967], 139 | ["2019-10-27T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 4562.55, 25271], 140 | ["2019-10-21T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 456.12, 69], 141 | ["2019-10-22T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 235.23, 114], 142 | ["2019-10-23T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 124.13, 46], 143 | ["2019-10-24T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 123.45, 36], 144 | ["2019-10-25T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 223.56, -1], 145 | ["2019-10-26T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 1981.89, 10967], 146 | ["2019-10-27T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 4562.55, 25271], 147 | ["2019-10-21T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 456.12, 69], 148 | ["2019-10-22T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 235.23, 114], 149 | ["2019-10-23T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 124.13, 46], 150 | ["2019-10-24T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 123.45, 36], 151 | ["2019-10-25T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 223.56, -1], 152 | ["2019-10-26T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 1981.89, 10967], 153 | ["2019-10-27T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 4562.55, 25271] 154 | ] 155 | } 156 | ``` 157 | -------------------------------------------------------------------------------- /metrics/examples/activities.json: -------------------------------------------------------------------------------- 1 | { 2 | "measures": ["dockless.deployed.avg","trips.end_loc.count"], 3 | "interval": "P1D", 4 | "start_date": "2019-10-21T00:00-07", 5 | "end_date": "2019-10-28T00:00-07", 6 | "dimensions": ["geography_id", "vehicle_type"], 7 | "filters": [ 8 | { 9 | "name": "geography_type", 10 | "values": ["census_block"] 11 | } 12 | ] 13 | } -------------------------------------------------------------------------------- /metrics/examples/activities_response.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "44428624-186b-4fc3-a7fb-124f487464a1", 3 | "query": { 4 | "measures": [ 5 | "dockless.deployed.avg", 6 | "trips.end_loc.count" 7 | ], 8 | "interval": "P1D", 9 | "start_date": "2019-10-21T00:00-07", 10 | "end_date": "2019-10-28T00:00-07", 11 | "dimensions": ["vehicle_type"], 12 | "timezone": "UTC", 13 | "k_value": 10, 14 | "filters": [] 15 | }, 16 | "columns": [ 17 | { 18 | "name": "interval_start", 19 | "column_type": "dimension", 20 | "data_type": "datetime" 21 | }, 22 | { 23 | "name": "geography_id", 24 | "column_type": "dimension", 25 | "data_type": "uuid" 26 | }, 27 | { 28 | "name": "vehicle_type", 29 | "column_type": "dimension", 30 | "data_type": "string" 31 | }, 32 | { 33 | "name": "dockless.deployed.avg", 34 | "column_type": "measure", 35 | "data_type": "float" 36 | }, 37 | { 38 | "name": "trips.end_loc.count", 39 | "column_type": "measure", 40 | "data_type": "integer" 41 | } 42 | ], 43 | "rows": [ 44 | ["2019-10-21T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 456.12, 69], 45 | ["2019-10-22T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 235.23, 114], 46 | ["2019-10-23T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 124.13, 46], 47 | ["2019-10-24T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 123.45, 36], 48 | ["2019-10-25T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 223.56, -1], 49 | ["2019-10-26T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 1981.89, 10967], 50 | ["2019-10-27T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "bicycle", 4562.55, 25271], 51 | ["2019-10-21T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 456.12, 69], 52 | ["2019-10-22T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 235.23, 114], 53 | ["2019-10-23T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 124.13, 46], 54 | ["2019-10-24T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 123.45, 36], 55 | ["2019-10-25T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 223.56, -1], 56 | ["2019-10-26T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 1981.89, 10967], 57 | ["2019-10-27T00:00-07", "03db06d0-3998-406a-92c7-25a83fc2784a", "scooter", 4562.55, 25271], 58 | ["2019-10-21T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 456.12, 69], 59 | ["2019-10-22T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 235.23, 114], 60 | ["2019-10-23T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 124.13, 46], 61 | ["2019-10-24T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 123.45, 36], 62 | ["2019-10-25T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 223.56, -1], 63 | ["2019-10-26T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 1981.89, 10967], 64 | ["2019-10-27T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "bicycle", 4562.55, 25271], 65 | ["2019-10-21T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 456.12, 69], 66 | ["2019-10-22T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 235.23, 114], 67 | ["2019-10-23T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 124.13, 46], 68 | ["2019-10-24T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 123.45, 36], 69 | ["2019-10-25T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 223.56, -1], 70 | ["2019-10-26T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 1981.89, 10967], 71 | ["2019-10-27T00:00-07", "2b697fb4-5935-4d4a-88ea-0745e1ea9b29", "scooter", 4562.55, 25271] 72 | ] 73 | } -------------------------------------------------------------------------------- /modes/README.md: -------------------------------------------------------------------------------- 1 | # Mobility Data Specification: **Modes** 2 | 3 | This directory contains descriptions of the different mobility modes that can be described by the Mobility Data Specification. It contains a list of all defined vehicle states and event types, as well as mode-specific state-machines, unique mode properties and attributes. 4 | 5 | All MDS APIs should be mode-agnostic. 6 | 7 | ## Table of Contents 8 | 9 | - [Modes](#modes) 10 | - [Provider ID](#provider-id) 11 | - [List of Supported Modes](#list-of-supported-modes) 12 | - [Mode Attributes](#mode-attributes) 13 | - [Mode Properties](#mode-properties) 14 | 15 | ## Modes 16 | 17 | The `mode` value is used to specify the applicable mobility category in MDS Policy, Provider/Agency, and many other parts of MDS. 18 | 19 | A `mode` is defined as: A distinct regulatory framework for a type of mobility service or program, as distinguished by a combination of: 20 | 21 | 1. the data needed by regulators, 22 | 1. the operating rules under which the service functions, 23 | 1. the legal authority under which it is regulated, and 24 | 1. the design and operating model of the service itself. 25 | 26 | There will be some gray areas and some differences from one jurisdiction to another (e.g. taxis and ridehail may be regulated under the same rules on one place, but different rules in another). MDS will not pre-define a complete taxonomy of modes, or identify every modal boundary upfront, but will instead add modes on an as-needed basis, maintaining as much consistency of naming as possible. 27 | 28 | We err on the side of treating highly similar services as one mode, but consult with our members and community to inform each decision about how to integrate a new service and whether it needs to be designated as its own mode. This is a policy implementation question as much as it is a technical one. 29 | 30 | Each mode defined in MDS shall include key descriptive information, such as journey type (e.g. point-to-point, multi-segment, multi-segment overlapping), primary purpose (goods, single passenger, multi-passenger, etc.), and a description of the service being offered that aligns with terminology commonly understood by the public (e.g. “e-scooter” or “ridehailing”). 31 | 32 | [Top][toc] 33 | 34 | ### Provider ID 35 | 36 | MDS is intended to be used for multiple transportation modes, including its original micromobility (e-scooters, bikes, etc.) mode, as well as additional modes such as taxis, car share, and delivery bots. A given `provider_id` shall be associated with a single mobility mode, so that the mode does not have to be specified in each data structure and API call. A provider implementing more than one mode shall [register](/README.md#providers-using-mds) a unique `provider_id` for each mode. 37 | 38 | [Top][toc] 39 | 40 | ## List of Supported Modes 41 | 42 | - **[Micromobility](/modes/micromobility.md)** (`micromobility`) - dockless or docked small devices such as e-scooters and bikes. 43 | - **[Passenger services](/modes/passenger-services.md)** (`passenger-services`) - transporting individuals with a vehicle driven by another entity, including taxis, TNCs, and microtransit 44 | - **[Car share](/modes/car-share.md)** (`car-share`) - shared point-to-point and station-based multi-passenger vehicles. 45 | - **[Delivery robots](/modes/delivery-robots.md)** (`delivery-robots`) - autonomous and remotely driven goods delivery devices 46 | 47 |

48 | MDS Mode - Micromobility       49 | MDS Mode - Passenger Services       50 | MDS Mode - Car Share       51 | MDS Mode - Delivery Robots 52 |

53 |
54 | 55 | [Top][toc] 56 | 57 | ## Mode Attributes 58 | 59 | Some fields used across MDS APIs are defined in more detail within each mode. 60 | 61 | ### Journey ID 62 | 63 | The `journey_id` field allows multiple trip segments to be referentially linked together. See each [mode definition](#list-of-supported-modes) for details. 64 | 65 | ### Journey Attributes 66 | 67 | The `journey_attributes` object allows additional mode-specific information about the nature of a journey to be described. See each [mode definition](#list-of-supported-modes) for details. 68 | 69 | ### Trip Type 70 | 71 | The `trip_type` field allows the purpose of each trip segment to be described. See each [mode definition](#list-of-supported-modes) for details. 72 | 73 | ### Trip Attributes 74 | 75 | The `trip_attributes` object allows additional mode-specific information about the nature of a trip to be described. It can return a list of JSON-formatted key/value pairs which correspond to the allowed attributes and values for the operative mode. See each [mode definition](#list-of-supported-modes) for details. 76 | 77 | _See more available trip attributes for any mode in the [trips object](/data-types.md#trips)._ 78 | 79 | ### Fare Attributes 80 | 81 | The `fare_attributes` object allows additional mode-specific information about fare information associated with the trip. It can return a list of JSON-formatted key/value pairs which correspond to the allowed attributes and values for the operative mode. See each [mode definition](#list-of-supported-modes) for details. 82 | 83 | _See more available fare attributes for any mode in the [trips object](/data-types.md#trips)._ 84 | 85 | ### Vehicle Attributes 86 | 87 | The `vehicle_attributes` object returns a list of JSON-formatted key/value pairs which correspond to the allowed attributes and values for the operative mode. For each mode, the allowed attributes and corresponding values are defined in the [mode definition](#list-of-supported-modes). 88 | 89 | _See more available vehicle attributes for any mode in the [vehicles object](/data-types.md#vehicles)._ 90 | 91 | ### Accessibility Attributes 92 | 93 | The `accessibility_attributes` object returns a list of JSON-formatted key/value pairs which correspond to the allowed accessibility attributes and values for the operative mode. For each mode, the allowed attributes and corresponding values are defined in the [mode definition](#list-of-supported-modes). 94 | 95 | [Top][toc] 96 | 97 | ## Mode Properties 98 | 99 | While each mode is unique in its operational and business models, there are several areas where there are significant differences from one mode to the next. Each of these areas is defined in more detail within the mode, and each pull from a base of options defined in a central location. 100 | 101 | ### Vehicle States 102 | 103 | Vehicle states are used to define the disposition of individual vehicles and fleets of vehicles. See [vehicle states](/modes/vehicle_states.md) for a list of possible values, and each [mode definition](#list-of-supported-modes) for details about which are used per mode. 104 | 105 | ### Event Types 106 | 107 | Event types are the possible transitions between vehicle states. See [event types](/modes/event_types.md) for a list of possible values, and each [mode definition](#list-of-supported-modes) for details about which are used per mode. 108 | 109 | ### State Transitions 110 | 111 | Possible combinations of how the `vehicle_state` changes in response to each `event_type`. See each [mode definition](#list-of-supported-modes) for a table of possible transition combinations. 112 | 113 | ### State Machine Diagram 114 | 115 | The State Machine Diagram visually shows the state transitions. See each [mode definition](#list-of-supported-modes) for a diagram. 116 | 117 | [Top][toc] 118 | 119 | --- 120 | 121 | [MDS Home][home] 122 | 123 | [home]: /README.md 124 | [modes]: /modes/README.md 125 | [micromobility]: /modes/micromobility.md 126 | [toc]: #table-of-contents 127 | -------------------------------------------------------------------------------- /modes/event_types.md: -------------------------------------------------------------------------------- 1 | # Mobility Data Specification: **Event Types** 2 | 3 | This file defines all possible `event_type`s that can be used in state machines across all MDS modes. Each mode will use some subset of these events. See individual [mode definitions](/modes#list-of-supported-modes) for additional details specific to that mode. 4 | 5 | As with all MDS definitions, they should be described in a way that maximizes their relevance to multiple modes whenever possible. 6 | 7 | | `event_type` | Description | 8 | | ------------------------- | ----------------------------------------------------------------------------------------------- | 9 | | `agency_drop_off` | Drop off by the agency | 10 | | `agency_pick_up` | Pick up by the agency, e.g. impound | 11 | | `battery_charged` | Battery charged (entering service) | 12 | | `battery_low` | Battery low (exiting service) | 13 | | `changed_geographies` | Geography change per [Geography Driven Events](/general-information.md#geography-driven-events) | 14 | | `charging_start` | Battery start charging | 15 | | `charging_end` | Battery end charging | 16 | | `comms_lost` | Communications lost | 17 | | `comms_restored` | Communications restored | 18 | | `compliance_pick_up` | Pick up for compliance (rule violation) | 19 | | `customer_cancellation` | Customer cancelled a trip | 20 | | `decommissioned` | Decommissioned | 21 | | `driver_cancellation` | Driver cancelled a trip | 22 | | `fueling_start` | Fueling starts | 23 | | `fueling_end` | Fueling ends | 24 | | `located` | Location found (opposite of Missing) | 25 | | `maintenance` | Start general maintenance in right of way | 26 | | `maintenance_pick_up` | Start pick up for maintenance outside of right of way | 27 | | `maintenance_end` | End of maintenance | 28 | | `not_located` | Location unknown | 29 | | `off_hours` | Off hours - end of service | 30 | | `on_hours` | On hours - start of service | 31 | | `order_drop_off` | Pick up of the order at business | 32 | | `order_pick_up` | Delivery of the order at the customer location | 33 | | `passenger_cancellation` | Passenger cancelled a trip | 34 | | `provider_cancellation` | Provider cancelled a trip | 35 | | `provider_drop_off` | Drop off by the provider | 36 | | `rebalance_pick_up` | Pick up for rebalancing | 37 | | `recommission` | Recommissioned | 38 | | `remote_start` | Remotely start the engine | 39 | | `remote_end` | Remotely stop the engine | 40 | | `reservation_cancel` | Reservation cancelled before trip | 41 | | `reservation_start` | Reservation started | 42 | | `reservation_stop` | Reservation stopped temporarily | 43 | | `service_end` | End of service | 44 | | `system_start` | Start of service | 45 | | `system_resume` | Resume system operations, e.g. start of day | 46 | | `system_suspend` | Suspend system operations, e.g. end of day | 47 | | `trip_cancel` | Cancel trip | 48 | | `trip_end` | End trip | 49 | | `trip_enter_jurisdiction` | Trip enters a jurisdiction | 50 | | `trip_leave_jurisdiction` | Trip leaves a jurisdiction | 51 | | `trip_pause` | Pause trip temporarily but do not end trip | 52 | | `trip_resume` | Resume trip | 53 | | `trip_start` | Start trip | 54 | | `trip_stop` | Stop trip | 55 | | `unspecified` | Unspecified | 56 | 57 | ### Limitations on the Use of Certain Values 58 | 59 | MDS is intended to communicate the provider's best available information to regulators. However there may be legitimate circumstances where providers do not have definitive or current information about devices on the ground. MDS incorporates some values to convey these situations. These vehicle state and event type values are to be used sparingly and temporarily, and are not meant for repeated or prolonged use. These values exist to create logical coherence within MDS about vehicles that are operating abnormally or are out of communication. When a more accurate value is known, the MDS API should be updated with the latest information. Cities may add language to their Service Level Agreements (SLAs) that minimize the use of these values by providers. 60 | 61 | #### Event Type: Unspecified 62 | 63 | The `unspecified` event type state transition means that the vehicle has moved from one state to another for an unspecified or unknown reason. It is used when there are multiple possible event types between states, but the reason for the transition is not clear. It is expected that `unspecified` will not be used frequently, and only for short periods of time. Cities may put in place specific limitations via an SLA. When more accurate information becomes available to the provider, it should be updated in the MDS data by sending a new event type state transition with the current timestamp. 64 | 65 | --- 66 | 67 | [Modes Overview][modes] 68 | 69 | --- 70 | 71 | [MDS Home][home] 72 | 73 | [home]: /README.md 74 | [modes]: /modes/README.md 75 | -------------------------------------------------------------------------------- /modes/vehicle_states.md: -------------------------------------------------------------------------------- 1 | # Mobility Data Specification: **Vehicle States** 2 | 3 | This file defines all possible `vehicle_state`s that can be used in state machines across all MDS modes. Each mode will use some subset of these states. It does not assign states to modes, but simply lists all possible values. As with all global definitions, they are described in a way that maximizes their relevance to multiple modes. See individual [mode definitions](/modes#list-of-supported-modes) for additional details specific to that mode. 4 | 5 | | `vehicle_state` | In PROW? | Description | 6 | | ----------------- | -------- | ----------- | 7 | | `removed` | no | Examples include: at the Provider's warehouse, in a Provider's truck, or destroyed and in a landfill. | 8 | | `available` | yes | Available for rental via the Provider's app. | 9 | | `non_operational` | yes | Not available for hire. Examples include: vehicle has low battery, or currently outside legal operating hours. | 10 | | `reserved` | yes | Reserved via Provider's app. A scooter waiting to be picked up by a rider, a taxi en route to a pickup. | 11 | | `on_trip` | yes | In a trip. For micromobility, in possession of renter. May or may not be in motion. | 12 | | `stopped` | yes | In a trip, but stopped temporarily for some purpose, e.g. to pick up or drop off passengers or packages, or if a driver is on break. | 13 | | `non_contactable` | yes | Provider has temporarily lost contact with the vehicle and its disposition is unknown. Examples include: connectivity loss, GPS issues. | 14 | | `missing` | no | Provider has lost contact with the vehicle and its disposition is unknown with no immediate resolution. Examples include: scooter taken into a private residence, bike thrown in river. | 15 | | `elsewhere` | no | Outside of regulator's jurisdiction, and thus not subject to cap-counts or other regulations. Example: a vehicle that started a trip in L.A. has transitioned to Santa Monica. | 16 | 17 | ### Limitations on the Use of Certain Values 18 | 19 | MDS is intended to communicate the provider's best available information to regulators. However there may be legitimate circumstances where providers do not have definitive or current information about devices on the ground. MDS incorporates some values to convey these situations. These vehicle state and event type values are to be used sparingly and temporarily, and are not meant for repeated or prolonged use. These values exist to create logical coherence within MDS about vehicles that are operating abnormally or are out of communication. When a more accurate value is known, the MDS API should be updated with the latest information. Cities may add language to their Service Level Agreements (SLAs) that minimize the use of these values by providers. 20 | 21 | #### Vehicle State: Non-Contactible and Missing 22 | 23 | It is expected that `non-contactable` will be used only for short periods of time and cities may put in place specific limitations via an SLA. As vehicles regain connectivity they should return to their prior state, and then send additional events to reflect any subsequent changes to that state. If vehicles remain `non-contactable` for over a specific limit as stated in the City SLA, then vehicles should be moved to `missing`. 24 | 25 | --- 26 | 27 | [Modes Overview][modes] 28 | 29 | --- 30 | 31 | [MDS Home][home] 32 | 33 | [home]: /README.md 34 | [modes]: /modes/README.md 35 | -------------------------------------------------------------------------------- /policy/examples/README.md: -------------------------------------------------------------------------------- 1 | # Policy Examples 2 | 3 | See the [MDS Policy Examples](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Policy-Examples) wiki page for code examples of specific MDS Policy use cases. 4 | -------------------------------------------------------------------------------- /policy/examples/requirements.md: -------------------------------------------------------------------------------- 1 | # Policy Requirement Examples 2 | 3 | See the [MDS Policy Requirements Examples](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Policy-Requirements-Examples) wiki page for code examples of specific MDS Policy Requirements use cases. 4 | -------------------------------------------------------------------------------- /provider/examples.md: -------------------------------------------------------------------------------- 1 | 2 | # Provider Examples 3 | 4 | This file presents a series of [Provider examples](/provider). 5 | 6 | ## Table of Contents 7 | 8 | - [Reports](#reports) 9 | 10 | ## Reports 11 | 12 | For 3 months of provider operation in a city (September 2019 through November 2019) for 3 geographies, 2 vehicle types, and 1 special group. Values of `-1` represent [redacted data](#data-redaction) counts. 13 | 14 | **September 2019** `/reports/2019-09.csv` 15 | 16 | ```csv 17 | provider_id,start_date,duration,special_group_type,geography_id,vehicle_type,trip_count,rider_count 18 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1302,983 19 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,201,104 20 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,530,200 21 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,75,26 22 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,687,450 23 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,98,45 24 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,256,104 25 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,41,16 26 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,201,140 27 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,35,21 28 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,103,39 29 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,15,-1 30 | ``` 31 | 32 | **October 2019** `/reports/2019-10.csv` 33 | 34 | ```csv 35 | provider_id,start_date,duration,special_group_type,geography_id,vehicle_type,trip_count,rider_count 36 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-10-01,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1042,786 37 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-10-01,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,161,83 38 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-10-01,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,424,160 39 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-10-01,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,60,0 40 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-10-01,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,550,360 41 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-10-01,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,78,36 42 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-10-01,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,205,83 43 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-10-01,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,33,13 44 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-10-01,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,161,112 45 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-10-01,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,28,-1 46 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-10-01,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,82,31 47 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-10-01,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,-1,0 48 | ``` 49 | 50 | **November 2019** `/reports/2019-11.csv` 51 | 52 | ```csv 53 | provider_id,start_date,duration,special_group_type,geography_id,vehicle_type,trip_count,rider_count 54 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-11-01,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,834,629 55 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-11-01,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,129,66 56 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-11-01,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,339,128 57 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-11-01,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,48,-1 58 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-11-01,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,440,288 59 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-11-01,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,62,29 60 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-11-01,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,164,66 61 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-11-01,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,26,0 62 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-11-01,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,129,90 63 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-11-01,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,22,-1 64 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-11-01,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,-1,25 65 | 48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-11-01,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,0,0 66 | ``` 67 | 68 | [Top][toc] 69 | 70 | [toc]: #table-of-contents -------------------------------------------------------------------------------- /providers.csv: -------------------------------------------------------------------------------- 1 | provider_name,mode_id,provider_id,url,mds_api_url,gbfs_api_url 2 | JUMP,micromobility,c20e08cf-8488-46a6-a66c-5d8fb827f7e0,https://jump.com,https://api.uber.com/v0.2/emobility/mds, 3 | Lime,micromobility,63f13c48-34ff-49d2-aca7-cf6a5b6171c3,https://li.me,https://data.lime.bike/api/partners/v1/mds, 4 | Bird,micromobility,2411d395-04f2-47c9-ab66-d09e9e3c3251,https://www.bird.co,https://mds.bird.co,https://mds.bird.co/gbfs 5 | Razor,micromobility,6ddcc0ad-1d66-4046-bba4-d1d96bb8ca4d,https://www.razor.com/share,https://razor-200806.appspot.com/api/v2/mds, 6 | Lyft,micromobility,e714f168-ce56-4b41-81b7-0b6a4bd26128,https://www.lyft.com,https://api.lyft.com/v1/last-mile/mds, 7 | Skip,micromobility,d73fcf80-22b1-450f-b535-042b4e30aac7,https://www.skipscooters.com,https://api.skipscooters.com/mds, 8 | HOPR,micromobility,2e4cb206-b475-4a9d-80fb-0880c9a033e0,https://gohopr.com,https://gbfs.hopr.city/api/mds, 9 | Wheels,micromobility,b79f8687-526d-4ae6-80bf-89b4c44dc071,https://wheels.co,https://mds.getwheelsapp.com, 10 | Spin,micromobility,70aa475d-1fcd-4504-b69c-2eeb2107f7be,https://www.spin.app,https://web.spin.pm/api/mds/v1, 11 | WIND,micromobility,d56d2df6-fa92-43de-ab61-92c3a84acd7d,https://www.wind.co,https://partners.wind.co/v1/mds, 12 | Tier,micromobility,264aad41-b47c-415d-8585-0208d436516e,https://www.tier.app,https://partner.tier-services.io/mds, 13 | Cloud,micromobility,bf95148b-d1d1-464e-a140-6d2563ac43d4,https://www.cloud.tt,https://mds.cloud.tt,https://mds.cloud.tt/gbfs 14 | BlueLA,micromobility,f3c5a65d-fd85-463e-9564-fc95ea473f7d,https://www.bluela.com,https://api.bluela.com/mds/v0,https://api.bluela.com/gbfs/v1/meta 15 | Bolt,micromobility,3291c288-c9c8-42f1-bc3e-8502b077cd7f,https://www.micromobility.com/,https://bolt.miami/bolt2/api/mds, 16 | CLEVR,micromobility,daecbe87-a9f2-4a5a-b5df-8e3e14180513,https://clevrmobility.com,https://portal.clevrmobility.com/api/mds, 17 | SherpaLA,micromobility,3c95765d-4da6-41c6-b61e-1954472ec6c9,,https://mds.bird.co,https://mds.bird.co/gbfs/platform-partner/sherpa-la 18 | OjO Electric,micromobility,8d293326-8464-4256-8312-617ebcd0efad,https://www.ojoelectric.com,https://api.ojoelectric.com/api/mds,https://api.ojoelectric.com/api/mds/gbfs.json 19 | VOI,micromobility,1f129e3f-158f-4df5-af9c-a80de238e334,https://www.voiscooters.com/,https://mds.voiapp.io,https://mds.voiapp.io/v1/gbfs 20 | MOVO,micromobility,40dad54c-e199-4fd8-9f5b-cff93ffced63,https://movo.me,https://mds.movo.me,https://gbfs.movo.me 21 | Baus,micromobility,638ba503-4006-4c53-bf34-cd625cc03d61,https://bausmoves.com,https://mds.bird.co,https://mds.bird.co/gbfs/platform-partner/v2/baus 22 | Bolt Technology,micromobility,7ea695ca-9de7-4b3b-9f3c-241b2045a1fe,https://bolt.eu,https://mds.bolt.eu,https://mds.bolt.eu/gbfs/1 23 | Grin,micromobility,8a0ecfce-5fb3-451e-8069-434b79c8b01a,https://ongrin.com,https://open-data.grow.mobi/mds/,https://open-data.grow.mobi/api/v1/gbfs/ 24 | Dott,micromobility,0a899e3a-705a-46f2-9189-d78cc83a2db4,https://ridedott.com,https://mds.api.ridedott.com,https://gbfs.api.ridedott.com 25 | Superpedestrian,micromobility,420e6e94-55a6-4946-b6b3-4398fe22e912,https://www.superpedestrian.com,https://mds.linkyour.city/mds, 26 | Circ,micromobility,03d5d605-e5c9-45a1-a1dd-144aa8649525,https://www.circ.com,https://mds.bird.co, 27 | GIG,car-share,42475742-8618-4fc0-aa8f-3b3948b84b85,https://gigcarshare.com/,https://global.us.prod.svc.ridecell.io/reporting/api/mds, 28 | Zisch,micromobility,fb62cfe6-757c-4e5b-a264-18b43b3fc40b,https://www.e-zisch.ch,https://mds.bird.co, 29 | Seven Group,micromobility,7fca7812-c718-48dd-b9f2-d1ae160f2ae4,https://www.group-seven.ch,https://mds.bird.co, 30 | Pony,micromobility,f190d330-b49e-4590-871b-0bcbec565a8c,https://getapony.com/,https://mds.getapony.com/v1, 31 | SHARE-NOW,car-share,d8f880d6-96d8-4cdc-8069-32a683b2bce6,https://www.share-now.com,https://external.share-now.com/api/rental/mds/,https://external.share-now.com/api/rental/mds/gbfs/ 32 | Boaz Bikes,micromobility,7c96bc58-fb63-433a-b77f-84ccb1c9d737,https://www.boazbikes.com/,https://mds.movatic.co/,https://gbsf.movatic.co/en/1.1/576347857979998215 33 | VeoRide INC.,micromobility,6e39f9db-751b-5cea-ae7e-486f579a56bc,https://www.veoride.com/,https://cluster-prod.veoride.com/api/shares/mds,https://cluster-prod.veoride.com/api/shares/gbfs 34 | LEO Ride,micromobility,b0eedf6-c7a5-4262-9222-ab2484ad214e,https://leoride.co/,https://mobile.leoriders.com/mds,https://mobile.leoriders.com/gbpf 35 | LEO Explore,micromobility,7c653014-2f33-4f5b-98de-30ea66430986,https://leoride.co/,, 36 | ATOM Mobility,micromobility,4d88272c-032e-487c-9f58-ab5951a23427,https://atommobility.com/,https://mds.rideatom.com/mds, 37 | Zig Zag Sharing,micromobility,39977af0-4b94-11ec-81d3-0242ac130003,https://www.zigzagsharing.com/,https://mds.zigzagsharing.com/, 38 | TukTuk,micromobility,1a99bf67-14a0-48a1-98d1-77147a88c3d2,https://tuktukscooters.com/,https://app.tuktukscooters.com/mds-feed, 39 | Helbiz,micromobility,3aece8c6-416a-4d39-bcc4-d02524cb8004,https://helbiz.com,https://mds.helbiz.com, 40 | Kiwibot,delivery-robots,5f19acae-d7e9-4b57-96bd-f6406712d654,https://www.kiwibot.com/,, 41 | Yego,micromobility,da99028e-28b7-4dd3-ad23-41b7a045db8a,https://www.rideyego.com/,https://mds.yego.app/mds,https://services.rideyego.com/gbfs 42 | Leo&Go,micromobility,84b174c4-eb74-5d07-bdeb-27f4215d2aa9,https://www.leoandgo.com,https://mds.vulog.io/mds/fleets/LEONGO-FRLIO, 43 | Scoot,micromobility,07a25fe6-d0be-11e8-a8d5-f2801f1b9fd1,https://scoot.co/san-francisco/,https://mds.bird.co/,https://mds.bird.co/gbfs/ 44 | Revel,micromobility,89301314-1210-4126-a213-3c41423f2ac5,https://gorevel.com/,https://opendata.gorevel.com/opendata/mds/,https://gbfs.gorevel.com/gbfs/v2/ 45 | Troopy,micromobility,2b684c7c-f8ad-4c65-92f0-b9e57aaa7dd3,https://www.troopy.com,https://mds.vulog.io/mds/fleets/TROOPY-FRPAR,https://gbfs.vulog.io/mds/fleets/TROOPY-FRPAR/gbfs 46 | BCycle,micromobility,938D9F8B-B8D3-46CC-9276-F4A8C4FA3610,https://www.bcycle.com,https://mds.bcycle.com,https://gbfs.bcycle.com 47 | Tembici,micromobility,46b28e68-8ecb-4875-b97e-836fd5e1930f,https://www.tembici.com.br/,https://api.tembici.com.br/mds,https://api.tembici.com.br/gbfs 48 | POPPY Mobility,micromobility,5c869736-797f-4244-9132-fb50a22d1bfd,https://www.poppy.be/,https://poppy.red/mds, 49 | Whoosh,micromobility,3f8908a7-86fa-450d-8889-5d49077e06cd,https://whoosh.bike,https://mds.whoosh.bike,https://gbfs.whoosh.bike 50 | Telofun,micromobility,3dd253d3-557c-4fcb-98da-9af3edeaaae6,https://www.tel-o-fun.co.il/,https://mds.fsmctmobility.com/api/mds/v1/, 51 | Gbike,micromobility,a50b796e-bca2-11ed-afa1-0242ac120002,https://gcoo.io/,https://mds.gcoo.io/,https://mds.gcoo.io/gbfs 52 | SURF,micromobility,66c43ccb-f9f9-4f70-9707-37301b9f49a8,https://www.surfingscooters.com,https://api.app.surf/mds,https://api.app.surf/gbfs/en 53 | Nextbike,micromobility,31e54f5a-66c4-4a4c-bb6e-236351c90312,https://www.nextbike.de,https://platform-services.tier-services.io/data-sharing/mds/,https://api.nextbike.net/maps/gbfs/ 54 | Scooty,micromobility,f4ac8ed2-d6c3-4e6f-b000-f69050e8a616,https://www.otoride.co/,https://oto-api.otoride.co/api/v2/mds/, 55 | Starship Technologies,delivery-robots,4a1524f3-8182-4b55-90c2-023c0cac84b9,https://www.starship.xyz/,https://mds-provider.starship.xyz/api/v1/mds/, 56 | Deutsche Bahn Connect,micromobility,dcd47d65-b290-4bd6-adf2-24578fbd9110,https://www.deutschebahnconnect.com/,https://bike-prod.msp.dbrent.net/mds/,https://apis.deutschebahn.com/db-api-marketplace/apis/shared-mobility-gbfs/2-2/de/CallABike/gbfs/ 57 | MyWheels,micromobility,ce0320e3-0e4b-4884-b31a-45319c0768d6,https://mywheels.nl,https://mds.mywheels.nl, 58 | Flamingo,micromobility,a32f88c4-ad9b-4bf1-b5d8-e0262fa8a582,https://rideflamingo.com/,https://data.rideflamingo.com/mds/,https://data.rideflamingo.com/gbfs/3/manifest.json 59 | 3KM,micromobility,fd32a231-f373-4049-9b73-14686a24ed06,https://ario.ai,https://mds.ario.ai, 60 | HelloRide,micromobility,bffe2237-2df1-4cd1-b0dc-6f03c830a47a,https://www.hellorideglobal.com/,https://mds-api.hellobike.com/mds/, 61 | Bauer's Intelligent Transportation,passenger-services,46454118-168c-40e1-93bb-53e68e3f03bf,https://bauersit.com,, 62 | MV Transportation,passenger-services,e4722796-4e0e-4203-8ae9-546bdcc4aa52,https://www.missionbaytma.org/,, 63 | CLS Global Transportation,passenger-services,64477ac9-0c53-4031-98a4-ffe83bd94590,https://clsgt.com/,, 64 | Compass Transportation,passenger-services,f00500e6-55b9-4cdf-afe9-68db2822a3e2,https://www.compasstransportation.net/,, 65 | Corinthian International,passenger-services,0666cc3c-a346-4413-aa16-241c48281afb,http://corinthianparking.com/,, 66 | Hallcon,passenger-services,d6354b9d-4179-465f-b663-648a6fc054a5,https://hallcon.com/,, 67 | Kaiser Permanente,passenger-services,5e96f9c3-bd41-4337-a436-475fc9747621,https://kp.org/,, 68 | Lux Bus America,passenger-services,0697d1bb-1678-4375-b8c6-9e09e363cbfa,https://luxbusamerica.com/,, 69 | Lux Leasing,passenger-services,fe7a26bc-a0bb-4943-b335-cd334d4f5fab,https://luxbusamerica.com/,, 70 | Royal Coach Tours,passenger-services,095da27f-7bbd-45f1-b00b-eb52b244ccd4,http://royal-coach.com,, 71 | Storer,passenger-services,eee92c25-89f5-4e03-a4c7-b6dac883732a,https://storercoachways.com/,, 72 | We Drive U Inc,passenger-services,5488c6d1-baa8-4994-8763-a2c48090631a,https://wedriveu.com/,, 73 | Samsara,passenger-services,aa055687-5947-4921-ae1d-70d7755609ae,https://samsara.com/,, 74 | Tripshot,passenger-services,e154cf80-df89-4d7e-b5e7-2ee8050a6e9c,https://www.tripshot.com/,, 75 | Trakk,passenger-services,6a907d9d-1e3c-4cb6-991c-f9738d30337b,https://gettrakk.com/,, 76 | Swoop,passenger-services,08ad2b21-8115-4d18-874f-48082e8e50fb,https://www.swoopapp.com/,, 77 | GoSharing,micromobility,1f859479-4427-4f52-8220-05c786436314,https://www.binbin.tech/,https://complianceapi.binbinapp.com/api/mds/,https://complianceapi.binbinapp.com/api/gbfs/ 78 | 79 | -------------------------------------------------------------------------------- /schema/README.md: -------------------------------------------------------------------------------- 1 | # MDS Schema Definitions 2 | 3 | See the external OMF GitHub repository [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) for more details and schema definitions, and browse the interactive API documentation on our [MDS Stoplight workspace](https://openmobilityfnd.stoplight.io/docs/mds-openapi/). 4 | 5 | Starting with MDS 2.0, [OpenAPI](https://www.openapis.org/) documents describe MDS endpoints and allow for schema validation, expanding on the prior JSON Schemas work. 6 | --------------------------------------------------------------------------------