You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: general-information.md
+8Lines changed: 8 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -146,6 +146,14 @@ Agencies that wish to use Geography-Driven Events do so by requiring a new `even
146
146
During the Beta period for this feature, location and telemtry data remain required fields. This allows Aggencies to test Geography-Driven Events, measuring its accuracy and efficacy against regulatory systems based on precise location data. After the beta period, if Geography-Driven Events is deemed by OMF to be accurate and effective, the specification will evolve to allow cities to use Geography-Driven Events in lieu of location or telemtry data.
147
147
148
148
149
+
[Top][toc]
150
+
151
+
## Optional Authentication
152
+
153
+
Authorization of the Policy and Geography APIs is no longer required and will be deprecated in next major release with these endpoints becoming optionally private instead of optionally public. An agency may optionally decide to make both the Policy and Geography endpoints 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.
154
+
155
+
Note if implementing the beta features [Geography Driven Events](/general-information.md#geography-driven-events), both Policy and Geography must be public.
Copy file name to clipboardExpand all lines: geography/README.md
+2-4Lines changed: 2 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -81,9 +81,7 @@ See the [Responses][responses] and [Error Messages][error-messages] sections.
81
81
82
82
### Authorization
83
83
84
-
When making requests, the Geography API expects `provider_id` to include an `access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the Agency.
85
-
86
-
Optionally, an Agency may decide to make these endpoints unauthenticated and public, which could be done in conjunction with the [/policy](/policy) endpoints.
84
+
Authorization is not required. An agency may decide to make this endpoint unauthenticated and public. See [Optional Authentication](/general-information.md#optional-authentication) for details.
87
85
88
86
[Top][toc]
89
87
@@ -99,7 +97,7 @@ Placeholder -- link to schema to be added later.
|`description`| String | Optional | Detailed description of geography |
102
-
|`geography_type`|Sting| Optional | Type of geography, e.g. `municipal_boundary` or `council_district` or custom text. See [Geography Types](#geography-types). |
100
+
|`geography_type`|String| Optional | Type of geography, e.g. `municipal_boundary` or `council_district` or custom text. See [Geography Types](#geography-types). |
103
101
|`geography_id`| UUID | Required | Unique ID of geography |
104
102
|`geography_json`| UUID | Required | The GeoJSON that defines the geographical coordinates. |
105
103
|`effective_date`|[timestamp][ts]| Optional | The date at which a Geography is considered "live". Must be at or after `published_date`. |
Copy file name to clipboardExpand all lines: policy/README.md
+11Lines changed: 11 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,7 @@ This specification describes the digital relationship between _mobility as a ser
8
8
9
9
-[General Information](#general-information)
10
10
-[Versioning](#versioning)
11
+
-[Update Frequency](#update-frequency)
11
12
-[Background](#background)
12
13
-[Distribution](#distribution)
13
14
-[REST Endpoints](#rest-endpoints)
@@ -29,6 +30,12 @@ The following information applies to all `policy` API endpoints.
29
30
30
31
[Top][toc]
31
32
33
+
### Update Frequency
34
+
35
+
The publishing agency should establish beforehand and communicate to providers how frequently the Policy endpoints are expected to change, how often they should be polled to get the latest information, and expectations around emergency updates.
36
+
37
+
[Top][toc]
38
+
32
39
### Versioning
33
40
34
41
`policy` APIs must handle requests for specific versions of the specification from clients.
@@ -90,6 +97,10 @@ The response to a client request must include a valid HTTP status code defined i
90
97
91
98
See the [Responses section][responses] for information on valid MDS response codes and the [Error Messages section][error-messages] for information on formatting error messages.
92
99
100
+
### Authorization
101
+
102
+
Authorization is not required. An agency may decide to make this endpoint unauthenticated and public. See [Optional Authentication](/general-information.md#optional-authentication) for details.
@@ -291,6 +296,118 @@ Without an `event_time` query parameter, `/status_changes` shall return a `400 B
291
296
292
297
[Top][toc]
293
298
299
+
300
+
## Reports
301
+
302
+
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.
303
+
304
+
The authenticated reports are monthly, historic flat files that may be pre-generated by the provider.
305
+
306
+
### Reports - Response
307
+
308
+
**Endpoint:**`/reports`
309
+
**Method:**`GET`
310
+
**[Beta feature][beta]:** Yes (as of 1.1.0)
311
+
**Schema:** TBD when out of beta
312
+
**`data` Filename:** monthly file named by year and month, e.g. `/reports/YYYY-MM.csv`
313
+
**`data` Payload:** monthly CSV files with the following structure:
| StartDate | date | Start date of the data row, ISO 8601 format, local timezone |
318
+
| Duration | string | Value is always `P1M` for monthly. Based on [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations)|
319
+
| Special Group Type |[Special Group Type](#special-group-type)| Type that applies to this row |
320
+
| Geography ID |[Geography](/geography)| ID that applies to this row. Includes all IDs in /geography. When there is no /geography then return `null` for this value and counts based on the entire operating area. |
321
+
| Vehicle Type |[Vehicle Type](/agency#vehicle-type)| Type that applies to this row |
322
+
| Trip Count | integer | Count of trips taken for this row |
323
+
| Rider Count | integer | Count of unique riders for this row |
324
+
325
+
#### Data Notes
326
+
327
+
Report contents include every combination of special group types, geography IDs, and vehicle types in operation for each month since the provider began operations in the jurisdiction. New files are added monthly in addition to the previous monthly historic files.
328
+
329
+
Counts are calculated based the city's local time zone, and this time zone is returned within the `StartDate` value. For months where there is a Daylight Saving Time change, use the timezone that is in the majority of the month.
330
+
331
+
All geography IDs included in the city published [Geography](/geography) API endpoint are included in the report results. In lieu of serving an API, this can alternately be a [flat file](/geography#file-format) created by the city and sent to the provider via link. If there is no `/geography` available, then counts are for the entire agency operating area, and `null` is returned for Geography ID.
332
+
333
+
### Reports - Example
334
+
335
+
For 3 months of provider operation in a city (September 2019 through November 2019) for 3 geographies, 2 vehicle types, and 1 special group. Timezone is Eastern Time in the US which is _-4_ from UTC before November 3, 2019, and _-5_ after. Values of `-1` represent [redacted data](#data-redaction) counts.
336
+
337
+
**September 2019**`/reports/2019-09.csv`
338
+
339
+
```csv
340
+
StartDate,Duration,Special Group Type,Geography ID,Vehicle Type,Trip Count,Rider Count
| low_income | Trips where a low income discount is applied by the provider, e.g., a discount from a qualified provider equity plan. |
398
+
| all_riders | All riders from any group |
399
+
400
+
Other special group types may be added in future MDS releases as relevant agency and provider use cases are identified. When additional special group types or metrics are proposed, a thorough review of utility and relevance in program oversight, evaluation, and policy development should be done by OMF Working Groups, as well as any privacy implications by the OMF Privacy Committee.
401
+
402
+
### Data Redaction
403
+
404
+
Some combinations of parameters may return a small count of trips, which could increase a privacy risk of re-identification. To correct for that, Reports does not return data below a certain count of results. This is called k-anonymity, and the threshold is set at a k-value of 10.
405
+
406
+
If the report returns count values from 1 through 10, then a number of value `-1` is returned to represent redacted data. Counts of `0` are still returned as usual. This requirement is applied to both counts of trips and unique riders.
0 commit comments