Appendix: Connected Vehicle Solution API - AWS Connected Vehicle Solution

Appendix: Connected Vehicle Solution API

The connected vehicle solution API enables you to expose collected vehicle data in a secure manner. The API acts as a “front door” for applications to access vehicle data, business logic, and extended functionality from the connected vehicle backend microservices.

This solution uses an Amazon Cognito user pool integrated with Amazon API Gateway (cc-authorizer) for identification and authorization. When a user pool is used with the API, clients are only allowed to call user pool enabled methods after they provide a valid identity token.

The following operations are available in the connected vehicle solution API.

Vehicles

Anomalies

Diagnostic Trouble Codes

Health Reports

Trips

GET /vehicles

Description

The GET /vehicles operation enables you to retrieve the vehicle ID and other details about the vehicle from the vehicle’s endpoint.

Response

Name Description
vin The vehicle identification number (VIN) for the vehicle
owner_id The unique user ID of the vehicle owner
nickname The vehicle nickname
odometer The vehicle’s odometer reading

For information about the errors that are common to all actions, see Common Errors.

POST /vehicles

Description

The POST /vehicles operation enables you to create a new registered vehicle for an owner. The response includes details about the newly registered vehicle.

Request Body

Name Description
vin The VIN for the vehicle
nickname The vehicle nickname

Response

Name Description
vin The VIN for the vehicle
owner_id The unique user ID of the vehicle owner
nickname The vehicle nickname
odometer The vehicle’s odometer reading

For information about the errors that are common to all actions, see Common Errors.

GET /vehicles/{vin}

Description

The GET /vehicles/{vin} operation enables you to retrieve information about a specific vehicle registered to a user.

Request Parameter

vin

The VIN used to filter vehicles

Type: String

Required: Yes

Response

Name Description
owner_id The unique user ID of the vehicle owner
nickname The vehicle nickname
odometer The vehicle’s odometer reading

For information about the errors that are common to all actions, see Common Errors.

GET /vehicles/{vin}/anomalies/

Description

The GET /vehicles/{vin}/anomalies operation enables you to retrieve information about a specific vehicle’s historical anomalies.

Request Parameter

vin

The VIN used to filter anomalies

Type: String

Required: Yes

Response

Name Description
anomaly_id The unique identifier of the anomaly
vin The VIN for the vehicle
telemetric The telemetric where the anomaly occurred
value The telemetric value where the anomaly occurred
anomaly_score The assessed score of the identified anomaly
acknowledged Flag indicating that the anomaly is acknowledged
description The description of the anomaly
identified_at The date and time the anomaly was identified
measured_at The date and time the anomaly was measured
created_at The date and time the anomaly was created

For information about the errors that are common to all actions, see Common Errors.

GET /vehicles/{vin}/anomalies/{anomaly_id}

Description

The GET /vehicles/{vin}/anomalies{anomaly_id} operation enables you to retrieve information about a specific anomaly for a specific vehicle.

Request Parameter

vin

The VIN used to filter anomalies

Type: String

Required: Yes

anomaly_id

The anomaly to return

Type: String

Required: Yes

Response

Name Description
anomaly_id The unique identifier of the anomaly
vin The VIN for the vehicle
telemetric The telemetric where the anomaly occurred
value The telemetric value where the anomaly occurred
anomaly_score The assessed score of the identified anomaly
acknowledged Flag indicating that the anomaly is acknowledged
description The description of the anomaly
identified_at The date and time the anomaly was identified
measured_at The date and time the anomaly was measured
created_at The date and time the anomaly was created

For information about the errors that are common to all actions, see Common Errors.

GET /vehicles/{vin}/anomalies/{anomaly_id}/acknowledge

Description

The GET /vehicles/{vin}/anomalies{anomaly_id}/acknowledge operation enables you to acknowledge a specific anomaly for a specific vehicle.

Request Parameter

vin

The VIN used to filter anomalies

Type: String

Required: Yes

anomaly_id

The anomaly to return

Type: String

Required: Yes

Response

Name Description
anomaly_id The unique identifier of the anomaly
vin The VIN for the vehicle
telemetric The telemetric where the anomaly occurred
value The telemetric value where the anomaly occurred
anomaly_score The assessed score of the identified anomaly
acknowledged Flag indicating that the anomaly is acknowledged
description The description of the anomaly
identified_at The date and time the anomaly was identified
measured_at The date and time the anomaly was measured
created_at The date and time the anomaly was created

For information about the errors that are common to all actions, see Common Errors.

GET /vehicles/{vin}/dtc

Description

The GET /vehicles/{vin}/dtc operation enables you to retrieve information about a specific vehicle’s historical diagnostic trouble codes.

Request Parameter

vin

The VIN used to filter diagnostic trouble codes

Type: String

Required: Yes

Response

Name Description
dtc_id The unique identifier of the diagnostic trouble code
vin The VIN for the vehicle
dtc The diagnostic trouble code identifier
description The description of the diagnostic trouble code
steps The resolution step of the diagnostic trouble code
acknowledged Flag indicating that the diagnostic trouble code is acknowledged
identified_at The date and time the diagnostic trouble code was identified
measured_at The date and time the diagnostic trouble code was measured

Resolution Step

Name Description
id The resolution step identifier
detail The resolution step details

For information about the errors that are common to all actions, see Common Errors.

GET /vehicles/{vin}/dtc/{dtc_id}

Description

The GET /vehicles/{vin}/dtc/{dtc-id} operation enables you to retrieve information about a specific diagnostic trouble code for a specific vehicle.

Request Parameter

vin

The VIN used to filter diagnostic trouble codes

Type: String

Required: Yes

dtc_id

The diagnostic trouble code to return

Type: String

Required: Yes

Response

Name Description
dtc_id The unique identifier of the diagnostic trouble code
vin The VIN for the vehicle
dtc The diagnostic trouble code identifier
description The description of the diagnostic trouble code
steps The resolution step of the diagnostic trouble code
acknowledged Flag indicating that the diagnostic trouble code is acknowledged
identified_at The date and time the diagnostic trouble code was identified
measured_at The date and time the diagnostic trouble code was measured

Resolution Step

Name Description
id The resolution step identifier
detail The resolution step details

For information about the errors that are common to all actions, see Common Errors.

PUT /vehicles/{vin}/dtc/{dtc_id}/acknowledge

Description

The PUT /vehicles/{vin}/dtc/{dtc-id}/acknowledge operation acknowledge a specific diagnostic trouble code for a specific vehicle.

Request Parameter

vin

The VIN used to filter diagnostic trouble codes

Type: String

Required: Yes

dtc_id

The diagnostic trouble code to return

Type: String

Required: Yes

Response

Name Description
dtc_id The unique identifier of the diagnostic trouble code
vin The VIN for the vehicle
dtc The diagnostic trouble code identifier
description The description of the diagnostic trouble code
steps The resolution step of the diagnostic trouble code
acknowledged Flag indicating that the diagnostic trouble code is acknowledged
identified_at The date and time the diagnostic trouble code was identified
measured_at The date and time the diagnostic trouble code was measured

For information about the errors that are common to all actions, see Common Errors.

GET /vehicles/{vin}/healthreports

Description

The GET /vehicles/{vin}/healthreports operation enables you to retrieve information about a vehicle’s historical health report.

Request Parameter

vin

The VIN used to filter health reports

Type: String

Required: Yes

Response

Name Description
report_id The unique identifier of the health report
vin The VIN for the vehicle
owner_id The unique user ID of the vehicle owner

For information about the errors that are common to all actions, see Common Errors.

GET /vehicles/{vin}/healthreports/{report_id}

Description

The GET /vehicles/{vin}/healthreports/{report_id} operation enables you to retrieve information about a specific health report for a specific vehicle.

Request Parameter

vin

The VIN used to filter health reports

Type: String

Required: Yes

report_id

The health report to return

Type: String

Required: Yes

Response

Name Description
report_id The unique identifier of the health report
vin The VIN for the vehicle
owner_id The unique user ID of the vehicle owner

For information about the errors that are common to all actions, see Common Errors.

GET /vehicles/{vin}/trips

Description

The GET /vehicles/{vin}/trips operation enables you to retrieve information about a specific vehicle’s historical trips.

Request Parameter

vin

The VIN used to filter trips

Type: String

Required: Yes

Response

Name Description
trip_id The unique identifier of the trip
vin The VIN for the vehicle
owner_id The unique user ID of the vehicle owner
vehicle_speed_mean The mean vehicle speed, in kilometers per hour, during the trip
engine_speed_mean The mean engine speed during the trip
torque_at_transmission_mean The mean transmission torque speed during the trip
oil_temp_mean The mean oil temperature during the trip
accelerator_pedal_position_mean The mean accelerator pedal position during the trip
brake_mean The mean brake pedal position during the trip
odometer The difference between the odometer reading at the start of the trip and the end of the trip
fuel_consumed_since_restart The fuel consumed during the trip
fuel_level The fuel level after the trip
start_latitude The latitude at the beginning of the trip
start_longitude The longitude at the beginning of the trip
stop_latitude The latitude at the end of the trip
stop_longitude The longitude at the end of the trip
start_time The time the trip started
end_time The time the trip ended
driver_safety_score The driver safety score for the trip

For information about the errors that are common to all actions, see Common Errors.

GET /vehicles/{vin}/trips/{trip_id}

Description

The GET /vehicles/{vin}/trips/{trip_id} operation enables you to retrieve information about a specific trip for a specific vehicle.

Request Parameter

vin

The VIN used to filter trips

Type: String

Required: Yes

trip_id

The trip to return

Type: String

Required: Yes

Response

Name Description
trip_id The unique identifier of the trip
vin The VIN for the vehicle
owner_id The unique user ID of the vehicle owner
vehicle_speed_mean The mean vehicle speed, in kilometers per hour, during the trip
engine_speed_mean The mean engine speed during the trip
torque_at_transmission_mean The mean transmission torque speed during the trip
oil_temp_mean The mean oil temperature during the trip
accelerator_pedal_position_mean The mean accelerator pedal position during the trip
brake_mean The mean brake pedal position during the trip
odometer The difference between the odometer reading at the start of the trip and the end of the trip
fuel_consumed_since_restart The fuel consumed during the trip
fuel_level The fuel level after the trip
start_latitude The latitude at the beginning of the trip
start_longitude The longitude at the beginning of the trip
stop_latitude The latitude at the end of the trip
stop_longitude The longitude at the end of the trip
start_time The time the trip started
end_time The time the trip ended
driver_safety_score The driver safety score for the trip

For information about the errors that are common to all actions, see Common Errors.

Common Errors

Error Code Description
400 Bad Request Invalid unique identifier
404 Not Found Vehicle not found
default Unexpected error