Mobility Data Specification: Agency

The Agency API endpoints are intended to be implemented by regulatory agencies and consumed by mobility providers. Data is pushed to agencies by providers. Providers query the Agency API when events (such as a trip start or vehicle status change) occur in their systems.

This specification contains a collection of RESTful APIs used to specify the digital relationship between mobility as a service providers and the agencies that regulate them.

Table of Contents

General Information
Vehicles
Trips
Telemetry
Events
Stops
Reports
- Reports - Register

General information

This specification uses data types including timestamps, UUIDs, and vehicle state definitions as described in the MDS General Information document.

Authorization

MDS Agency endpoint producers SHALL provide authorization for API endpoints via a bearer token based auth system. When making requests, the endpoints expect provider_id to be part of the claims in a JSON Web Token (JWT) access_token in the Authorization header, in the form Authorization: Bearer <access_token>. The token issuance, expiration and revocation policies are at the discretion of the agency. JSON Web Token is the recommended format.

General authorization details are specified in the Authorization section in MDS General Information.

Versioning

Agency APIs must handle requests for specific versions of the specification from clients.

Versioning must be implemented as specified in the Versioning section.

Modes

MDS is intended to be used for multiple transportation modes, including its original micromobility (e-scooters, bikes, etc.) mode, as well as additional modes such as taxis, car share, and delivery bots. A given provider_id shall be associated with a single mobility mode, so that the mode does not have to be specified in each data structure and API call. A provider implementing more than one mode shall register a unique provider_id for each mode.

Responses and Error Messages

The response to a client request must include a valid HTTP status code defined in the IANA HTTP Status Code Registry.

The response must set the Content-Type header as specified in the Versioning section.

Response bodies must be a UTF-8 encoded JSON object

See the Responses, Error Messages, and Bulk Responses sections, and the schema for more details.

GBFS

See the GBFS Requirement language for more details.

Data Schema

See the Endpoints below for information on their specific schema, and the mds-openapi repository for full details and interactive documentation.

Vehicles

The /vehicles endpoints allow providers to register and update the properties of their fleet vehicles, and query current vehicle properties and status.

Vehicle - Register

The /vehicles registration endpoint is used to register vehicles for use in the Agency's jurisdiction.

Endpoint: /vehicles
Method: POST
Payload: An array of Vehicles

Responses

Possible HTTP Status Codes: 201, 400, 401, 406, 409, 500

See Responses, Bulk Responses, and schema for details.

Error Codes:

`error`	`error_description`	`error_details`[]
`bad_param`	A validation error occurred	Array of parameters with errors
`missing_param`	A required parameter is missing	Array of missing parameters
`already_registered`	A vehicle with `device_id` is already registered

Vehicle - Update

The /vehicles update endpoint is used to change vehicle information, should some aspect of the vehicle change, such as the vehicle_id. Each vehicle must already be registered.

Endpoint: /vehicles
Method: PUT
Payload: An array of Vehicles

Responses

Possible HTTP Status Codes: 200, 400, 401, 406, 409, 500

See Responses, Bulk Responses, and schema for details.

Error Codes:

`error`	`error_description`	`error_details`[]
`bad_param`	A validation error occurred	Array of parameters with errors
`unregistered`	This `device_id` is unregistered

Vehicle - List

The /vehicles endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles. Providers can only retrieve data for vehicles in their registered fleet. Contains vehicle properties that do not change often.

Endpoint: /vehicles/{device_id}
Method: GET
Payload: An array of Vehicles

Path Parameters:

Path Parameters	Type	Required/Optional	Description
`device_id`	UUID	Optional	If provided, retrieve the specified vehicle

If device_id is specified, GET will return an array with a single vehicle record, otherwise it will be a list of vehicle records with pagination details per the JSON API spec:

{
    "version": "2.0.0",
    "vehicles": [ ... ]
    "links": {
        "first": "https://...",
        "last": "https://...",
        "prev": "https://...",
        "next": "https://..."
    }
}

Responses

Possible HTTP Status Codes: 200, 400 (with parameter), 401, 404, 406, 500

See Responses, Bulk Responses, and schema for details.

Vehicle - Status

The /vehicles/status endpoint returns information about the specified vehicle (if a device_id is provided) or a list of known vehicles current state. Providers can only retrieve data for vehicles in their registered fleet. Contains specific vehicle properties that are updated frequently.

Endpoint: /vehicles/status/{device_id}
Method: GET
Payload: An array of Vehicles objects

Path Parameters:

Path Parameters	Type	Required/Optional	Description
`device_id`	UUID	Optional	If provided, retrieve the specified vehicle

If device_id is specified, GET will return an array with a vehicle status record, otherwise it will be a list of vehicle records with pagination details per the JSON API spec:

{
    "version": "2.0.0",
    "vehicles_status": [ ... ]
    "links": {
        "first": "https://...",
        "last": "https://...",
        "prev": "https://...",
        "next": "https://..."
    }
}

Responses

Possible HTTP Status Codes: 200, 400 (with parameter), 401, 404, 406, 500

See Responses, Bulk Responses, and schema for details.

Trips

The Trips endpoint serves two purposes:

Definitively indicating that a Trip (a sequence of events linked by a trip_id) has been completed. For example, from analyzing only the raw Vehicle Events feed, if a trip crosses an Agency's jurisdictional boundaries but does not end within the jurisdiction (last event_type seen is a leave_jurisdiction), this can result in a 'dangling trip'. The Trips endpoint satisfies this concern, by acting as a final indication that a trip has been finished, even if it ends outside of jurisdictional boundaries; if a trip has intersected an Agency's jurisdictional boundaries at all during a trip, it is expected that a Provider will send a Trip payload to the Agency following the trip's completion.
Providing information to an Agency regarding an entire trip, without extending any of the Vehicle Event payloads, or changing any requirements on when Vehicle Events should be sent.

Endpoint: /trips
Method: POST
Payload: Array of Trips

Responses

Possible HTTP Status Codes: 201, 400, 401, 404, 406, 500

See Responses, Bulk Responses, and schema for details.

Trip Errors:

`error`	`error_description`	`error_details`[]
`bad_param`	A validation error occurred	Array of parameters with errors
`missing_param`	A required parameter is missing	Array of missing parameters
`unregistered`	This `device_id` is unregistered

Telemetry

The vehicle /telemetry endpoint allows a Provider to send vehicle telemetry data in a batch for any number of vehicles in the fleet.

Endpoint: /telemetry
Method: POST
Payload: An array of vehicle Telemetry

Responses

Possible HTTP Status Codes: 201, 400, 401, 404, 406, 500

See Responses, Bulk Responses, and schema for details.

Telemetry Errors:

`error`	`error_description`	`error_details`[]
`bad_param`	A validation error occurred	Array of parameters with errors
`missing_param`	A required parameter is missing	Array of missing parameters
`unregistered`	This `device_id` is unregistered

Events

The vehicle /events endpoint allows the Provider to submit events describing the state changes of multiple vehicles.

Endpoint: /events
Method: POST
Payload: An array of vehicle Events

Responses

Possible HTTP Status Codes: 201, 400, 401, 404, 406, 500

See Responses, Bulk Responses, and schema for details.

Event Errors:

`error`	`error_description`	`error_details`[]
`bad_param`	A validation error occurred	Array of parameters with errors
`missing_param`	A required parameter is missing	Array of missing parameters
`unregistered`	This `device_id` is unregistered

Stops

Stops - Register

The /stops endpoint allows an agency to register city-managed Stops, or a provider to register self-managed Stops.

Endpoint: /stops
Method: POST
Payload: An array of Stops

Responses

Possible HTTP Status Codes: 201, 400, 401, 406, 409, 500

See Responses, Bulk Responses, and schema for details.

Stops Register Errors:

`error`	`error_description`	`error_details`[]
`bad_param`	A validation error occurred	Array of parameters with errors
`missing_param`	A required parameter is missing	Array of missing parameters
`already_registered`	A stop with `stop_id` is already registered

403 Unauthorized Response:

None

Stops - Update

Endpoint: /stops
Method: PUT
Payload: An array of of Stop information, where the permitted changeable fields are defined as:

Field	Required/Optional	Description
stop_id	Required	See Stops
last_updated	Optional	See Stops
status	Optional	See Stops
rental_methods	Optional	See Stops
num_vehicles_available	Optional	See Stops
num_vehicles_disabled	Optional	See Stops
num_places_available	Optional	See Stops
num_places_disabled	Optional	See Stops
devices	Optional	See Stops

Responses

Possible HTTP Status Codes: 200, 400, 401, 404, 406, 500

See Responses, Bulk Responses, and schema for details.

Stops update Errors:

`error`	`error_description`	`error_details`[]
`bad_param`	A validation error occurred	Array of parameters with errors
`missing_param`	A required parameter is missing	Array of missing parameters
`unregistered`	No stop with `stop_id` is already registered

Stops - Readback

Endpoint: /stops/{stop_id}
Method: GET
Payload: An array of Stops

Path Parameters:

Path Parameters	Type	Required/Optional	Description
`stop_id`	UUID	Optional	If provided, retrieve the specified stop

If stop_id is specified, GET will return an array with a single stop record, otherwise it will be a list of all stop records.

Responses

Possible HTTP Status Codes: 200, 401, 404, 406, 500

See Responses, Bulk Responses, and schema for details.

Reports

Reports are 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. These supplemental reports are not a substitute for other MDS Provider endpoints.

The authenticated reports are monthly, historic flat files that may be pre-generated by the provider.

Reports - Register

The /reports endpoint allows an agency to register aggregated report counts in CSV structure.

Endpoint: /reports
Method: POST
Payload: A CSV of Reports

Responses

Possible HTTP Status Codes: 201, 400, 401, 406, 500

See Responses, Bulk Responses, and schema for details.

Reports Register Errors:

`error`	`error_description`	`error_details`[]
`bad_param`	A validation error occurred	Array of parameters with errors

400 Unauthorized Response:

None