Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add geography and authentication to Metrics feature branch #594

Merged
merged 7 commits into from
Oct 31, 2020
Merged

Add geography and authentication to Metrics feature branch #594

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
bccbe09
Added MDS geography fixes and examples.
whereissean Oct 28, 2020
7b92d65
Added MDS geography fixes and examples.
whereissean Oct 28, 2020
bb49f7e
Added MDS geography fixes and examples.
whereissean Oct 28, 2020
b8b0888
Added MDS geography fixes and examples.
whereissean Oct 29, 2020
f80017a
Added MDS geography fixes and examples.
whereissean Oct 29, 2020
d70d6d3
Added MDS geography fixes and examples.
whereissean Oct 29, 2020
fdecdd7
Added MDS geography fixes and examples.
whereissean Oct 29, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 28 additions & 14 deletions metrics/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,15 @@ The Metrics API endpoints are intended to be implemented by regulatory agencies
## General Information

Objectives:

- Cities need a number of clearly defined best practice metrics for operating, measuring, and managing emerging micro mobility programs using MDS data.
- 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.
- Cities need to rely upon trusted data sources upon which to perform longer term studies on citizen impact.
- Mobility providers would like consistent rules between each city deployment in order to make their operations more scalable.
- Some information like special groups usage is too sensitive to be shared at the trip level, so aggregate metrics are a preferable way to share a subset of this provider data with cities to evaluate program success.

Initial Design Use Cases and Scenarios:

- For cities to republish data ingested from MDS (Agency or Provider data) for use in visualization, analysis, or other applications to trusted third parties (e.g., departments or individuals within their city, academic researchers).
- For cities to publish calculated metrics back to providers allowing shared understanding and alignment on billing, enforcement, and policy alignment.
- For providers to publish metrics to cities for analysis and report alignment. This is not meant to replace the required MDS [trips](https://github.com/openmobilityfoundation/mobility-data-specification/tree/feature-metrics/provider#trips) endpoint, but it may supplement it and solve a few of a city's use cases.
Expand All @@ -39,8 +41,17 @@ All interval durations (duration) are [ISO 8601](https://en.wikipedia.org/wiki/I
[Top][toc]

## Authorization

When making requests, the Metrics API expects `provider_id` to be part of the claims in a [JWT](https://jwt.io/) `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/Provider.
### For Agencies hosting the Metrics API
When making requests, the Metrics API expects one of two scopes `metrics:read` or `metrics:read:provider` to be present as part of the `scope` claims in a [JWT](https://jwt.io/) `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.
​
If a client has a `metrics:read` scope, they are permitted to read _all_ metrics available via the Metrics API.
​
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`.
​
Further scopes and requirements may be added at the discretion of the Agency, depending on their particular access control needs.
### For Providers hosting the Metrics API
Follow the pattern outlined in Provider API [auth](../provider/auth.md) document.
Collapse

[Top][toc]

Expand All @@ -50,7 +61,7 @@ Some combinations of dimensions, filters, time, and geography may return a small

If the query returns less than `10` trips in its count, then a `rows` value `number` of `-1` is returned.

The k-value is always returned in the Metrics Query API [response](/metrics#response-1) to provider important context for the data consumer on the data redaction that is occuring.
The k-value 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 occuring.

[Top][toc]

Expand Down Expand Up @@ -79,6 +90,7 @@ None.
| `filters` | string[] | Yes | List of supported filters for metrics. [See filters.](core_metrics.md#filters) |

### Response Schema

```js
{
"metrics": [
Expand All @@ -93,6 +105,7 @@ None.
"filters": [string]
}
```

See the [Metrics Examples](examples) for ways these can be implemented.

[Top][toc]
Expand All @@ -107,17 +120,17 @@ Supports querying one or more metrics with the following parameters.

### Parameters

| Name | Type | Required | Comments |
| --------------- | ------------- | -------- | ----------------------------------------------------------------------- |
| `measures` | string[] | Yes | list of measures to return. [See metric names](core_metrics.md) |
| `interval` | duration | Yes | Duration for metrics intervals. |
| `start_date` | datetime | Yes | ISO 8601 formatted start date or numeric timestamp to fetch metrics. |
| `end_date` | datetime | No | ISI 8601 formatted end date or numberic timestamp to fetch metrics. |
| `timezone` | timezone | No | TZ Database time zone name (default: "UTC") |
| `dimensions` | string[] | No | List of dimension names. [See dimensions.](core_metrics.md#dimensions) |
| `filters` | filter[] | No | Filters for metrics to return of format [See filters.](core_metrics.md#filters) |
| `filter.name` | string | No | Name of filter (e.g. 'vehicle_type') |
| `filter.values` | string[] | No | List of values to filter for (e.g ['car', 'moped']) |
| Name | Type | Required | Comments |
| --------------- | -------- | -------- | ------------------------------------------------------------------------------- |
| `measures` | string[] | Yes | list of measures to return. [See metric names](core_metrics.md) |
| `interval` | duration | Yes | Duration for metrics intervals. |
| `start_date` | datetime | Yes | ISO 8601 formatted start date or numeric timestamp to fetch metrics. |
| `end_date` | datetime | No | ISI 8601 formatted end date or numberic timestamp to fetch metrics. |
| `timezone` | timezone | No | TZ Database time zone name (default: "UTC") |
| `dimensions` | string[] | No | List of dimension names. [See dimensions.](core_metrics.md#dimensions) |
| `filters` | filter[] | No | Filters for metrics to return of format [See filters.](core_metrics.md#filters) |
| `filter.name` | string | No | Name of filter (e.g. 'vehicle_type') |
| `filter.values` | string[] | No | List of values to filter for (e.g ['car', 'moped']) |

Note: If `timezone` is specified then `start_date`, `end_date`, and all _datetime_ column values will be
converted to the specified time zone. If not, parameters will be converted to and the results will be
Expand Down Expand Up @@ -149,6 +162,7 @@ All named fields are required to be returned in response. Non-relevant values ca
| `rows` | values[][] | Array of row arrays containing the dimension and metric values. |

### Response Schema

```js
{
"id": string,
Expand Down
65 changes: 33 additions & 32 deletions metrics/core_metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,50 +12,51 @@ The core metrics are a set of defined, consistent MDS metrics definitions that p

# Metrics Definitions

The table below represents supported MDS core metrics and definition. All metrics are aggregated by time interval and geographic areas. This [document](https://docs.google.com/document/d/1rOhnaKWPSZApfWhFd1lzurXMbWLuZTJAYCLoxT2PQ14/edit?usp=sharing) provides methodologies and sample calculations of MDS metrics.

|Number| Metric | Description |
|------|-----------------------|----------------|
| 1.1 | vehicles.[status].avg | The average number of vehicles in [MDS status](/agency#vehicle-events). |
| 1.2 | vehicles.[status].min | The minimum number of vehicles in [MDS status](/agency#vehicle-events). |
| 1.3 | vehicles.[status].max | The maximum number of vehicles in [MDS status](/agency#vehicle-events). |
| 1.4 | vehicles.[status].duration.sum | The total duration (in seconds) vehicles spent in a specified [MDS status](/agency#vehicle-events). |
| 1.5 | events.[event_type].count | The number of [MDS event type](/agency#vehicle-events) received. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
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.

| Number | Metric | Description |
| ------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| 1.1 | vehicles.[status].avg | The average number of vehicles in [MDS status](/agency#vehicle-events). |
| 1.2 | vehicles.[status].min | The minimum number of vehicles in [MDS status](/agency#vehicle-events). |
| 1.3 | vehicles.[status].max | The maximum number of vehicles in [MDS status](/agency#vehicle-events). |
| 1.4 | vehicles.[status].duration.sum | The total duration (in seconds) vehicles spent in a specified [MDS status](/agency#vehicle-events). |
| 1.5 | events.[event_type].count | The number of [MDS event type](/agency#vehicle-events) received. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |

[Top][toc]

## Dimensions

The following represent the suggested MDS core metric dimensions:

| Dimension | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| provider_id | Transportation provider id issued by OMF and [tracked here](/providers.csv) |
| [geography_type](/geography#geography-type) | [MDS Geography](/geography) e.g. policy, jurisdictions, council_districts |
| vehicle_type | [Vehicle Type](/agency#vehicle-type) defined by MDS |
| special_group_type | [Special Group Type](#special-group-type) defined by MDS |
| Dimension | Description |
| ------------------ | --------------------------------------------------------------------------- |
| 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]

## Filters

The following represent the suggested MDS core metric filters:

| Filter | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| 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 |
| Filter | Description |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| provider_id | Transportation provider id issued by OMF and [tracked here](/providers.csv) |
| geography_id | [MDS Geography](/geography) |
| geography_type | [MDS Geography Type](/geography#geography-type) e.g. census_block, jurisdiction, council_district |
| vehicle_type | [Vehicle Type](/agency#vehicle-type) defined by MDS |
| special_group_type | [Special Group Type](#special-group-type) defined by MDS |

[Top][toc]

Expand All @@ -65,8 +66,8 @@ Special groups of riders can be optionally queried and counts can be returned in

Here are the possible values for the `special_group_type` field:

| Name | Description |
|------|------|
| 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. |

Other special group types may be added in future MDS releases as relevant agency and provider use cases are identified.
Expand Down
Loading