MDS: the API contract cities and mobility operators use to talk to each other

The problem is that every city and every operator writes its own integration

The Mobility Data Specification is described as a set of Application Programming Interfaces that helps cities better manage transportation in the public right of way, standardising communication and data sharing between cities and mobility providers, allowing cities to share and validate policy digitally, and enabling vehicle management and better outcomes for residents.

The scope of mobility it covers is broad. The README lists dockless scooters, bicycles, mopeds, car share, food and goods delivery, sidewalk robots, fixed route services and shuttles, fleets, busses, and passenger services like taxis, transportation network companies and for-hire autonomous vehicles. The topic tags match that list, with scooter-share, bike-share, carshare, delivery-robot, robotaxi, micromobility, taxi, TNC and fixed-route among them.

The reason a specification like this exists is straightforward economics. A city with forty operators in its right of way would otherwise need forty integrations, each one custom, each one breaking when the operator changes their fleet. A shared contract turns that into one implementation per side. The README states the adoption figures directly, describing MDS as a global standard in use by over 200 mobility operators, operating in over 1,200 cities globally, with over 2 billion trips sent.

The lineage is stated too, and it explains the design. MDS was originally created by the Los Angeles Department of Transportation in 2018, and in November 2019 stewardship and repository ownership transferred to the Open Mobility Foundation. The project says it was inspired in part by GTFS and GBFS, the two well-known public transport and bikeshare feed specifications, so it is a deliberate descendant of that family of static feed formats.

The audience is a public agency or a mobility operator with enough scale that bespoke integrations have become a burden.

Six APIs, and the direction of data flow is the thing to understand

MDS is made up of six distinct APIs, each with multiple endpoints, and the design turns on who pulls and who pushes.

The provider API is intended to be implemented by mobility providers and consumed by regulatory agencies. Data is pulled from providers by agencies, and when a municipality queries a provider, the Provider API gives historical and recent views of operations. It was first released in June 2018, which makes it the oldest part of the specification.

The agency API is the mirror image. It is implemented by agencies and consumed by providers, with data pushed to agencies by providers, so an agency sees when events such as a trip start or a vehicle status change occur in provider systems in real time. First released April 2019.

The policy API lets agencies publish information about local rules, events or emergencies that affect mobility services or which may be used to determine compliance. It is implemented by agencies and consumed by providers, and the data can be pulled from agencies or pushed to providers. Released October 2019.

The geography API is also released from October 2019, as part of the Policy specification, and gives providers information about geographical regions for regulatory purposes. The jurisdiction API, from March 2021, lets cities communicate boundaries to each other and to mobility providers, which is the piece that matters when an operating area crosses a city line. The metrics API, also from March 2021, gives agencies a standard way to describe available metrics and an extensible interface for querying them.

So an agency that wants trip and vehicle history pulls from providers, and a provider that wants to know about a local rule pulls or receives from agencies. Getting this wrong is the most common way to mis-implement MDS, and it is why the README points to a separate guide, Understanding the different MDS APIs, in the governance repository.

It is a kit of parts, not a mandatory bundle

One design decision stands out: MDS is designed to be a modular kit of parts, and an agency may choose to use only the agency, provider and policy APIs, with geography, jurisdiction and metrics used in coordination with those or sometimes on their own. An agency may also select specific endpoints from each API rather than the whole thing.

That is a pragmatic choice for a specification used by hundreds of organisations with wildly different regulatory needs. A city that only wants to know where scooters are does not have to implement the jurisdiction API, and a small operator does not have to implement metrics. The cost is that the specification is less uniform than a single API would be, and an implementer has to make choices about scope.

Many parts of the definitions align across the APIs, and for the shared parts the consolidated information lives on a General Information page, referenced from the repository as general-information.md. That file is the join between the APIs: shared data types, shared identifiers, and the conventions that let a vehicle or a trip be referred to consistently across the provider, agency and policy flows.

The development process is also part of the story. Development of the APIs takes place under the guidance of the Open Mobility Foundation's MDS Working Group, which is a wiki page in the same repository. The repository itself shows the shape of the work: a directory per API at the root, each with its own endpoints, plus a modes/ directory, a schema/ directory, and a data-types.md file at the root. There are also agencies.csv and providers.csv at the root, which are registries of the organisations using the specification, and that is where a new implementer would find the counterparties already on the network.

Public feeds come on top of the APIs, not instead of them

There is a requirement that is easy to miss and that shapes the implementation work more than anything else in the specification.

All MDS compatible provider and agency feeds must also expose a public GBFS feed for the micromobility and fleet modes, and a public GOFS feed for passenger mode. A public feed, in this context, is a static file on a web server that anyone can fetch, and it is the mechanism that makes vehicle positions and availability visible to the public and to third party applications without any credentials.

So an MDS implementation is two things at once. There is the authenticated, real-time, event-oriented side, which is the six APIs, and there is the public, static, anonymous side, which is the GBFS and GOFS feeds. The static feeds are what a city publishes for residents and apps, and the APIs are what a regulator uses to enforce and coordinate.

That distinction has consequences. A GBFS feed is a periodic file dump, easy to serve and easy to consume, and it is the part most people interact with. The API side is bidirectional and eventful, and it is the part that requires agreement between two parties about endpoint behaviour, authentication and data semantics.

The modes directory in the repository is where the differences live. The README notes that the feeds are required for the micromobility and fleet modes and GOFS for passenger mode, which implies the requirement is mode-specific rather than universal, and the modes directory presumably enumerates the mode definitions that the rest of the specification refers to. A team implementing MDS for a passenger service and a team implementing it for scooters are working against different public feed requirements.

Adopting it means writing an implementation, not adding a dependency

This is the practical point that the README does not spell out, and it is the one an engineering team needs first.

MDS is a specification of APIs, not an implementation of them. The repository contains no client library, no server framework and no SDK. The top level listing is directories of endpoint definitions, a schema directory, CSV registries of participating agencies and providers, and governance documents such as CODEOWNERS, CONTRIBUTING.md, SECURITY.md, ReleaseGuidelines.md and ReleaseNotes.md.

The word schema in that listing is the one to pay attention to, because it points at the validation story. The table of contents has a Data Validation entry, and the schema directory is where the shapes of the payloads live. That means the practical path for an implementer is to read the endpoint definitions, implement the endpoints, and validate incoming and outgoing payloads against the published schemas. You get a contract and a conformance target, and you write the code.

There is also a version story. The release history shows 2.0.2 from 2025-06-04, 2.1.0 from 2026-07-09, and a 2.1.0 release candidate from 2026-04-16. The repository follows SemVer conventions in the sense that a 2.x line means breaking changes are limited to 2.0, but a specification with several APIs and many endpoints has a wide surface, and the release notes and guidelines in the repository are the place to look for what changed between versions. Your implementation, and the counterparty's implementation, will be on some version of this, and the version you agree on is part of your contract with them.

The project is also set up for contribution in the usual open governance way, with a code of conduct, a security policy, a contributing guide and a working group. That matters more for a specification than for a library, because conformance is a community process.

Where MDS is the wrong tool

The first wrong-tool case is a product that needs vehicle positions and nothing else. GBFS alone gives you that, as a static file, with no implementation work, no bilateral agreement and no agency in the middle. MDS is for the regulatory relationship, and if you do not have a regulatory relationship it is a lot of machinery for a file you could have served yourself.

The second case is a team that wants to consume mobility data rather than produce it. The provider and agency APIs are both defined from the point of view of the parties that operate the vehicles. A data aggregator that only wants to read is better served by the public feeds, and the README states that a GBFS or GOFS feed is required anyway, so the aggregator can use that without implementing anything from this specification.

The third case is a bilateral integration between exactly two parties who control both ends. Writing a small direct integration, where both sides agree on the payload, is often faster than agreeing on a shared specification, and there is no conformance to argue about. The specification pays off at the third and fourth counterparty, and the return on the implementation cost is a function of how many counterparties you expect.

The fourth case is a private fleet with no public right-of-way exposure. The specification is built around cities regulating shared space. An internal fleet with no agency relationship gains nothing from implementing six APIs.

There is also a data privacy dimension the README addresses in its own section, and it is worth reading before designing an implementation. The topic tags include policy-as-code, which is an interesting framing: the policy API is a mechanism for sharing rules digitally so that a provider's behaviour can be checked against them, and that mechanism has privacy consequences on both sides, since what a provider sends to an agency and what a city publishes about its rules are both partly sensitive.

On licensing, the repository carries both a LICENSE and a LICENSE file, and the project is reported as a custom licence that GitHub cannot classify. Since the specification is meant to be implemented by anyone including commercial operators, the permission grant is broad in practice, but a legal team deploying it should read those two files rather than assume an open source identifier, and the terms of the OMF as the steward are the thing to check.

Editorial conclusion

MDS suits a city or a mobility operator that is tired of one-off integrations and wants a documented contract with counterparties who have already adopted it, since the specification is versioned, publicly maintained and already in production with a large number of operators. It does not suit a product team that just needs a map of vehicle positions, since MDS has no client SDK and assumes both sides can host endpoints. Before adopting, read the mode definitions under modes/ and the data types in data-types.md, confirm your city or operator appears in agencies.csv or providers.csv if the list matters to you, and budget for the pull and push flows separately because the provider and agency APIs have opposite data directions.

Frequently asked questions

Official sources

1. Issues
2. openmobilityfoundation/mobility-data-specification on GitHub
3. Project website
4. README
5. Releases