From 7b852a2179d750e591e254c06f7ea6d26635857f Mon Sep 17 00:00:00 2001
From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com>
Date: Fri, 11 Dec 2020 16:39:43 -0500
Subject: [PATCH 01/10] First pass without example yet

---
 provider/README.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/provider/README.md b/provider/README.md
index 77d604a7..ace88612 100644
--- a/provider/README.md
+++ b/provider/README.md
@@ -20,6 +20,8 @@ This specification contains a data standard for *mobility as a service* provider
   * [Routes](#routes)
 * [Status Changes][status]
   * [Status Changes - Query Parameters](#status-changes---query-parameters)
+* [Reports](#reports)
+  * [Data Redaction](#data-redaction)
 * [Realtime Data](#realtime-data)
   * [GBFS](#GBFS)
   * [Data Latency Requirements][data-latency]
@@ -291,6 +293,61 @@ Without an `event_time` query parameter, `/status_changes` shall return a `400 B
 
 [Top][toc]
 
+
+## Reports
+
+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.
+
+The authenticated reports endpoint is a flat file that may be pre-generated by the provider.
+
+### Reports - Response
+
+**Endpoint:** `/reports`  
+**Method:** `GET`  
+**[Beta feature][beta]:** Yes (as of 1.1.0)  
+**Schema:** TBD when out of beta  
+**`data` Payload:** a CSV file with the following structure: 
+
+| Name               | Type                                      | Comments                                    |
+| ------------------ | ----------------------------------------- | ------------------------------------------- |
+| StartDate          | date                                      | Start date of the data row, ISO 8601 format |
+| Duration           | string                                    | Value is always `P1M` for monthly. Based on [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) |
+| Special Group Type | [Special Group Type](#special-group-type) | Type that applies to this row               |
+| Geography ID       | [Geography](/geography)                   | ID that applies to this row                 |
+| Vehicle Type       | [Vehicle Type](/agency#vehicle-type)      | Type that applies to this row               |
+| Trip Count         | integer                                   | Count of trips taken for this row           |
+| Rider Count        | integer                                   | Count of unique riders for this row         |
+ 
+Contents include every combination of geography ID and vehicle type that the city requests for each month of the entire provider operating time period in the jurisdiction, updated monthly. Every Special Group Type is required.
+
+### Special Group Type	
+
+Here are the possible values for the `special_group_type` dimension field:	
+
+| Name       | Description                                                                                                           |	
+| ---------- | --------------------------------------------------------------------------------------------------------------------- |	
+| low_income | Trips where a low income discount is applied by the provider, e.g., a discount from a qualified provider equity plan. |	
+| all_riders | All riders from any group                                                                                             |	
+
+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.
+
+### Reports - Example
+
+```csv
+x,y,x,10
+```
+
+### Data Redaction
+
+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.
+
+If the query returns less than 10 trips in its count, then a rows value number of -1 is returned.
+
+The k-value used is always returned in the `/reports` endpoint response to provide important context for the data consumer on the data redaction that is occuring.
+
+[Top][toc]
+
+
 ## Realtime Data
 
 ### GBFS

From 0efff58508bd30aae2b4ec4b12648b770967638e Mon Sep 17 00:00:00 2001
From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com>
Date: Fri, 11 Dec 2020 17:13:59 -0500
Subject: [PATCH 02/10] Added example

Can move example to a folder later.
---
 provider/README.md | 69 ++++++++++++++++++++++++++++++++++++----------
 1 file changed, 55 insertions(+), 14 deletions(-)

diff --git a/provider/README.md b/provider/README.md
index ace88612..677689fc 100644
--- a/provider/README.md
+++ b/provider/README.md
@@ -21,6 +21,9 @@ This specification contains a data standard for *mobility as a service* provider
 * [Status Changes][status]
   * [Status Changes - Query Parameters](#status-changes---query-parameters)
 * [Reports](#reports)
+  * [Reports - Response](#reports---response)
+  * [Reports - Example](#reports---example)
+  * [Special Group Type](#special-group-type)
   * [Data Redaction](#data-redaction)
 * [Realtime Data](#realtime-data)
   * [GBFS](#GBFS)
@@ -308,18 +311,62 @@ The authenticated reports endpoint is a flat file that may be pre-generated by t
 **Schema:** TBD when out of beta  
 **`data` Payload:** a CSV file with the following structure: 
 
-| Name               | Type                                      | Comments                                    |
-| ------------------ | ----------------------------------------- | ------------------------------------------- |
-| StartDate          | date                                      | Start date of the data row, ISO 8601 format |
+| Name               | Type                                      | Comments                                         |
+| ------------------ | ----------------------------------------- | ------------------------------------------------ |
+| StartDate          | date                                      | Start date of the data row, ISO 8601 format, UTC |
 | Duration           | string                                    | Value is always `P1M` for monthly. Based on [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) |
-| Special Group Type | [Special Group Type](#special-group-type) | Type that applies to this row               |
-| Geography ID       | [Geography](/geography)                   | ID that applies to this row                 |
-| Vehicle Type       | [Vehicle Type](/agency#vehicle-type)      | Type that applies to this row               |
-| Trip Count         | integer                                   | Count of trips taken for this row           |
-| Rider Count        | integer                                   | Count of unique riders for this row         |
+| Special Group Type | [Special Group Type](#special-group-type) | Type that applies to this row                    |
+| Geography ID       | [Geography](/geography)                   | ID that applies to this row                      |
+| Vehicle Type       | [Vehicle Type](/agency#vehicle-type)      | Type that applies to this row                    |
+| Trip Count         | integer                                   | Count of trips taken for this row                |
+| Rider Count        | integer                                   | Count of unique riders for this row              |
  
 Contents include every combination of geography ID and vehicle type that the city requests for each month of the entire provider operating time period in the jurisdiction, updated monthly. Every Special Group Type is required.
 
+### Reports - Example
+
+From June 2019 through September 2019 for 3 geographies and 2 vehicle types.
+
+```csv
+StartDate,Duration,Special Group Type,Geography ID,Vehicle Type,Trip Count,Rider Count
+2019-07-01T00:00-00,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1302,983
+2019-07-01T00:00-01,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,201,104
+2019-07-01T00:00-02,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,530,200
+2019-07-01T00:00-03,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,75,26
+2019-07-01T00:00-04,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,687,450
+2019-07-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,98,45
+2019-07-01T00:00-06,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,256,104
+2019-07-01T00:00-07,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,41,16
+2019-07-01T00:00-08,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,201,140
+2019-07-01T00:00-09,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,35,21
+2019-07-01T00:00-10,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,103,39
+2019-07-01T00:00-11,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,15,-1
+2019-08-01T00:00-00,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1042,786
+2019-08-01T00:00-01,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,161,83
+2019-08-01T00:00-02,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,424,160
+2019-08-01T00:00-03,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,60,21
+2019-08-01T00:00-04,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,550,360
+2019-08-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,78,36
+2019-08-01T00:00-06,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,205,83
+2019-08-01T00:00-07,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,33,13
+2019-08-01T00:00-08,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,161,112
+2019-08-01T00:00-09,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,28,17
+2019-08-01T00:00-10,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,82,31
+2019-08-01T00:00-11,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,12,-1
+2019-09-01T00:00-0,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,834,629
+2019-09-01T00:00-1,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,129,66
+2019-09-01T00:00-2,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,339,128
+2019-09-01T00:00-3,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,48,-1
+2019-09-01T00:00-4,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,440,288
+2019-09-01T00:00-5,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,62,29
+2019-09-01T00:00-6,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,164,66
+2019-09-01T00:00-7,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,26,10
+2019-09-01T00:00-8,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,129,90
+2019-09-01T00:00-9,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,22,-1
+2019-09-01T00:00-10,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,66,25
+2019-09-01T00:00-11,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,-1,-1 
+```
+
 ### Special Group Type	
 
 Here are the possible values for the `special_group_type` dimension field:	
@@ -331,12 +378,6 @@ Here are the possible values for the `special_group_type` dimension field:
 
 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.
 
-### Reports - Example
-
-```csv
-x,y,x,10
-```
-
 ### Data Redaction
 
 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.

From 131ae197fddc1f2f3d410a71798ec7978b85ad5f Mon Sep 17 00:00:00 2001
From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com>
Date: Mon, 14 Dec 2020 13:08:29 -0500
Subject: [PATCH 03/10] Example update

---
 provider/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/provider/README.md b/provider/README.md
index 677689fc..ebedd0cb 100644
--- a/provider/README.md
+++ b/provider/README.md
@@ -325,7 +325,7 @@ Contents include every combination of geography ID and vehicle type that the cit
 
 ### Reports - Example
 
-From June 2019 through September 2019 for 3 geographies and 2 vehicle types.
+For 3 months (July 2019 through September 2019) for 3 geographies and 2 vehicle types. Values of `-1` represent [redacted data](#data-redaction).
 
 ```csv
 StartDate,Duration,Special Group Type,Geography ID,Vehicle Type,Trip Count,Rider Count
@@ -382,7 +382,7 @@ Other special group types may be added in future MDS releases as relevant agency
 
 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.
 
-If the query returns less than 10 trips in its count, then a rows value number of -1 is returned.
+If the report returns less than 10 in any count, then a value number of -1 is returned.
 
 The k-value used is always returned in the `/reports` endpoint response to provide important context for the data consumer on the data redaction that is occuring.
 

From 531d79973240ec04497cb266ae74dab149c09e16 Mon Sep 17 00:00:00 2001
From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com>
Date: Mon, 14 Dec 2020 15:19:01 -0500
Subject: [PATCH 04/10] Updated examples to monthly files

---
 provider/README.md | 84 +++++++++++++++++++++++++++-------------------
 1 file changed, 49 insertions(+), 35 deletions(-)

diff --git a/provider/README.md b/provider/README.md
index ebedd0cb..f30cbcee 100644
--- a/provider/README.md
+++ b/provider/README.md
@@ -325,46 +325,60 @@ Contents include every combination of geography ID and vehicle type that the cit
 
 ### Reports - Example
 
-For 3 months (July 2019 through September 2019) for 3 geographies and 2 vehicle types. Values of `-1` represent [redacted data](#data-redaction).
+For 3 months of provider operation in a city (July 2019 through September 2019) for 3 geographies, 2 vehicle types, and 1 speical group. Values of `-1` represent [redacted data](#data-redaction).
+
+**July 2019** `/reports/2019-07.csv`
 
 ```csv
 StartDate,Duration,Special Group Type,Geography ID,Vehicle Type,Trip Count,Rider Count
-2019-07-01T00:00-00,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1302,983
-2019-07-01T00:00-01,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,201,104
-2019-07-01T00:00-02,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,530,200
-2019-07-01T00:00-03,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,75,26
-2019-07-01T00:00-04,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,687,450
+2019-07-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1302,983
+2019-07-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,201,104
+2019-07-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,530,200
+2019-07-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,75,26
+2019-07-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,687,450
 2019-07-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,98,45
-2019-07-01T00:00-06,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,256,104
-2019-07-01T00:00-07,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,41,16
-2019-07-01T00:00-08,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,201,140
-2019-07-01T00:00-09,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,35,21
-2019-07-01T00:00-10,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,103,39
-2019-07-01T00:00-11,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,15,-1
-2019-08-01T00:00-00,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1042,786
-2019-08-01T00:00-01,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,161,83
-2019-08-01T00:00-02,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,424,160
-2019-08-01T00:00-03,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,60,21
-2019-08-01T00:00-04,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,550,360
+2019-07-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,256,104
+2019-07-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,41,16
+2019-07-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,201,140
+2019-07-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,35,21
+2019-07-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,103,39
+2019-07-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,15,-1
+```
+
+**August 2019** `/reports/2019-08.csv`
+
+```csv
+StartDate,Duration,Special Group Type,Geography ID,Vehicle Type,Trip Count,Rider Count
+2019-08-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1042,786
+2019-08-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,161,83
+2019-08-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,424,160
+2019-08-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,60,21
+2019-08-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,550,360
 2019-08-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,78,36
-2019-08-01T00:00-06,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,205,83
-2019-08-01T00:00-07,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,33,13
-2019-08-01T00:00-08,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,161,112
-2019-08-01T00:00-09,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,28,17
-2019-08-01T00:00-10,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,82,31
-2019-08-01T00:00-11,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,12,-1
-2019-09-01T00:00-0,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,834,629
-2019-09-01T00:00-1,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,129,66
-2019-09-01T00:00-2,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,339,128
-2019-09-01T00:00-3,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,48,-1
-2019-09-01T00:00-4,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,440,288
-2019-09-01T00:00-5,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,62,29
-2019-09-01T00:00-6,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,164,66
-2019-09-01T00:00-7,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,26,10
-2019-09-01T00:00-8,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,129,90
-2019-09-01T00:00-9,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,22,-1
-2019-09-01T00:00-10,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,66,25
-2019-09-01T00:00-11,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,-1,-1 
+2019-08-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,205,83
+2019-08-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,33,13
+2019-08-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,161,112
+2019-08-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,28,17
+2019-08-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,82,31
+2019-08-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,12,-1
+```
+
+**September 2019** `/reports/2019-09.csv`
+
+```csv
+StartDate,Duration,Special Group Type,Geography ID,Vehicle Type,Trip Count,Rider Count
+2019-09-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,834,629
+2019-09-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,129,66
+2019-09-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,339,128
+2019-09-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,48,-1
+2019-09-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,440,288
+2019-09-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,62,29
+2019-09-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,164,66
+2019-09-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,26,10
+2019-09-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,129,90
+2019-09-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,22,-1
+2019-09-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,66,25
+2019-09-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,-1,-1
 ```
 
 ### Special Group Type	

From edef4a97188de032ff2f6fa941b69826f460d821 Mon Sep 17 00:00:00 2001
From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com>
Date: Mon, 14 Dec 2020 15:52:12 -0500
Subject: [PATCH 05/10] Clarified Data Notes

---
 provider/README.md | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/provider/README.md b/provider/README.md
index f30cbcee..51703869 100644
--- a/provider/README.md
+++ b/provider/README.md
@@ -299,9 +299,9 @@ Without an `event_time` query parameter, `/status_changes` shall return a `400 B
 
 ## Reports
 
-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.
+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.
 
-The authenticated reports endpoint is a flat file that may be pre-generated by the provider.
+The authenticated reports endpoint are monthly, historic flat files that may be pre-generated by the provider.
 
 ### Reports - Response
 
@@ -309,19 +309,26 @@ The authenticated reports endpoint is a flat file that may be pre-generated by t
 **Method:** `GET`  
 **[Beta feature][beta]:** Yes (as of 1.1.0)  
 **Schema:** TBD when out of beta  
-**`data` Payload:** a CSV file with the following structure: 
+**`data` Filename:** monthly file named by year and month, e.g. `/reports/YYYY-MM.csv` 
+**`data` Payload:** monthly CSV files with the following structure: 
 
 | Name               | Type                                      | Comments                                         |
 | ------------------ | ----------------------------------------- | ------------------------------------------------ |
-| StartDate          | date                                      | Start date of the data row, ISO 8601 format, UTC |
+| StartDate          | date                                      | Start date of the data row, ISO 8601 format, local timezone |
 | Duration           | string                                    | Value is always `P1M` for monthly. Based on [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) |
 | Special Group Type | [Special Group Type](#special-group-type) | Type that applies to this row                    |
-| Geography ID       | [Geography](/geography)                   | ID that applies to this row                      |
+| 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. |
 | Vehicle Type       | [Vehicle Type](/agency#vehicle-type)      | Type that applies to this row                    |
 | Trip Count         | integer                                   | Count of trips taken for this row                |
 | Rider Count        | integer                                   | Count of unique riders for this row              |
- 
-Contents include every combination of geography ID and vehicle type that the city requests for each month of the entire provider operating time period in the jurisdiction, updated monthly. Every Special Group Type is required.
+
+#### Data Notes
+
+Report contents include every combination of special group types, geography IDs, and vehicle types in operation for each month of the entire provider operating time period in the jurisdiction. New files are added monthly in addition to the previous monthly files. 
+
+Counts are calculated based the city's local time zone, and this time zone is returned within the `StartDate` value.
+
+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. If there is no `/geography` available, then counts are for the entire agency operating area, and `null` is returned for Geography ID. 
 
 ### Reports - Example
 
@@ -396,9 +403,7 @@ Other special group types may be added in future MDS releases as relevant agency
 
 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.
 
-If the report returns less than 10 in any count, then a value number of -1 is returned.
-
-The k-value used is always returned in the `/reports` endpoint response to provide important context for the data consumer on the data redaction that is occuring.
+If the report returns less than 10 in any count, then a number of value -1 is returned.
 
 [Top][toc]
 

From 5cb97b90fd1b9979fa43c2a0820e28db73beaec6 Mon Sep 17 00:00:00 2001
From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com>
Date: Mon, 14 Dec 2020 15:55:32 -0500
Subject: [PATCH 06/10] Update to operations timeline

---
 provider/README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/provider/README.md b/provider/README.md
index 51703869..352479d6 100644
--- a/provider/README.md
+++ b/provider/README.md
@@ -309,7 +309,7 @@ The authenticated reports endpoint are monthly, historic flat files that may be
 **Method:** `GET`  
 **[Beta feature][beta]:** Yes (as of 1.1.0)  
 **Schema:** TBD when out of beta  
-**`data` Filename:** monthly file named by year and month, e.g. `/reports/YYYY-MM.csv` 
+**`data` Filename:** monthly file named by year and month, e.g. `/reports/YYYY-MM.csv`  
 **`data` Payload:** monthly CSV files with the following structure: 
 
 | Name               | Type                                      | Comments                                         |
@@ -324,15 +324,15 @@ The authenticated reports endpoint are monthly, historic flat files that may be
 
 #### Data Notes
 
-Report contents include every combination of special group types, geography IDs, and vehicle types in operation for each month of the entire provider operating time period in the jurisdiction. New files are added monthly in addition to the previous monthly files. 
+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. 
 
 Counts are calculated based the city's local time zone, and this time zone is returned within the `StartDate` value.
 
-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. If there is no `/geography` available, then counts are for the entire agency operating area, and `null` is returned for Geography ID. 
+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. 
 
 ### Reports - Example
 
-For 3 months of provider operation in a city (July 2019 through September 2019) for 3 geographies, 2 vehicle types, and 1 speical group. Values of `-1` represent [redacted data](#data-redaction).
+For 3 months of provider operation in a city (July 2019 through September 2019) for 3 geographies, 2 vehicle types, and 1 special group. Values of `-1` represent [redacted data](#data-redaction).
 
 **July 2019** `/reports/2019-07.csv`
 

From a5d8036fb64ea0e70d1eda7e310c598765908005 Mon Sep 17 00:00:00 2001
From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com>
Date: Mon, 14 Dec 2020 16:49:59 -0500
Subject: [PATCH 07/10] Timezone and k-value updates

---
 provider/README.md | 84 +++++++++++++++++++++++-----------------------
 1 file changed, 42 insertions(+), 42 deletions(-)

diff --git a/provider/README.md b/provider/README.md
index 352479d6..d904574f 100644
--- a/provider/README.md
+++ b/provider/README.md
@@ -326,66 +326,66 @@ The authenticated reports endpoint are monthly, historic flat files that may be
 
 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. 
 
-Counts are calculated based the city's local time zone, and this time zone is returned within the `StartDate` value.
+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.
 
 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. 
 
 ### Reports - Example
 
-For 3 months of provider operation in a city (July 2019 through September 2019) for 3 geographies, 2 vehicle types, and 1 special group. Values of `-1` represent [redacted data](#data-redaction).
+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.
 
-**July 2019** `/reports/2019-07.csv`
+**September 2019** `/reports/2019-09.csv`
 
 ```csv
 StartDate,Duration,Special Group Type,Geography ID,Vehicle Type,Trip Count,Rider Count
-2019-07-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1302,983
-2019-07-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,201,104
-2019-07-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,530,200
-2019-07-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,75,26
-2019-07-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,687,450
-2019-07-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,98,45
-2019-07-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,256,104
-2019-07-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,41,16
-2019-07-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,201,140
-2019-07-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,35,21
-2019-07-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,103,39
-2019-07-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,15,-1
+2019-09-01T00:00-04,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1302,983
+2019-09-01T00:00-04,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,201,104
+2019-09-01T00:00-04,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,530,200
+2019-09-01T00:00-04,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,75,26
+2019-09-01T00:00-04,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,687,450
+2019-09-01T00:00-04,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,98,45
+2019-09-01T00:00-04,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,256,104
+2019-09-01T00:00-04,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,41,16
+2019-09-01T00:00-04,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,201,140
+2019-09-01T00:00-04,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,35,21
+2019-09-01T00:00-04,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,103,39
+2019-09-01T00:00-04,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,15,-1
 ```
 
-**August 2019** `/reports/2019-08.csv`
+**October 2019** `/reports/2019-10.csv`
 
 ```csv
 StartDate,Duration,Special Group Type,Geography ID,Vehicle Type,Trip Count,Rider Count
-2019-08-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1042,786
-2019-08-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,161,83
-2019-08-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,424,160
-2019-08-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,60,21
-2019-08-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,550,360
-2019-08-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,78,36
-2019-08-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,205,83
-2019-08-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,33,13
-2019-08-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,161,112
-2019-08-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,28,17
-2019-08-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,82,31
-2019-08-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,12,-1
+2019-10-01T00:00-04,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1042,786
+2019-10-01T00:00-04,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,161,83
+2019-10-01T00:00-04,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,424,160
+2019-10-01T00:00-04,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,60,0
+2019-10-01T00:00-04,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,550,360
+2019-10-01T00:00-04,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,78,36
+2019-10-01T00:00-04,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,205,83
+2019-10-01T00:00-04,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,33,13
+2019-10-01T00:00-04,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,161,112
+2019-10-01T00:00-04,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,28,-1
+2019-10-01T00:00-04,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,82,31
+2019-10-01T00:00-04,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,-1,0
 ```
 
-**September 2019** `/reports/2019-09.csv`
+**November 2019** `/reports/2019-11.csv`
 
 ```csv
 StartDate,Duration,Special Group Type,Geography ID,Vehicle Type,Trip Count,Rider Count
-2019-09-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,834,629
-2019-09-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,129,66
-2019-09-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,339,128
-2019-09-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,48,-1
-2019-09-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,440,288
-2019-09-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,62,29
-2019-09-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,164,66
-2019-09-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,26,10
-2019-09-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,129,90
-2019-09-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,22,-1
-2019-09-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,66,25
-2019-09-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,-1,-1
+2019-11-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,834,629
+2019-11-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,129,66
+2019-11-01T00:00-05,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,339,128
+2019-11-01T00:00-05,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,48,-1
+2019-11-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,440,288
+2019-11-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,62,29
+2019-11-01T00:00-05,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,164,66
+2019-11-01T00:00-05,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,26,0
+2019-11-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,129,90
+2019-11-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,22,-1
+2019-11-01T00:00-05,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,-1,25
+2019-11-01T00:00-05,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,0,0
 ```
 
 ### Special Group Type	
@@ -403,7 +403,7 @@ Other special group types may be added in future MDS releases as relevant agency
 
 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.
 
-If the report returns less than 10 in any count, then a number of value -1 is returned.
+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.
 
 [Top][toc]
 

From 55ea53f243be7f1c199c1e0c5bc455a10308337b Mon Sep 17 00:00:00 2001
From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com>
Date: Tue, 15 Dec 2020 14:48:50 -0500
Subject: [PATCH 08/10] Updates based on comments

---
 provider/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/provider/README.md b/provider/README.md
index d904574f..ace02f6f 100644
--- a/provider/README.md
+++ b/provider/README.md
@@ -301,7 +301,7 @@ Without an `event_time` query parameter, `/status_changes` shall return a `400 B
 
 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.
 
-The authenticated reports endpoint are monthly, historic flat files that may be pre-generated by the provider.
+The authenticated reports are monthly, historic flat files that may be pre-generated by the provider.
 
 ### Reports - Response
 
@@ -403,7 +403,7 @@ Other special group types may be added in future MDS releases as relevant agency
 
 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.
 
-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.
+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.
 
 [Top][toc]
 

From a05923549c58fb0eddcfbd6a73c841214b0384da Mon Sep 17 00:00:00 2001
From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com>
Date: Tue, 15 Dec 2020 14:52:38 -0500
Subject: [PATCH 09/10] Geography typo

---
 geography/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/geography/README.md b/geography/README.md
index 495a1313..1315b267 100644
--- a/geography/README.md
+++ b/geography/README.md
@@ -99,7 +99,7 @@ Placeholder -- link to schema to be added later.
 | ----------------   | --------- | --- | --------------------------------------------------------------------------------------------- |
 | `name`             | String    | Required   | Name of geography                                                                      |
 | `description`      | String    | Optional   | Detailed description of geography                                                      |
-| `geography_type`   | Sting     | Optional   | Type of geography, e.g. `municipal_boundary` or `council_district` or custom text.  See [Geography Types](#geography-types). |
+| `geography_type`   | String     | Optional   | Type of geography, e.g. `municipal_boundary` or `council_district` or custom text.  See [Geography Types](#geography-types). |
 | `geography_id`     | UUID      | Required   | Unique ID of geography                                                                 |
 | `geography_json`   | UUID      | Required   | The GeoJSON that defines the geographical coordinates.                                 |
 | `effective_date`   | [timestamp][ts] | Optional   | The date at which a Geography is considered "live".  Must be at or after `published_date`. |

From 02d56d674006e00a6c3a69b08b93c590ace4f080 Mon Sep 17 00:00:00 2001
From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com>
Date: Tue, 15 Dec 2020 14:53:24 -0500
Subject: [PATCH 10/10] Remove special group type from Metrics

---
 metrics/core_metrics.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/metrics/core_metrics.md b/metrics/core_metrics.md
index 4b0b2ee6..e061c423 100644
--- a/metrics/core_metrics.md
+++ b/metrics/core_metrics.md
@@ -41,7 +41,6 @@ The following represent the suggested MDS core metric dimensions:
 | provider_id        | Transportation provider id issued by OMF and [tracked here](/providers.csv) |
 | geography_id       | [MDS Geography](/geography)                                                 |
 | vehicle_type       | [Vehicle Type](/agency#vehicle-type) defined by MDS                         |
-| special_group_type | [Special Group Type](#special-group-type) defined by MDS                    |
 
 [Top][toc]