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
|`description`| String | Optional | Detailed description of geography |
100
-
|`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). |
101
101
|`geography_id`| UUID | Required | Unique ID of geography |
102
102
|`geography_json`| UUID | Required | The GeoJSON that defines the geographical coordinates. |
103
103
|`effective_date`|[timestamp][ts]| Optional | The date at which a Geography is considered "live". Must be at or after `published_date`. |
@@ -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