The Mobility Data Specification offers three primary Application Programming Interfaces (APIs): agency, provider, and policy.
Both the agency and provider APIs allow agencies to gather data about vehicles and trips from a mobility mervice provider. Although the design of the APIs differ, they allow for similar types of data gathering. A city can adopt one or both of these APIs depending on their goals, tools, and resources. See our Policy Language Guidance for how to specify endpoint needs in your city policy documents.
| Agency API | Provider API | |
|---|---|---|
 |
 |
|
| Data flow | - Provider pushes data to an agency - Hosted by an agency |
-Agency pulls data from a provider - Hosted by a provider |
| Key benefits/features | - Designed for real-time data collection - Agency maintains an authoritative database of information reported by all providers - Designed to support real-time analysis and adaptive regulation - Available reference implementation and data auditing / verification tools |
- Designed to provide recent historical data and a snapshot of vehicle status - Easier to use - Lower IT complexity - Some historical data is available on request, which may reduce need for agencies to store data - Many available commercial and open source analysis tools |
| Drawbacks | - More complex to implement - Agency must operate or procure IT systems capable of handling real-time API calls - Data only published once, not available for re-ingestion - Agencies must store any data needed for future analysis or reporting - Fewer software vendors currently providing processing solutions |
- Harder to scale as datasets get larger - Agency needs to query each provider individually - Availability of all necessary historical data from providers is not guaranteed - Not intended to provide real-time data about events in the right-of-way |
| Who is it for | - Agencies focused on dynamic or real-time management of right-of-way - Agencies with technical capacity to run a more complex system and store sensitive data |
- Agencies focused on using historical data for planning or compliance - Agencies with more limited technical capacity or a desire to minimize technical complexity |
The agency and provider APIs were developed in alignment with each other, with shared terminology and a similar data model. While they will likely stay aligned at a high-level, they are part of an open source development process and it is possible that their features and functionality may diverge or align more in the future.
Public agencies should consider their goals and use cases when selecting software to ingest and analyze MDS data. Some software packages and vendors may only support agency or provider. Data sharing requirements in permits and regulations should specify which MDS API(s) the public agency intends to use.
The policy API allows agencies to express various types of regulation through an API and can be used in tandem with agency or provider.
| Policy API | |
|---|---|
 |
|
| Data flow | - Provider pulls policy information from an agency - Hosted by an agency |
| Key benefits/features | - Allows agency to publish geography-based regulations (ex: restricted riding/parking areas, vehicle caps, etc.) - Providers can automatically adjust their services/apps as policies change - Removes need to manually communicate policy changes to providers - Works via a static webpage or as a dynamic API |
| Drawbacks | - Some complex policies / rules may not be supported by API - Newer MDS API with limited software tools available to implement - Need to set provider expectations for how/when policies will change |
| Who is it for | - Agencies focused on dynamic or real-time management of right-of-way - Agencies with technical capacity to host and run this API |
Three additional APIs support the core MDS APIs:
geography- Geography API looks at spatial coverage and boundaries that define where the rules set out in the Policy API apply or that trigger data logging and reporting in the Agency, Provider and Metrics APIs (e.g. a geo-fenced zone where vehicle speeds are reduced or a boundary whose crossing initiates logging of vehicle trip characteristics).jurisdiction- Jurisdiction API is used to define and communicate hierarchical or overlapping administrative or operational areas associated with specific data access rights. This API also enables co-ordination among different agencies.metrics- Metrics API establishes common methodologies for creating indicators from MDS data. This API defines common indicator semantics and ensures that indicators are consistently being calculated. It thus provides the basis for consistent processing and the production of comparable outputs raw data on the mobility operator side that can be incorporated into data-reporting mandates.