Mobility Data Specification: Agency

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.

Date: 19 Sep 2019
Version: BETA

General information

The following information applies to all agency API endpoints. Details on providing authorization to endpoints is specified in the Authorization section.

Versioning

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

Versioning must be implemented as specified in the General information versioning section.

Authorization

When making requests, the Agency API expects provider_id to be part of the claims in a 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.

Timestamps

As with the Provider API, timestamp refers to integer milliseconds since Unix epoch.

Strings

All String fields, such as vehicle_id, are limited to a maximum of 255 characters.

Vehicles

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.

Endpoint: /vehicles/{device_id} Method: GET

Path Params:

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

200 Success Response:

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

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

A vehicle record is as follows:

Field	Type	Field Description
`device_id`	UUID	Provided by Operator to uniquely identify a vehicle
`provider_id`	UUID	Issued by City and tracked
`vehicle_id`	String	Vehicle Identification Number (vehicle_id) visible on vehicle
`type`	Enum	Vehicle Type
`propulsion`	Enum[]	Array of Propulsion Type; allows multiple values
`year`	Integer	Year Manufactured
`mfgr`	String	Vehicle Manufacturer
`model`	String	Vehicle Model
`status`	Enum	Current vehicle status. See Vehicle Status
`prev_event`	Enum	Last Vehicle Event
`updated`	Timestamp	Date of last event update

404 Failure Response:

No content returned on vehicle not found.

Vehicle - Register

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

Endpoint: /vehicles Method: POST

Body Params:

Field	Type	Required/Optional	Field Description
`device_id`	UUID	Required	Provided by Operator to uniquely identify a vehicle
`vehicle_id`	String	Required	Vehicle Identification Number (vehicle_id) visible on vehicle
`type`	Enum	Required	Vehicle Type
`propulsion`	Enum[]	Required	Array of Propulsion Type; allows multiple values
`year`	Integer	Optional	Year Manufactured
`mfgr`	String	Optional	Vehicle Manufacturer
`model`	String	Optional	Vehicle Model

201 Success Response:

No content returned on success.

400 Failure Response:

`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

409 Failure Response:

`error`	`error_description`	`error_details`[]
`already_registered`	A vehicle with `device_id` is already registered

Vehicle - Update

The /vehicles update endpoint is used to update some mutable aspect of a vehicle. For now, only vehicle_id.

Endpoint: /vehicles/{device_id} Method: PUT

Body Params:

Field	Type	Required/Optional	Field Description
`vehicle_id`	String	Required	Vehicle Identification Number (vehicle_id) visible on vehicle

201 Success Response:

No content returned on success.

400 Failure Response:

`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

404 Failure Response:

No content returned if no vehicle matching device_id is found.

Vehicle - Event

The vehicle /event endpoint allows the Provider to control the state of the vehicle including deregister a vehicle from the fleet.

Endpoint: /vehicles/{device_id}/event Method: POST

Path Params:

Field	Type	Required/Optional	Field Description
`device_id`	UUID	Required	ID used in Register

Body Params:

Field	Type	Required/Optional	Field Description
`event_type`	Enum	Required	see Vehicle Events
`event_type_reason`	Enum	Required if Available	see Vehicle Events
`timestamp`	Timestamp	Required	Date of last event update
`telemetry`	Telemetry	Required	Single point of telemetry
`trip_id`	UUID	Optional	UUID provided by Operator to uniquely identify the trip. Required for `trip_start`, `trip_end`, `trip_enter`, and `trip_leave` event types

201 Success Response:

Field	Type	Field Description
`device_id`	UUID	UUID provided by Operator to uniquely identify a vehicle
`status`	Enum	Vehicle status based on posted `event_type`. See Vehicle Status

400 Failure Response:

`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`	Vehicle is not registered

Vehicles - 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: /vehicles/telemetry Method: POST

Body Params:

Field	Type	Required/Optional	Field Description
`data`	Telemetry[]	Required	Array of telemetry for one or more vehicles.

201 Success Response:

Field	Type	Field Description
`result`	String	Responds with number of successfully written telemetry data points and total number of provided points.
`failures`	Telemetry[]	Array of failed telemetry for zero or more vehicles (empty if all successful).

400 Failure Response:

`error`	`error_description`	`error_details`[]
`bad_param`	A validation error occurred.	Array of parameters with errors
`invalid_data`	None of the provided data was valid.
`missing_param`	A required parameter is missing.	Array of missing parameters

Vehicle Events

List of valid vehicle events and the resulting vehicle status if the event is sucessful. Note that to handle out-of-order events, the validity of the initial-status is not enforced. Events received out-of-order may result in transient incorrect vehicle states.

`event_type`	`event_type_reason`	description	valid initial `status`	`status` on success	status_description
`register`		Default state for a newly registered vehicle	`inactive`	`removed`	A vehicle is in the active fleet but not yet available for customer use
`service_start`		Vehicle introduced into service at the beginning of the day (if program does not operate 24/7)	`unavailable`	`available`	Vehicle is on the street and available for customer use.
`service_end`	`low_battery`, `maintenance`, `compliance`, `off_hours`	A vehicle is no longer available due to `event_type_reason`	`available`	`unavailable`
`provider_drop_off`		Vehicle moved for rebalancing	`removed`, `elsewhere`	`available`
`provider_pick_up`	`rebalance`, `maintenance`, `charge`, `compliance`	Vehicle removed from street and will be placed at another location to rebalance service	`available`, `unavailable`, `elsewhere`	`removed`
`city_pick_up`		Vehicle removed by city	`available`, `unavailable`	`removed`
`reserve`		Customer reserves vehicle	`available`	`reserved`	Vehicle is reserved or in use.
`cancel_reservation`		Customer cancels reservation	`reserved`	`available`
`trip_start`		Customer starts a trip	`available`, `reserved`	`trip`
`trip_enter`		Customer enters the municipal area managed by agency during an active trip.	`removed`, `elsewhere`	`trip`
`trip_leave`		Customer leaves the municipal area managed by agency during an active trip.	`trip`	`elsewhere`
`trip_end`		Customer ends trip and reservation	`trip`	`available`
`deregister`	`missing`, `decommissioned`	A vehicle is deregistered	`available`, `unavailable`, `removed`, `elsewhere`	`inactive`	A vehicle is deactivated from the fleet.

The diagram below shows the expected events and related status transitions for a vehicle:

Telemetry Data

A standard point of vehicle telemetry. References to latitude and longitude imply coordinates encoded in the WGS 84 (EPSG:4326) standard GPS or GNSS projection expressed as Decimal Degrees.

Field	Type	Required/Optional	Field Description
`device_id`	UUID	Required	ID used in Register
`timestamp`	Timestamp	Required	Date/time that event occurred. Based on GPS or GNSS clock
`gps`	Object	Required	Telemetry position data
`gps.lat`	Double	Required	Latitude of the location
`gps.lng`	Double	Required	Longitude of the location
`gps.altitude`	Double	Required if Available	Altitude above mean sea level in meters
`gps.heading`	Double	Required if Available	Degrees - clockwise starting at 0 degrees at true North
`gps.speed`	Float	Required if Available	Speed in meters / sec
`gps.accuracy`	Float	Required if Available	Accuracy in meters
`gps.hdop`	Float	Required if Available	Horizontal GPS or GNSS accuracy value (see hdop)
`gps.satellites`	Integer	Required if Available	Number of GPS or GNSS satellites
`charge`	Float	Required if Applicable	Percent battery charge of vehicle, expressed between 0 and 1

Enum Definitions

Area Types

`type`	Description
`unrestricted`	Areas where vehicles may be picked up/dropped off. A provider's unrestricted area shall be contained completely inside the agency's unrestricted area for the provider in question, but it need not cover the entire agency unrestricted area. See the provider version of the service areas endpoint
`restricted`	Areas where vehicle pick-up/drop-off is not allowed
`preferred_pick_up`	Areas where users are encouraged to pick up vehicles
`preferred_drop_off`	Areas where users are encouraged to drop off vehicles

Vehicle Type

`type`
`bicycle`
`car`
`scooter`
`moped`

Propulsion Type

`propulsion`	Description
`human`	Pedal or foot propulsion
`electric_assist`	Provides power only alongside human propulsion
`electric`	Contains throttle mode with a battery-powered motor
`combustion`	Contains throttle mode with a gas engine-powered motor

A vehicle may have one or more values from the propulsion, depending on the number of modes of operation. For example, a scooter that can be powered by foot or by electric motor would have the propulsion represented by the array ['human', 'electric']. A bicycle with pedal-assist would have the propulsion represented by the array ['human', 'electric_assist'] if it can also be operated as a traditional bicycle.

Responses

200: OK: operation successful.
201: Created: POST operations, new object created
400: Bad request.
401: Unauthorized: Invalid, expired, or insufficient scope of token.
404: Not Found: Object does not exist, returned on GET or POST operations if the object does not exist.
409: Conflict: POST operations when an object already exists and an update is not possible.
500: Internal server error: In this case, the answer may contain a text/plain body with an error message for troubleshooting.

Error Message Format

Field	Type	Field Description
`error`	String	Error message string
`error_description`	String	Human readable error description (can be localized)
`error_details`	String[]	Array of error details

Top

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Mobility Data Specification: Agency

Table of Contents

General information

Versioning

Authorization

Timestamps

Strings

Vehicles

Vehicle - Register

Vehicle - Update

Vehicle - Event

Vehicles - Telemetry

Vehicle Events

Telemetry Data

Enum Definitions

Area Types

Vehicle Type

Propulsion Type

Responses

Error Message Format

Files

README.md

Latest commit

History

README.md

File metadata and controls

Mobility Data Specification: Agency

Table of Contents

General information

Versioning

Authorization

Timestamps

Strings

Vehicles

Vehicle - Register

Vehicle - Update

Vehicle - Event

Vehicles - Telemetry

Vehicle Events

Telemetry Data

Enum Definitions

Area Types

Vehicle Type

Propulsion Type

Responses

Error Message Format