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.

Authors: LADOT
Date: 10 Aug 2018
Version: ALPHA

register_vehicle

The Vehicle Registration API is required in order to register a vehicle for use in the system. The API will require a valid provider_id and api_key.

Endpoint: /register_vehicle
Method: POST
API Key: Required

Body:

Field	Type	Required/Optional	Other
`unique_id`	UUID	Required	UUID v4 provided by Operator to uniquely identify a vehicle
`provider_id`	String	Required	Issued by city
`vehicle_id`	String		Vehicle Identification Number (VIN) visible on device
`vehicle_type`	Enum	Required	Vehicle Type
`propulsion_type`	Enum	Required	Propulsion Type
`vehicle_year`	Enum	Required	Year Manufactured
`vehicle_mfgr`	Enum	Required	Vehicle Manufacturer
`vehicle_model`	Enum	Required	Vehicle Model

Response:

Field	Type	Required/Optional	Other
`message`	Enum		See Message Enum

deregister_vehicle

The remove-vehicle API is used to deregister a vehicle from the fleet.

Endpoint: /deregister_vehicle
Method: POST
API Key: Required

Body:

Field	Type	Required/Optional	Other
`unique_id`	UUID	Required	ID used in Register
`device_id`	UUID	Required
`reason_code`	Enum	Required	Reason for status change

Response:

Field	Type	Required/Optional	Other
`message`	Enum		See Message Enum

update_vehicle_status

This API is used by providers when a vehicle is either removed or returned to service.

Endpoint: /update_vehicle_status
Method: POST
API Key: Required

Body:

Field	Type	Required/Optional	Other
`unique_id`	UUID	Required	ID used in Register
`timestamp`	Unix Timestamp	Required	Date/time that event occurred. Based on GPS clock.
`location`	Point	Required	Location at the time of status change in WGS 84 (EPSG:4326) standard GPS projection
`event_type`	Enum	Required	Event Type for status change.
`reason_code`	Enum	Required	Reason for status change.
`battery_pct`	Float	Require if Applicable	Percent battery charge of device, expressed between 0 and 1

Response:

Field	Type	Required/Optional	Other
`message`	Enum		See Message Enum

start_trip

Endpoint: /start_trip
Method: POST
API Key: Required

Body:

Field	Type	Required/Optional	Other
`unique_id`	UUID	Required	ID used in Register
`provider_id`	String	Required	Issued by city
`vehicle_id`	String	Required	Provided by the Vehicle Registration API
`timestamp`	Unix Timestamp	Required	Date/time that event occurred. Based on GPS clock.
`location`	Point	Required	Location at the time of status change in WGS 84 (EPSG:4326) standard GPS projection
`accuracy`	Integer	Required	The approximate level of accuracy, in meters, represented by start_point and end_point.
`battery_pct_start`	Float	Require if Applicable	Percent battery charge of device, expressed between 0 and 1

Response:

Field	Type	Required/Optional	Other
`trip_id`	UUID	Required	a unique ID for each trip

end_trip

Endpoint: /end_trip
Method: POST
API Key: Required

Body:

Field	Type	Required/Optional	Other
`trip_id`	UUID	Required	See start_trip
`timestamp`	Unix Timestamp	Required	Date/time that event occurred. Based on GPS clock.
`location`	Point	Required	Location at the time of status change in WGS 84 (EPSG:4326) standard GPS projection
`accuracy`	Integer	Required	The approximate level of accuracy, in meters, represented by start_point and end_point.
`battery_pct_end`	Float	Require if Applicable	Percent battery charge of device, expressed between 0 and 1

update_trip_telemetry

A trip represents a route taken by a provider's customer. Trip data will be reported to the API every 5 seconds while the vehicle is in motion.

Endpoint: /update_trip_telemetry
Method: POST
API Key: Required

Body:

Field	Type	Required/Optional	Other
`trip_id`	UUID	Required	Issued by InitMovementPlan() API
`timestamp`	Unix Timestamp	Required	Time of day (UTC) data was sampled
`route`	Route	Required	See detail below.
`accuracy`	Integer	Required	The approximate level of accuracy, in meters, represented by start_point and end_point.

Response:

Field	Type	Other
`message`	Enum	See Message Enum

Route

To represent a route, MDS provider APIs should create a GeoJSON Feature Collection where ever observed point in the route, plus a time stamp, should be included. The representation needed is below.

The route must include at least 2 points, a start point and end point. Additionally, it must include all possible GPS samples collected by a provider. All points must be in WGS 84 (EPSG:4326) standard GPS projection

"route": {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "properties": {
                    "timestamp": 1529968782.421409
                },
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        -118.46710503101347,
                        33.9909333514159
                    ]
                }
            },
            {
                "type": "Feature",
                "properties": {
                    "timestamp": 1531007628.3774529
                },
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        -118.464851975441,
                        33.990366257735
                    ]
                }
            }
        ] }

service_areas

Gets the list of service areas available to the provider.

Endpoint: /service_areas
Method: GET

Query Parameters:

Parameter	Type	Required/Optional	Description
`provider_id`	UUID	Required	A UUID for the Provider, unique within MDS
`service_area_id`	UUID	Optional	If provided, retrieve a specific service area (e.g. a retired or old service area). If omitted, will return all active service areas.

Response:

Field	Types	Required/Optional	Other
`service_area_id`	UUID	Required
`service_start_date`	Unix Timestamp	Required	Date at which this service area became effective
`service_end_date`	Unix Timestamp	Required	Date at which this service area was replaced. If currently effective, place NaN
`service_area`	MultiPolygon	Required
`prior_service_area`	UUID	Optional	If exists, the UUID of the prior service area.
`replacement_service_area`	UUID	Optional	If exists, the UUID of the service area that replaced this one
`type`	Enum	Required	See area types table

Area types

`type`	Description
unrestricted	Areas where devices 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 device pick-up/drop-off is not allowed
preferred_pick_up	Areas where users are encouraged to pick up devices
preferred_drop_off	Areas where users are encouraged to drop off devices

Event Types

event_type	event_type_description	reason	reason_description
`available`	A device becomes available for customer use	`service_start`	Device introduced into service at the beginning of the day (if program does not operate 24/7)
		`user_drop_off`	User ends reservation
		`rebalance_drop_off`	Device moved for rebalancing
		`maintenance_drop_off`	Device introduced into service after being removed for maintenance
`reserved`	A customer reserves a device (even if trip has not started yet)	`user_pick_up`	Customer reserves device
`unavailable`	A device is on the street but becomes unavailable for customer use	`default`	Default state for a newly registered vehicle
		`low_battery`	A device is no longer available due to insufficient battery
		`maintenance`	A device is no longer available due to equipment issues
`removed`	A device is removed from the street and unavailable for customer use	`service_end`	Device removed from street because service has ended for the day (if program does not operate 24/7)
		`rebalance_pick_up`	Device removed from street and will be placed at another location to rebalance service
		`maintenance_pick_up`	Device removed from street so it can be worked on
`inactive`	A device has been deregistered

Enum Definitions

vehicle_type

For vehicle_type, options are:

bike
scooter
recumbent

propulsion_type

For propulsion_type, options are:

human
electric
combustion

reason_code

For reason_code, options are:

rebalancing
maintenance

message

For 'message', options are:

200: OK
201: Created
202: Accepted
203: Added
204: Removed
210: Warning: vehicle used in this trip has not been properly registered
305: Error: vehicle is already registered
306: Error: vehicle registration cannot be found
310: Error: vehicle is not properly registered
311: Error: duplicate registration found, please use a different unique_id or update existing unique_id status using the update-vehicle-status endpoint
315: Error: vehicle is not active
320: Error: vehicle trip has not been properly started

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Mobility Data Specification: Agency

Table of Contents

register_vehicle

deregister_vehicle

update_vehicle_status

start_trip

end_trip

update_trip_telemetry

Route

service_areas

Area types

Event Types

Enum Definitions

vehicle_type

propulsion_type

reason_code

message

Files

README.md

Latest commit

History

README.md

File metadata and controls

Mobility Data Specification: Agency

Table of Contents

register_vehicle

deregister_vehicle

update_vehicle_status

start_trip

end_trip

update_trip_telemetry

Route

service_areas

Area types

Event Types

Enum Definitions

vehicle_type

propulsion_type

reason_code

message