Vehicle Update API

Vehicle Update API is available to enable integrated users to poll GPS location-based information captured by vehicles tracked with REVEAL.

Important concepts to understand prior to utilizing any of the available integration methods:

·      Vehicle Update API is offered as a RESTful web service

·      Standard REST verbs are applied: GET, POST

·      Throughout this document, we will reference the unique identifier to be invoked for each of the main objects available to be created or deleted.  The unique identifiers used within this API method set include:

o   Vehicle Number

Note: The current version of the Vehicle Update API does not support devices tracking Non-Powered Assets.  No information will return regarding Non-Powered Assets within any of the following API methods.

The returned response will be restricted to the Reveal account's data plan. If the information being queried is outside of the data plan, a "400 Bad Request error "response will be returned.

For more details on your account's data plan please reach out to Verizon Connect Customer Support

 

 

API Summary Details

API Name

Vehicle Update API

Endpoint

https://fim.api.us.fleetmatics.com/rad

Operation

GET, POST

 

Get Location and Status

The following methods enable integrated users to extract a vehicle’s current location or status from REVEAL.  These methods can only be called for one vehicle at a time using the Vehicle Number within REVEAL.

It is recommended that integrated users regularly calling the GET Segment by Vehicle Number periodically call the Customer Meta Data – Vehicle API for GET ALL VEHICLES to return a set of active Vehicle Numbers for the REVEAL account.  Coding dynamically against the GET ALL VEHICLES method will ensure that all vehicles within an account are being requested and that vehicle numbers that do not exist in the REVEAL account do not accidentally get processed creating a 400 errors.

 

GET Location by Vehicle Number

The GET Location by Vehicle Number method provides integration users with the ability to retrieve the location of the vehicles within a fleet at a regular interval. 

 

GET Location API Request Header

Operation and Path

GET https://fim.api.us.fleetmatics.com/rad/v1/vehicles/<vehiclenumber>/location HTTP/1.1

HOST

fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID  ], Bearer [Authorization Token]

Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

GET Location Sample Response

{

    "Address": {

        "AddressLine1": "31500 Bainbridge Rd",

        "AddressLine2": "",

        "Locality": "Solon",

        "AdministrativeArea": "OH",

        "PostalCode": "44139",

        "Country": "USA"

    },

    "DeltaDistance": 0,

    "DeltaTime": null,

    "DeviceTimeZoneOffset": -5,

    "DeviceTimeZoneUseDST": true,

    "DisplayState": "Idle",

    "Direction": 0,

    "Heading": "North",

    "DriverNumber": null,

    "GeoFenceName": null,

    "Latitude": 41.397001,

    "Longitude": -81.45617,

    "Speed": 0,

    "UpdateUTC": "2016-07-14T15:52:04"

}

 

GET Location Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Address

{

     “Address”:{

          “AddressLine1”:””

          “AddressLine2”:””

          “Locality”:””

          “Administrative Area”:””

          “Postal Code”:””

          “Country”:””

},

Address contains the global standards for address components:

·       Address Line 1 – location specific identification such as a house number

·       Address Line 2 – additional information to identify location such as an apartment number

·       Locality – city, town, etc.

·       Administrative Area – state, province, etc.

·       Postal Code

·       Country

Delta Distance

     “DeltaDistance”:0,

Delta Distance is the distance accumulated between the previous GPS plot and the current referenced plot.

Defaults to “0” if no delta distance accumulated for the most recent GPS plot referenced.

Delta Time

     DeltaTime:null,

Delta Time is the time between the previous GPS plot and the current referenced plot.

Defaults to NULL if no time accumulated for the most recent GPS plot referenced.

Device Time Zone Offset

     DeviceTimeZoneOffset:””

Device Time Zone Offset is the GPS device’s current time zone compared to UTC.

Device Time Zone Use DST

     DeviceTimeZoneUseDST”:true,

If the REVEAL account is set to acknowledge Daylight Savings Time then this value will return as TRUE.

REVEAL accounts in the United States are automatically defaulted to True.

Display State

     DisplayState”:””

Display State is the value used to describe the vehicle’s display state.  The following values will return to describe the state of the vehicle:

·       0: Coverage

·       1: Moving

·       2: Stop

·       3: Towing

·       4: Idle

·       5: Panic

·       6: Privacy

Direction

     “Direction”:””

Direction is the degrees of the compass direction.

Heading

     “Heading”:””

Heading will include the following values to describe the vehicle’s current direction:

·       North

·       North East

·       East

·       South East

·       South

·       South West

·       West

·       North West

·       Unknown

Driver Number

     DriverNumber”:null,

Driver Number is the unique identifier for Drivers created within REVEAL.

The value will default to NULL if no Driver is Assigned to the Vehicle at the time of the GPS plot that is referenced.  NULL will also be returned if the Driver record assigned at the time of the plot does not have a Driver Number associated with the record in REVEAL.

Geofence Name

     GeoFenceName”:null,

Geofence is a place configured within a REVEAL account to easily identify particular locations.

The value will default to NULL if the GPS plot referenced does not occur within a Geofence.

Latitude

     “Latitude”:””

 

Longitude

     “Longitude”:””

 

Speed

     “Speed”:””  

Values will be returned in kilometers per hour.

Update UTC

     UpdateUTC”:””

}

The date and time stamp when the GPS plot was received.

Format: xxxx-xx-xxTxx:xx:xx

·       YEAR-MONTH-DAY T HOURS-MINUTES-SECONDS

 
 

GET Status by Vehicle Number

The GET Status by Vehicle Number returns key information related to the vehicle’s current activity. 

 

GET Status API Request Header

Operation and Path

GET https://fim.api.us.fleetmatics.com/rad/v1/vehicles/<vehiclenumber>/status HTTP/1.1

HOST

fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID  ], Bearer [Authorization Token]

Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

GET Status Sample Response

{

    "DeviceTimeZoneOffset": -5,

    "DeviceTimeZoneUseDST": true,

    "DisplayState": "Idle",

    "DriverNumber": null,

    "Speed": 0,

    "UpdateUTC": "2016-07-14T15:52:04",

    "DriverName": null,

    "EngineMinutes": 44547,

    "CurrentOdometer": 7855.1499492187495,

    "IdleTime": 10,

    "BatteryLevel": 74,

    "TractionBatteryChargingUtc": "2023-11-27T21:19:13",

    "TractionBatteryChargingLastStartUtc": "2023-11-27T18:41:46",

    "SensorValues": [

        "Privacy Off"

    ],

    "BatteryVoltage": null

}

 

GET Status Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Device Time Zone Offset

{

     DeviceTimeZoneOffset”:””

Device Time Zone Offset is the GPS device’s current time zone compared to UTC.

Device Time Zone Use DST

     DeviceTimeZoneUseDST”:true,

If the REVEAL account is set to acknowledge Daylight Savings Time then this value will return as TRUE.

REVEAL accounts in the United States are automatically defaulted to True.

Display State

     DisplayState”:””

Display State is the value used to describe the vehicle’s display state.  The following values will return to describe the state of the vehicle:

·       0: Coverage

·       1: Moving

·       2: Stop

·       3: Towing

·       4: Idle

·       5: Panic

·       6: Privacy

Driver Number

     DriverNumber”:null,

Driver Number is the unique identifier for Drivers created within REVEAL.

The value will default to NULL if no Driver is Assigned to the Vehicle at the time of the GPS plot that is referenced.  NULL will also be returned if the Driver record assigned at the time of the plot does not have a Driver Number associated with the record in REVEAL.

Speed

     “Speed”:””

Values will be returned in kilometers per hour.

Update UTC

     UpdateUTC”:””

The date and time stamp when the GPS plot was received.

Format: xxxx-xx-xxTxx:xx:xx

YEAR-MONTH-DAY T HOURS-MINUTES-SECONDS

Engine Minutes

     EngineMinutes”:””

Engine Minutes is accumulated across the lifetime of the device within the vehicle every time the vehicle has Ignition On plots.

Current Odometer

     CurrentOdometer”:””

Current Odometer is the accumulated odometer value.  If the REVEAL vehicle record profile includes an initial odometer amount, the accumulated odometer will reflect the initial odometer value entered by the user plus the accumulated distance.  The Odometer is displayed in kilometers.

Idle Time

     IdleTime”:””

The total amount of time (in minutes) that the vehicle has been continuously idling.

Battery Level

     BatteryLevel”:””

The percentage of Battery remaining for Electric Vehicles.

Traction Battery Charging Last Start Utc

     TractionBatteryChargingLastStartUtc”:””

The value of the charging start date/time for Electric Vehicles.

Traction Battery Charging Utc

     TractionBatteryChargingUtc”:””

The value of the charging end date/time for Electric Vehicles.

Sensor Values

     SensorValues”:[<”name of sensor”>

 ],

Vehicles that have PTOs will display the Sensor’s name if the GPS plot referenced has an active PTO ON.

Battery Voltage

     "BatteryVoltage": null

}

Battery Voltage is the Power Supply Voltage for an ICE vehicle.

Please note: The value will default to NULL if no data is captured for Battery Voltage of an ICE vehicle.

 

POST Status and Location for Multiple Vehicles

The following POST methods enable integration users the ability to extract status and location details from REVEAL by calling up to 100 vehicles  within one POST call.  The list of 100 vehicles  must be called using the Vehicle Number within REVEAL.

It is recommended that integrated users regularly calling the GET Segment by Vehicle Number periodically call the Customer Meta Data – Vehicle API for GET ALL VEHICLES to return a set of active Vehicle Numbers for the REVEAL account.  Coding dynamically against the GET ALL VEHICLES method will ensure that all vehicles within an account are being requested and that vehicle numbers that do not exist in the REVEAL account do not accidentally get processed creating a 400 errors.

 

POST Locations

The POST Locations by Vehicle Numbers enables the integrated user to return location information for up to 100 vehicles  within one call.

 

POST Locations API Request Header

Within the body of the request, the integrated user will need to supply the list of vehicle numbers using the following format:

[

  "0018",

  "CB0021",

  "0046",

  "0156",

  "5184",

  "56990",

]

 

Within the above example body content, each value within quotes is a Vehicle Number within the referenced REVEAL account.

Operation and Path

POST https://fim.api.us.fleetmatics.com/rad/v1/vehicles/locations HTTP/1.1

HOST

fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID  ], Bearer [Authorization Token]

Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

POST Locations Sample Response

[

    {

        "VehicleNumber": "0018",

        "StatusCode": 200,

        "ContentResource": {

            "Value": {

                "Address": {

                    "AddressLine1": "8 Penrod Way",

                    "AddressLine2": "",

                    "Locality": "Heysham",

                    "AdministrativeArea": "England",

                    "PostalCode": "LA3 2UZ",

                    "Country": "GBR"

                },

                "DeltaDistance": null,

                "DeltaTime": null,

                "DeviceTimeZoneOffset": null,

                "DeviceTimeZoneUseDST": false,

                "DisplayState": "Idle",

                "Direction": 0,

                "Heading": "West",

                "DriverNumber": null,

                "GeoFenceName": null,

                "Latitude": 54.03659,

                "Longitude": -2.901719,

                "Speed": null,

                "UpdateUTC": "2016-09-24T16:23:13",

                "IsPrivate": false,

                "BatteryVoltage": null

            },

            "StatusCode": 200

        }

    },

    {

        "VehicleNumber": "CB0021",

        "StatusCode": 200,

        "ContentResource": {

            "Value": {

                "Address": {

                    "AddressLine1": "Belgard Rd",

                    "AddressLine2": "",

                    "Locality": "Tallaght",

                    "AdministrativeArea": "Dublin",

                    "PostalCode": "Dublin 24",

                    "Country": "IRL"

                },

                "DeltaDistance": null,

                "DeltaTime": null,

                "DeviceTimeZoneOffset": null,

                "DeviceTimeZoneUseDST": false,

                "DisplayState": "Stop",

                "Direction": 0,

                "Heading": "North",

                "DriverNumber": null,

                "GeoFenceName": null,

                "Latitude": 53.29742,

                "Longitude": -6.37298,

                "Speed": null,

                "UpdateUTC": "2016-03-04T09:42:20",

                "IsPrivate": false,

                "BatteryVoltage": null

            },

            "StatusCode": 200

        }

    },

]

 

POST Locations Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Vehicle Number

[

    {

        "VehicleNumber": "0018",

The Vehicle Number called in the request will be returned within the response.

Status Code

        "StatusCode": 200,

The POST Locations enables integrated users to call a list of up to 100 vehicles  within one request.  Therefore, the response may include individual statuses per vehicle.

·       400

·       500

·       204

·       404

·       200

·       401

The Status Code at the top of the response indicates if the Vehicle Number provided can be found.

Address

        "ContentResource": {

            "Value": {

                "Address": {

                    "AddressLine1": "8 Penrod Way",

                    "AddressLine2": "",

                    "Locality": "Heysham",

                    "AdministrativeArea": "England",

                    "PostalCode": "LA3 2UZ",

                    "Country": "GBR"

                },

·       Address contains the global standards for address components:

·       Address Line 1 – location specific identification such as a house number

·       Address Line 2 – additional information to identify location such as an apartment number

·       Locality – city, town, etc.

·       Administrative Area – state, province, etc.

·       Postal Code

·       Country

Delta Distance

     “DeltaDistance”:0,

Delta Distance is the distance accumulated between the previous GPS plot and the current referenced plot.

Defaults to “0” if no delta distance accumulated for the most recent GPS plot referenced.

Delta Time

     DeltaTime:null,

Delta Time is the time between the previous GPS plot and the current referenced plot.

Defaults to NULL if no time accumulated for the most recent GPS plot referenced.

Device Time Zone Offset

     DeviceTimeZoneOffset:””

Device Time Zone Offset is the GPS device’s current time zone compared to UTC.

Device Time Zone Use DST

     DeviceTimeZoneUseDST”:true,

If the REVEAL account is set to acknowledge Daylight Savings Time then this value will return as TRUE.

REVEAL accounts in the United States are automatically defaulted to True.

Display State

     DisplayState”:””

Display State is the value used to describe the vehicle’s display state.  The following values will return to describe the state of the vehicle:

·       0: Coverage

·       1: Moving

·       2: Stop

·       3: Towing

·       4: Idle

·       5: Panic

·       6: Privacy

Direction

     “Direction”:””

Direction is the degrees of the compass direction.

Heading

     “Heading”:””

Heading will include the following values to describe the vehicle’s current direction:

·       North

·       North East

·       East

·       South East

·       South

·       South West

·       West

·       North West

·       Unknown

 

Driver Number

     DriverNumber”:null,

Driver Number is the unique identifier for Drivers created within REVEAL.

The value will default to NULL if no Driver is Assigned to the Vehicle at the time of the GPS plot that is referenced.  NULL will also be returned if the Driver record assigned at the time of the plot does not have a Driver Number associated with the record in REVEAL.

Geofence Name

     GeoFenceName”:null,

Geofence is a place configured within a REVEAL account to easily identify particular locations.

The value will default to NULL if the GPS plot referenced does not occur within a Geofence.

Latitude

     "Latitude": 54.03659,

 

Longitude

     "Latitude": 54.03659,

 

Speed

     “Speed”:””  

Values will be returned in kilometers per hour.

Update UTC

     UpdateUTC”:””

}

The date and time stamp when the GPS plot was received.

Format: xxxx-xx-xxTxx:xx:xx

YEAR-MONTH-DAY T HOURS-MINUTES-SECONDS

IsPrivate

      "IsPrivate": false,

If the REVEAL account is using the Privacy feature to enable drivers with the ability to not disclose their current location during non-business hours, the location information will not be returned within the vehicle’s response to the API and this flag will be set to TRUE. 


Please note: when IsPrivate is TRUE neither the address nor coordinate details will be displayed to the integration user.

BatteryVoltage

      "BatteryVoltage": :null

   },

Battery Voltage is the Power Supply Voltage for an ICE vehicle. 


Please note: the value will default to NULL if no data is captured for Battery Voltage of an ICE vehicle.

Status Code

     "StatusCode": 200

   }

]

If the Vehicle Number can be successfully found, but there is no address content available for the vehicle the Status Code would reflect that the location content could not be found.  This will primarily indicate vehicles that have not yet reported to REVEAL but may be set up within an account. The Status Codes available include:

·       400

·       500

·       204

·       404

·       200

·       401

 

POST Statuses

The POST Statuses by Vehicle Numbers enables the integrated user to return status information for up to 100 vehicles  within one call.

POST Statuses API Request Header

Within the body of the request, the integrated user will need to supply the list of vehicle numbers using the following format:

[

  "0018",

  "CB0021",

  "0046",

  "0156",

  "5184",

  "56990",

]

 

Within the above example body content, each value within quotes is a Vehicle Number within the referenced REVEAL account.

 

Operation and Path

POST https://fim.api.us.fleetmatics.com/rad/v1/vehicles/statuses HTTP/1.1

HOST

fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=< Integration Manager App ID>, Bearer <token>

Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

POST Statuses Sample Response

[

    {

        "VehicleNumber": "0018",

        "StatusCode": 200,

        "ContentResource": {

            "Value": {

                "DeviceTimeZoneOffset": 0,

                "DeviceTimeZoneUseDST": true,

                "DisplayState": "Idle",

                "DriverNumber": null,

                "Speed": 0,

                "UpdateUTC": "2016-09-24T16:23:13",

                "DriverName": null,

                "EngineMinutes": 306764,

                "CurrentOdometer": 160730,

                "IdleTime": 55,

                "BatteryLevel": 74,

                "TractionBatteryChargingUtc": "2023-11-27T21:19:13",

                "TractionBatteryChargingLastStartUtc": "2023-11-27T18:41:46",

                "SensorValues": [

                    "Brushes OFF"

                ]

            },

            "StatusCode": 200

        }

    },

    {

        "VehicleNumber": "CB0021",

        "StatusCode": 200,

        "ContentResource": {

            "Value": {

                "DeviceTimeZoneOffset": 0,

                "DeviceTimeZoneUseDST": false,

                "DisplayState": "Stop",

                "DriverNumber": null,

                "Speed": 0,

                "UpdateUTC": "2016-03-04T09:42:20",

                "DriverName": null,

                "EngineMinutes": 348,

                "CurrentOdometer": 7,

                "IdleTime": 0,

                "BatteryLevel": 74,

                "TractionBatteryChargingUtc": "2023-11-27T21:19:13",

                "TractionBatteryChargingLastStartUtc": "2023-11-27T18:41:46",

                "SensorValues": []

            },

            "StatusCode": 200

        }

    },

]

 

POST Statuses Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Vehicle Number

[

    {

        "VehicleNumber": "0018",

The Vehicle Number called in the request will be returned within the response.

Status Code

        "StatusCode": 200,

The POST Locations enables integrated users to call a list of up to 100 vehicles  within one request.  Therefore, the response may include individual statuses per vehicle.

·       400

·       500

·       204

·       404

·       200

·       401

The Status Code at the top of the response indicates if the Vehicle Number provided can be found.

Device Time Zone Offset

{

     DeviceTimeZoneOffset”:””

Device Time Zone Offset is the GPS device’s current time zone compared to UTC.

Device Time Zone Use DST

     DeviceTimeZoneUseDST”:true,

If the REVEAL account is set to acknowledge Daylight Savings Time then this value will return as TRUE.

 

REVEAL accounts in the United States are automatically defaulted to True.

Display State

     DisplayState”:””

Display State is the value used to describe the vehicle’s display state.  The following values will return to describe the state of the vehicle:

·       0: Coverage

·       1: Moving

·       2: Stop

·       3: Towing

·       4: Idle

·       5: Panic

·       6: Privacy

Driver Number

     DriverNumber”:null,

Driver Number is the unique identifier for Drivers created within REVEAL.

The value will default to NULL if no Driver is Assigned to the Vehicle at the time of the GPS plot that is referenced.  NULL will also be returned if the Driver record assigned at the time of the plot does not have a Driver Number associated with the record in REVEAL.

Speed

     “Speed”:””

Values will be returned in kilometers per hour.

Update UTC

     UpdateUTC”:””

The date and time stamp when the GPS plot was received.

Format: xxxx-xx-xxTxx:xx:xx

YEAR-MONTH-DAY T HOURS-MINUTES-SECONDS

Engine Minutes

     EngineMinutes”:””

Engine Minutes is accumulated across the lifetime of the device within the vehicle every time the vehicle has Ignition On plots.

Current Odometer

     CurrentOdometer”:””

Current Odometer is the accumulated odometer value.  If the REVEAL vehicle record profile includes an initial odometer amount, the accumulated odometer will reflect the initial odometer value entered by the user plus the accumulated distance.  The Odometer is displayed in kilometers.

Idle Time

     IdleTime”:””

The total amount of time (in minutes) that the vehicle has been continuously idling.

Battery Level

     BatteryLevel”:””

The percentage of Battery remaining for Electric Vehicles.

Traction Battery Charging Last Start Utc

     TractionBatteryChargingLastStartUtc”:””

The value of the charging start date/time for Electric Vehicles.

Traction Battery Charging Utc

     TractionBatteryChargingUtc”:””

The value of the charging end date/time for Electric Vehicles.

Sensor Values

     SensorValues”:[<”name of sensor”>

 ]

}

Vehicles that have PTOs will display the Sensor’s name if the GPS plot referenced has an active PTO ON.

Status Code

     "StatusCode": 200

   }

]

If the Vehicle Number can be successfully found, but there is no status content available for the vehicle the Status Code would reflect that the status content could not be found.  This will primarily indicate vehicles that have not yet reported to REVEAL but may be set up within an account. The Status Codes available include:

·       400

·       500

·       204

·       404

·       200

·       401

 

GET Engine Computer Module (ECM) Statuses

The following set of methods are available for customers using devices that are connected to a vehicle’s Engine Computer Module (ECM).  Please check with Customer Support team before implementing any of these methods for your organization to ensure your devices are compatible.  Additionally, not all ECM devices will return the same ECM feature set.  It is important to confirm your fleet’s devices along with the expected feature set before regularly calling any of the methods listed within this section. 

It is recommended that integrated users regularly calling the GET Segment by Vehicle Number periodically call the Customer Meta Data – Vehicle API for GET ALL VEHICLES to return a set of active Vehicle Numbers for the REVEAL account.  Coding dynamically against the GET ALL VEHICLES method will ensure that all vehicles within an account are being requested and that vehicle numbers that do not exist in the REVEAL account do not accidentally get processed creating a 400 errors.

 

GET Active DTCs

The GET Active DTCs enables the integration user to pull all active Diagnostic Trouble Codes (DTCs) across an entire REVEAL fleet.

NOTE: This method is only available to fleets with less than 1,000 vehicles. Not all ECM units may be compatible or configured to report DTCs.

 

GET Active DTCs API Request Header

Operation and Path

GET https://fim.api.us.fleetmatics.com/rad/v1/vehicles/getvehiclesactivedtcs HTTP/1.1

HOST

fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID  ], Bearer [Authorization Token]

Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

GET Active DTCs Sample Response

[

    {

        "VehicleNumber": "33242526",

        "VehicleName": "Gem2",

        "ActiveDTCs": null,

        "LastUpdatedDateTime": null

    },

    {

        "VehicleNumber": "999001",

        "VehicleName": "Gem1",

        "ActiveDTCs": null,

        "LastUpdatedDateTime": null

    },

]

 

GET Active DTCs Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Vehicle Number

[

    {

        "VehicleNumber": "0018",

The Vehicle Number called in the request will be returned within the response.

Note :This method is only available to fleets with less than 1,000 vehicles.

Vehicle Name

        "VehicleName": "Gem2",

 

The Vehicle Name as displayed within the REVEAL account.

Active DTCs

        "ActiveDTCs": null,

 

When a vehicle has active DTCs a list of the codes will be displayed.

Last Updated Date Time

        "LastUpdatedDateTime": null

    },

]

 

The last date and time stamp where the presented DTCs were registered.

 

 

GET DTC History by Vehicle Number

The GET DTC History by Vehicle Number enables the integration user to specify a vehicle within the fleet and return all DTCs that were ever activated or deactivated.

Note: Not all ECM units may be compatible or configured to report DTCs.

 

GET DTC History API Request Header

Operation and Path

GET https://fim.api.us.fleetmatics.com/rad/v1/vehicles/<VehicleNumber>/getdtchistorybyvehiclenumber HTTP/1.1

HOST

fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID  ], Bearer [Authorization Token]

Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

GET DTC History API Sample Response

{

    "VehicleNumber": "GEM1",

    "VehicleName": "GEM1 US",

    "DTCs": [

        {

            "DTCs": "OBDII DTC: \P1036",

            "IsActive": "True",

            "LastUpdatedDateTime": "2017-04-17T18:56:30"

        },

        {

            "DTCs": "OBDII DTC: \ P1036",

            "IsActive": "False",

            "LastUpdatedDateTime": "2017-04-17T18:56:31"

        },

        {

            "DTCs": "OBDII DTC: \ P1036",

            "IsActive": "True",

            "LastUpdatedDateTime": "2017-04-09T15:54:41"

        },

        {

            "DTCs": "OBDII DTC: \ P1036",

            "IsActive": "False",

            "LastUpdatedDateTime": "2017-04-09T16:02:44"

        },

    ]

}

 

GET DTC History Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Vehicle Number

{

    "VehicleNumber": "4865005051",

The Vehicle Number called in the request will be returned within the response.

Vehicle Name

    "VehicleName": "LMU4230 - 4865005051",

The Vehicle Name as displayed within the REVEAL account.

DTC

    "DTCs": [

        {

            "DTCs": "OBDII DTC: \P1036",

 

Will include all of the DTCs that have ever been activated or deactivated for the specified vehicle.

DTC displays the Diagnostic Trouble Code and how it would translate for JBUS or OBDII values.

Is Active

            "IsActive": "False",

 

The DTC active status is TRUE or FALSE.

·       If “True” then the DTC shown is currently activated.

·       If “False” then the DTC shown is currently deactivated

Last Updated Date Time

            "LastUpdatedDateTime": "2017-04-09T15:54:41"

        },

 

The last date and time stamp where the DTC was either activated or deactivated.

 

 

GET ECM Status by Vehicle Number

The GET ECM Status by Vehicle Number enables the integrated user to return status information on top of what would be collected by a standard GPS tracking unit and displayed in the GET Status by Vehicle Number method.

Note: Not all ECM units may be compatible with every ECM status field shown within the response

 

GET ECM Status API Request Header

Operation and Path

GET https://fim.api.us.fleetmatics.com/rad/v1/vehicles/getvecmstatusbyvehiclenumber HTTP/1.1

HOST

fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID  ], Bearer [Authorization Token]

Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

GET ECM Status by Vehicle number Sample Response

  {

                    "CurrentOdometer": null,

                    "DeviceTimeZoneOffset": null,

                    "DeviceTimeZoneUseDST": null,

                    "DisplayState": null,

                    "DriverName": null,

                    "DriverNumber": null,

                    "DTCs": null,

                    "EngineMintutes": null,

                    "FuelLevelPercentage": null,

                    "IdleTime": null,

                    "Speed": null,

                    "SensorValues": null,

                    "BatteryLevel": null,

                    "TractionBatteryChargingLastStartUtc": null,

                    "TractionBatteryChargingUtc": null,

                    "UpdateUTC": null,

                    "TotalFuelUsed": null,

                    "TotalIdleFuel": null,

                    "TotalPTOFuel": null,

                    "TotalPTOTime": null,

                    "VIN": null,

                    "BatteryVoltage": null

                  }

 

GET ECM Status by Vehicle Number Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Current Odometer

  {

                    "CurrentOdometer": null,

The Current Odometer field will return the value as it shows within the Vehicle Profile of REVEAL Admin. The Odometer is displayed in kilometers.

Device Time Zone Offset

     DeviceTimeZoneOffset:””

Device Time Zone Offset is the GPS device’s current time zone compared to UTC.

Device Time Zone Use DST

     DeviceTimeZoneUseDST”:true,

If the REVEAL account is set to acknowledge Daylight Savings Time then this value will return as TRUE.

REVEAL accounts in the United States are automatically defaulted to True.

Display State

     DisplayState”:””

Display State is the value used to describe the vehicle’s display state.  The following values will return to describe the state of the vehicle:

·       0: Coverage

·       1: Moving

·       2: Stop

·       3: Towing

·       4: Idle

·       5: Panic

·       6: Privacy

Driver Name

      "DriverName": null,

 

The driver first and last name as shown within REVEAL.

If there is no driver assignment within REVEAL for the plot being returned then this field will be NULL.

Driver Number

     DriverNumber”:null,

Driver Number is the unique identifier for Drivers created within REVEAL.

The value will default to NULL if no Driver is Assigned to the Vehicle at the time of the GPS plot that is referenced.  NULL will also be returned if the Driver record assigned at the time of the plot does not have a Driver Number associated with the record in REVEAL.

DTCs

    "DTCs": null,

 

Any active DTCs for the vehicle that are included within the referenced vehicle plot.

Please note, compatible ECM devices that extract DTC details do not include DTCs on every plot sent to REVEAL.  DTCs details are sent upon a state change or at specific time intervals so that every plot does not include this information.

Engine Minutes

    "EngineMintutes": null,

 

Current total engine hours for the vehicle converted to minutes.  This value will align with the Vehicle Profile in REVEAL Admin.

Fuel Level Percentage

    "FuelLevelPercentage": null,

 

Idle Time

     "IdleTime": null,

 

Speed

     “Speed”:””  

Values will be returned in kilometers per hour.

Sensor Values

     SensorValues”:[<”name of sensor”>

 ]

}

Vehicles that have PTOs will display the Sensor’s name if the GPS plot referenced has an active PTO ON.

Battery Level

    "BatteryLevel": null,

 

The percentage of Battery remaining for Electric Vehicles

Traction Battery Charging Last Start Utc

    "TractionBatteryChargingLastStartUtc": null,

 

The value of the charging start date/time for Electric Vehicles.

Traction Battery Charging Utc

    "TractionBatteryChargingUtc": null,

 

The value of the charging end date/time for Electric Vehicles.

Update UTC

     UpdateUTC”:””

}

The date and time stamp when the GPS plot was received.

Format: xxxx-xx-xxTxx:xx:xx

YEAR-MONTH-DAY T HOURS-MINUTES-SECONDS

Total Fuel Used

     "TotalFuelUsed": null,

 

Total Idle Fuel

     "TotalIdleFuel": null,

 

Total PTO Time

     "TotalPTOTime": null,

 

VIN

     "VIN": null,

 

When an ECM device is compatible to send the vehicle’s VIN, the value will be included in the API if the referenced plot includes this information.

Note: Compatible ECM devices that extract vehicle VIN details do not include VIN on every plot sent to REVEAL.  VIN details are sent on specific intervals so that every plot does not include this information.

Battery Voltage

     "BatteryVoltage": null

}

Battery Voltage is the Power Supply Voltage for an ICE vehicle.

Please note: The value will default to NULL if no data is captured for Battery Voltage of an ICE vehicle.