MDS 1.2 and 0.4

This section describes the Mobility Data Specification (MDS) provider API, explained in full on the Open Mobility Foundation's GitHub v0.4 and v1.2.

Authentication

Authentication for MDS 1.2 and 0.4 uses the same API key method described in the MDS 2.0 Authentication section. Include your API key in the X-Access-Token request header.

Key	Value
X-Access-Token	your-api-key

Legacy Authentication (deprecated)

warning

The previous OAuth 2.0 client_credentials authentication via POST mds.voiapp.io/token is deprecated. Existing tokens will continue to work, but credentials will not be renewed upon expiration. Please migrate to the API key method described above.

Versioning

The MDS APIs handle requests for specific versions of the specification from the clients. Version is communicated through the use of a custom media-type, application/vnd.mds.provider+json or application/vnd.mds+json, combined with a required version parameter.

See Open Mobility Foundation's MDS description on versioning here.

warning

Current MDS implementation only supports versions 0.4 and 1.2

Header

Key	Value
Accept	application/vnd.mds.provider+json;version=0.4
Accept	application/vnd.mds+json;version=1.2

Trips

A trips request.

# v0.4
$ curl -H "Accept: application/vnd.mds.provider+json;version=0.4"
  mds.voiapp.io/en/9/trips?end_time=2020-01-01T23

# v1.2
$ curl -H "Accept: application/vnd.mds+json;version=1.2"
  mds.voiapp.io/en/9/trips?end_time=2020-01-01T23

Do not copy ^ as the zone-ID or Accept might not match yours

A trip represents a journey taken by a customer with a geo-tagged start and stop point. The `/trips endpoint allows a user to query historical trip data that happened within the queried hour.

See Open Mobility Foundation's MDS description on trips v0.4, v1.2.

HTTPS request

GET mds.voiapp.io/en/{zoneID}/trips

Path parameters

parameter	description	presence
zoneID	The zone id for the requested trips	required

Query parameters

parameter	description	presence
end_time	YYYY-MM-DDTHH, an ISO 8601 extended DateTime representing a UTC hour between 00 and 23.	required

Status Changes

A status changes request.

# v0.4
$ curl -H "Accept: application/vnd.mds.provider+json;version=0.4"
  mds.voiapp.io/en/9/status_changes?event_time=2020-01-01T23

# v1.2
$ curl -H "Accept: application/vnd.mds+json;version=1.2"
  mds.voiapp.io/en/9/status_changes?event_time=2020-01-01T23

Do not copy ^ as the zone-ID or Accept might not match yours

The status of the inventory of vehicles available for customer use. The /status_changes endpoint allows a user to query the historical availability for a system within the queried hour.

See Open Mobility Foundation's MDS description on status changes v0.4, v1.2.

HTTPS request

GET mds.voiapp.io/en/{zoneID}/status_changes

Path parameters

parameter	description	presence
zoneID	The zone id for the requested status changes	required

Query parameters

parameter	description	presence
event_time	YYYY-MM-DDTHH, an ISO 8601 extended DateTime representing a UTC hour between 00 and 23.	required

Events

An events request.

# v0.4
$ curl -H "Accept: application/vnd.mds.provider+json;version=0.4"
  mds.voiapp.io/en/9/events?start_time=1580518800000&end_time=1581123600000

# v1.2
$ curl -H "Accept: application/vnd.mds+json;version=1.2"
  mds.voiapp.io/en/9/events?start_time=1580518800000&end_time=1581123600000

Do not copy ^ as the zone-ID or Accept might not match yours

The /events endpoint is a near real-time feed of status changes, designed to give access to as recent as possible series of events.

The /events endpoint functions similarly to /status_changes, but does not include data older than 2 weeks.

See Open Mobility Foundation's MDS description of events v0.4, v1.2.

HTTPS request

POST mds.voiapp.io/en/{zoneID}/events

Path parameters

parameter	description	presence
zoneID	The zone id for the requested events	required

Query parameters

parameter	description	presence
end_time	timestamp, integer milliseconds since Unix epoch	required
start_time	timestamp, integer milliseconds since Unix epoch	required

Vehicles

An vehicles request.

# v0.4
$ curl -H "Accept: application/vnd.mds.provider+json;version=0.4"
  mds.voiapp.io/en/9/vehicles

# v1.2
$ curl -H "Accept: application/vnd.mds+json;version=1.2"
  mds.voiapp.io/en/9/vehicles

Do not copy ^ as the zone-ID or Accept might not match yours

The /vehicles endpoint returns the current status of vehicles on the PROW. Only vehicles that are currently in available, unavailable, or reserved states should be returned in this payload.

See Open Mobility Foundation's MDS description of events v0.4, v1.2.

HTTPS request

GET mds.voiapp.io/en/{zoneID}/vehicles

Path parameters

parameter	description	presence
zoneID	The zone id for the requested events	required