MDS 2.0

This section describes the Mobility Data Specification (MDS) provider API, explained in full on the Open Mobility Foundation's GitHub v2.0.

Authentication

$ curl -H "X-Access-Token: $API_KEY" \
     api.voiapp.io/v1/partner-apis/mds/1/trips?end_time=2024-06-13T10

All MDS and GBFS API endpoints are protected with API key authentication. Include your API key in the X-Access-Token request header on every request.

Contact our engineering support to receive your API key.

Header Parameters

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

Legacy Authentication (deprecated)

warning

The previous OAuth 2.0 client_credentials authentication method 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.

Previously, OAuth 2.0's client_credentials grant type was used to obtain a Bearer token via POST api.voiapp.io/v1/partner-apis/token. This method is now replaced by the API key approach 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+json;version=2.0.

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

warning

Current MDS 2.0 implementation only supports versions 2.0, for version 1.2 or 0.4 see here.

Key	Value
Accept	application/vnd.mds+json;version=2.0

Trips

A trips request.

# v2.0
$ curl -H "Accept: application/vnd.mds+json;version=2.0"
  api.voiapp.io/v1/partner-apis/mds/1/trips?end_time=2024-06-13T10

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

A trips response.

{
    "last_updated": {
        "last_updated": 1722932136606
    },
    "ttl": {
        "ttl": 0
    },
    "version": "2.0.0",
    "trips": [
        {
            "accessibility_attributes": [],
            "device_id": "d48ac4f0-d971-4cd0-be18-9658ebde9c75",
            "distance": 8329,
            "duration": 1652,
            "end_location": {
                "lat": 59.306113,
                "lng": 18.107582
            },
            "end_time": 1718272978417,
            "provider_id": "1f129e3f-158f-4df5-af9c-a80de238e334",
            "start_location": {
                "lat": 59.311543,
                "lng": 18.059523
            },
            "start_time": 1718271326209,
            "trip_id": "95ba3c85-8087-457d-9fed-8469ffb2dad7",
            "trip_type": [
                "rider"
            ]
        }
    ]
}

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 v2.0.

HTTPS request

GET api.voiapp.io/v1/partner-apis/mds/{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

Vehicles

A vehicles request.

# v2.0 - All vehicles
$ curl -H "Accept: application/vnd.mds+json;version=2.0"
  api.voiapp.io/v1/partner-apis/mds/1/vehicles

# V2.0 - Single device
$ curl -H "Accept: application/vnd.mds+json;version=2.0"
  api.voiapp.io/v1/partner-apis/mds/1/vehicles/703af7e8-ac8c-5543-b2ac-64ef52812d19

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

A vehicles response.

{
    "version": "2.0.0",
    "vehicles": [
        {
            "device_id": "703af7e8-ac8c-5543-b2ac-64ef52812d19",
            "maximum_speed": 20,
            "propulsion_types": [
                "electric"
            ],
            "provider_id": "1f129e3f-158f-4df5-af9c-a80de238e334",
            "vehicle_id": "b383",
            "vehicle_type": "scooter_standing"
        },
    ],
    "links": {}
}

The status of the inventory of vehicles available for customer use. The /vehicles endpoint returns all vehicles in the zone and their type.

See Open Mobility Foundation's MDS description on status changes v2.0.

HTTPS request

To fetch all vehicles in a zoneID GET api.voiapp.io/v1/partner-apis/mds/{zoneID}/vehicles

Optionally to fetch the status of a single device GET api.voiapp.io/v1/partner-apis/mds/{zoneID}/vehicles/{deviceID}

Path parameters

parameter	description	presence
zoneID	The zone id for the requested status changes	required
deviceID	A specific deviceID to request	optional

Vehicle Status

A vehicle status request.

# v2.0 - All vehicles
$ curl -H "Accept: application/vnd.mds+json;version=2.0"
  api.voiapp.io/v1/partner-apis/mds/1/vehicles/status

# v2.0 - Single device 
$ curl -H "Accept: application/vnd.mds+json;version=2.0"
  api.voiapp.io/v1/partner-apis/mds/1/vehicles/status/6aca5a87-60e9-51eb-8147-c38b58100c83

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

A vehicle status response.

{
    "last_updated": {
        "last_updated": 0
    },
    "ttl": {
        "ttl": 0
    },
    "version": "2.0.0",
    "vehicles_status": [
        {
            "device_id": "6aca5a87-60e9-51eb-8147-c38b58100c83",
            "last_event": {
                "battery_percent": 54,
                "device_id": "6aca5a87-60e9-51eb-8147-c38b58100c83",
                "event_id": "276ced41-0b6d-482a-85b0-84755b7dc97f",
                "event_types": [
                    "trip_end"
                ],
                "location": {
                    "lat": 59.31385,
                    "lng": 18.075726
                },
                "provider_id": "1f129e3f-158f-4df5-af9c-a80de238e334",
                "timestamp": 1722841638075,
                "trip_ids": [
                    "9456de24-eb22-46bb-b8af-b114b29d496e"
                ],
                "vehicle_state": "available"
            },
            "last_telemetry": {
                "battery_percent": 50,
                "device_id": "6aca5a87-60e9-51eb-8147-c38b58100c83",
                "journey_id": null,
                "location": {
                    "lat": 59.31388,
                    "lng": 18.075653
                },
                "provider_id": "1f129e3f-158f-4df5-af9c-a80de238e334",
                "telemetry_id": "926adb5b-45a2-51e3-a9d4-dbd472f50d31",
                "timestamp": 1722932388272,
                "trip_ids": null
            },
            "provider_id": "1f129e3f-158f-4df5-af9c-a80de238e334"
        }
    ]
}

The status of the inventory of vehicles available for customer use. The /vehicles/status endpoint returns all vehicles in the zone along with their most recent event and telemetry.

See Open Mobility Foundation's MDS description on status changes v2.0.

HTTPS request

To fetch all vehicles in a zoneID GET api.voiapp.io/v1/partner-apis/mds/{zoneID}/vehicles/status

Optionally to fetch the status of a single device GET api.voiapp.io/v1/partner-apis/mds/{zoneID}/vehicles/status/{deviceID}

Path parameters

parameter	description	presence
zoneID	The zone id for the requested status changes	required
deviceID	A specific deviceID to request	optional

Events, recent

A recent events request.

# v2.0
$ curl -H "Accept: application/vnd.mds+json;version=2.0"
  api.voiapp.io/v1/partner-apis/mds/1/events/recent?start_time=1722931200000&end_time=1722934800000

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

A recent events response.

{
    "last_updated": {
        "last_updated": 1722935579741
    },
    "ttl": {
        "ttl": 0
    },
    "version": "2.0.0",
    "events": [
        {
            "battery_percent": 33,
            "device_id": "1786c844-82e7-5fcd-88cf-e2b0869030d5",
            "event_id": "222117b0-8cbb-4021-9eb7-799522ae9b54",
            "event_types": [
                "trip_start"
            ],
            "location": {
                "lat": 59.33512,
                "lng": 18.067327
            },
            "provider_id": "1f129e3f-158f-4df5-af9c-a80de238e334",
            "timestamp": 1722931201181,
            "trip_ids": [
                "504387ca-ac49-4198-845f-76e508fd5b73"
            ],
            "vehicle_state": "on_trip"
        },
    ],
    "links": {}
}

The /events/recent endpoint is a near real-time feed of status changes, designed to give access to as recent as possible series of events. The recent endpoint only provides data up to two weeks back in time. For more data, see Historical events

The /events/recent endpoint functions similarly to /vehicles/status.

See Open Mobility Foundation's MDS description of recent events v2.0.

HTTPS request

GET api.voiapp.io/v1/partner-apis/mds/{zoneID}/events/recent

Path parameters

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

Query parameters

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

Events, historical

A recent events request.

# v2.0
$ curl -H "Accept: application/vnd.mds+json;version=2.0"
  api.voiapp.io/v1/partner-apis/mds/1/events/historical?event_time=2024-06-13T10

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

A historical events response.

{
    "last_updated": {
        "last_updated": 1722935878725
    },
    "ttl": {
        "ttl": 0
    },
    "version": "2.0.0",
    "events": [
        {
            "battery_percent": 84,
            "device_id": "5a90ff25-a0eb-5995-a7e5-dc2f29091cd0",
            "event_id": "5e61f822-46e1-462f-bbbe-9e8e8fd51191",
            "event_types": [
                "trip_start"
            ],
            "location": {
                "lat": 59.314285,
                "lng": 18.063965
            },
            "provider_id": "1f129e3f-158f-4df5-af9c-a80de238e334",
            "timestamp": 1718272800160,
            "trip_ids": [
                "f4249d42-80ae-467c-90cc-8b53bc070054"
            ],
            "vehicle_state": "on_trip"
        },
    ],
    "links": {}
}

The /events/historical endpoint is a hourly historical version of the recent events. It provides data that is older than two weeks (can also query data newer than two weeks) in chunks of one hour.

See Open Mobility Foundation's MDS description of historical events v2.0.

HTTPS request

GET api.voiapp.io/v1/partner-apis/mds/{zoneID}/events/historical

Path parameters

parameter	description	presence
zoneID	The zone id for the requested events	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

Authentication​

Header Parameters​

Legacy Authentication (deprecated)​

Versioning​

Header​

Trips​

HTTPS request​

Path parameters​

Query parameters​

Vehicles​

HTTPS request​

Path parameters​

Vehicle Status​

HTTPS request​

Path parameters​

Events, recent​

HTTPS request​

Path parameters​

Query parameters​

Events, historical​

HTTPS request​

Path parameters​

Query parameters​

Authentication

Header Parameters

Legacy Authentication (deprecated)

Versioning

Header

Trips

HTTPS request

Path parameters

Query parameters

Vehicles

HTTPS request

Path parameters

Vehicle Status

HTTPS request

Path parameters

Events, recent

HTTPS request

Path parameters

Query parameters

Events, historical

HTTPS request

Path parameters

Query parameters