MDS Provider API
Herd implements the MDS Provider API, version 2.0, in micromobility mode. It gives a city’s data team vehicles, trips and trip events for one network.
Access
Section titled “Access”Access is by API key. You create the key yourself and hand it to the agency:
- In the console, open Settings and find API keys.
- Create a key with the
mds:readscope. Label it with the agency’s name. - Copy the key, which is shown once, and send it to the agency by a secure channel.
Creating keys needs the Admin role. A key reads your network’s MDS feeds and no other network’s. Revoke it from the same screen when the agency no longer needs it.
GET /mds/{network}/trips?end_time=2026-05-01T14Authorization: Bearer hk_live_…Accept: application/vnd.mds+json;version=2.0- A missing, wrong or revoked key returns
401. - A key without the
mds:readscope, or a key from another network, returns403. - Asking for any other MDS version in
Acceptreturns406.
Endpoints
Section titled “Endpoints”All are GET under /mds/{network}.
| Path | Returns |
|---|---|
/vehicles and /vehicles/{device_id} |
Each vehicle and its propulsion type |
/vehicles/status and /vehicles/status/{device_id} |
Each vehicle’s latest event and position |
/trips?end_time=YYYY-MM-DDTHH |
Trips that ended in that UTC hour |
/telemetry?telemetry_time=YYYY-MM-DDTHH |
Trip start and end points for that UTC hour |
/events/historical?event_time=YYYY-MM-DDTHH |
trip_start and trip_end events for that UTC hour |
/events/recent?start_time=<ms>&end_time=<ms> |
The same events for a window within the last two weeks |
Limits to plan around
Section titled “Limits to plan around”- Hourly queries are for closed hours. An hour that has not fully passed returns
404; a missing or malformed hour returns400. - Telemetry is two points per trip, the start and the end. The route in between is not published.
- Events are trip events.
trip_startandtrip_endare reported. Maintenance and rebalancing events are not. - Bikes in use are left out of
/vehicles/status. A bike on a ride is where its rider is, so its live position is not published. - No rider data. Nothing in the MDS responses identifies a rider.
- The Agency, Policy and Geography APIs, and the Provider
/stopsand/reportsendpoints, are not offered.