Is your feature request related to a problem? Please describe.

There is currently no standard way to retrieve metrics calculated from MDS data (provider or agency) or to define a standard set of useful MDS-based data aggregations.  We have heard from the OMF community that this leads to a number of problems:

• Cities need a number of clearly defined best practice metrics for operating, measuring, and managing emerging micro-mobility, and other transportation 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 need consistent rules and measures between city deployments in order to make their operations more scalable.

Describe the solution you'd like

The proposed Metrics API is intended to help users of MDS - both cities, mobility service providers, and third-party ecosystem services - to have a standard way to consistently describe available metrics, and create an extensible interface for querying core MDS metrics and future metrics still to be defined.  It should be a framework to describe how different API users and hosts can:

1. Define and communicate available metrics;
2. Request these metrics across multiple dimensions and filters;
3. Serve these metrics either to external parties or to other MDS API consumers, without requiring the transmission of the underlying raw data;
4. Ensure that multiple parties can reliably reproduce the same metrics, given the same data

The goal is to be able to define “Metric X” and then ensure that when “X” is calculated by the city, authorized parties, or transportation providers, the result will be identical. For example, while n different methods may exist to calculate the utilization of a vehicle or a fleet for a given time range, the Metrics API is intended to ensure that for given method k, the same result will be produced regardless of who conducts the calculation, and there is a standard interface for authorized users to receive this data without requiring access to underlying raw data.

The Metrics API is intended to be useful for future MDS use cases, best practices and requirements.  Particularly notable is that it provides the foundation to implement data anonymization best practices, such as k-anonymity.  It also represents an important component needed to enable new MDS policy types and compliance evaluation as well as operations management use cases that can only be achieved by linking MDS metrics and MDS policy.

This proposed specification is not intended to represent a complete data pipeline or analytics service. It is also not meant to define the complete set of MDS metrics, only a useful starting point.

Is this a breaking change

• No, not breaking

Impacted Spec

• agency
• provider

Describe alternatives you've considered

It is hoped that this work can be complementary to other projects working to define, develop, and implement metrics services or metrics processing pipelines for MDS data.  Much of this proposal was inspired by excellent work done by OMF member cities and SharedStreets with their SharedStreets Mobility Metrics.

This proposal represents work done without full visibility into the efforts of the Mobility Data Collaborative (MDC).  We hope to bring the metrics defined in the Metrics Definitions PR to alignment with those MDC describes, once they become public.

Additional context

This specification received initial input from a variety of OMF contributors, representing city transportation departments (LADOT), ecosystem services stakeholders (Blue Systems, Lacuna, Ellis & Associates), and mobility service providers (Bird).  We hope it encourages discussion and creation in the OMF on this important subject.  A reference implementation of this API is not included at this time, but hopefully will be developed and contributed following additional community feedback.

Specific thanks to @bhandzo and @HenriJ.

Proposal consists of the following PRs
Metrics API PR #486 and Metrics Definitions PR #487