Skip to content

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 is by API key. You create the key yourself and hand it to the agency:

  1. In the console, open Settings and find API keys.
  2. Create a key with the mds:read scope. Label it with the agency’s name.
  3. 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-01T14
Authorization: Bearer hk_live_…
Accept: application/vnd.mds+json;version=2.0
  • A missing, wrong or revoked key returns 401.
  • A key without the mds:read scope, or a key from another network, returns 403.
  • Asking for any other MDS version in Accept returns 406.

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
  • Hourly queries are for closed hours. An hour that has not fully passed returns 404; a missing or malformed hour returns 400.
  • Telemetry is two points per trip, the start and the end. The route in between is not published.
  • Events are trip events. trip_start and trip_end are 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 /stops and /reports endpoints, are not offered.