goUrban has implemented MDS standards according to the best practices. Utilizing the latest versions (MDS v1.2.0) in our solution we have implemented our end-points to work with the proposed standards in a best practice outcome.
For more detail on the official documentation, please review the document below.
Accessing the endpoints
In regards to setting up the appropriate access, the operators have to get in touch with the goUrban team so that the relevant API access can be configured.
Pricing
There is a setup fee and a monthly fee for using MDS, please reach out to your account manager for further information.
About MDS
The Mobility Data Specification (MDS), a project of the Open Mobility Foundation (OMF), is a set of Application Programming Interfaces (APIs) focused on shared mobility services such as dockless scooters, bicycles, mopeds, and carshare, and inspired by projects like GTFS and GBFS. MDS is a digital tool that helps cities better manage transportation in the public right of way, standardizing communication and data-sharing between cities and private mobility providers, allowing cities to share and validate policy digitally, and enabling vehicle management and better outcomes for residents.
MDS is a key piece of digital infrastructure that supports the effective implementation of mobility policies in cities around the world.
Official documentation
Endpoints for MDS
MDS v1.2.0
Authentication
All of the listed provider endpoints require a bearer token which can be obtained in two different ways:
- pre-shared key generated by goUrban
- obtaining an access token through the OAuth2 flow with APIClient credentials (User API api-client endpoint).
https://user.api.gourban.services/v1/{tenant}/auth/sign-in-api-client
To get your credentials for access to a token retrieval get in touch with your customer success manager.
Header
The latest supported version is 1.2.0. When requesting information, the following header needs to be provided:
Accept: application/vnd.mds.provider+json;version=1.2.0
Base URL
The base URL is where all MDS endpoints can be found. The UUID part can be used to run multiple MDS endpoints for different cities in the same environment.
Note: MDS can be configured for “parent branches” (e.g. a country) which will include all child branches. This configuration can then be expanded to exclude specific branches (e.g. private branches).
Example: A link can be set up for “Austria”, which will include both child branches, “Vienna” and “Graz”. In this case, “Vienna” can be set up to be excluded which results in only “Austria” and “Graz” being used.
Austria - billable
Vienna - free floating
Graz - booking branch
Please check with your contact at goUrban to get the tenant and UUID to be used.
https://{tenant}.core.gourban.services/api/mds/{uuid}
Endpoints
Trips - official Docs
A trip represents a journey taken by a mobility as a service customer with a geo-tagged start and stop point.
The /trips?end_time=YYYY-MM-DDTHH endpoint allows a user to query trips that happened in the hour after the given timestamp.
Status Changes - official Docs
The /status_changes?event_time=YYYY-MM-DDTHH endpoint allows a user to query all the status changes that happened within the hour after the given timestamp.
Note: goUrban does not support the full range of status changes listed by the MDS standard.
Events - official Docs
The /events?start_time=YYYY-MM-DDTHH&end_time=YYYY-MM-DDTHH endpoint is a near-ish 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 shall not include data older than 2 weeks (that should live in /status_changes.)
Reports - official Docs
The /reports/YYYY-MM endpoint provides information that providers can send back to agencies containing aggregated data that is not contained within other MDS endpoints, like counts of special groups of riders.
The authenticated reports are monthly, historic flat files.
Vehicles - official Docs
The /vehicles is a near-real-time endpoint and returns the current status of vehicles in an agency's Jurisdiction and/or area of agency responsibility. All vehicles that are currently in any vehicle_state should be returned in this payload. Since all states are returned, care should be taken to filter out states not in the PROW if doing vehicle counts. For the states elsewhere and removed which include vehicles, not in the PROW but provide some operational clarity for agencies.
PROW - Public Right of Way - the physical infrastructure reserved for transportation purposes, examples include sidewalks, curbs, bike lanes, transit lanes and stations, traffic lanes and signals, and public parking.
Stops (currently not supported by the goUrban MDS implementation) - official Docs
The /stops endpoint provides a list of all designated “stops” in the system. They are referenced in the trip's endpoint if a trip is started and ended on designated “stops”. This is needed for shared fleets operated with docking stations.
Configuration
For initial setup and specific city, configuration operators should get in touch with support: support@gourban.co