1. Home
  2. Table check
In this Article
Back Download PDF

Table check

APIs
 

 

Caterpillar VisionLink APIs enable dealers and customers to access the fleet data remotely reported by the VisionLink® application.

The VisionLink APIs eliminates the need to “mine” the data from the VisionLink application. For example, data can be provided to an ERP system, to a project management scheduling tool of choice, or to a field service dispatching application.

Most of the data elements that are available for a specific asset by subscription can be obtained through the VisionLink API.

VisionLink APIs include:

  • Assets Operation History API
  • Assets Summary API
  • Faults History API
  • Asset Fence History API
  • Utilization History API

The new Caterpillar VisionLink APIs replace the legacy and unified VisionLink APIs. The legacy-unified-to-new API mappings is as follows:

VisionLink APIs (V1.0,V2.0) New VisionLink APIs (V3.0)
Events: https://www.myvisionlink.com/APIService/CATDataTopics/v5/feed/Trimb/Event/0

Diagnostic: https://www.myvisionlink.com/APIService/CATDataTopics/v4/feed/Trimb/Diagnostic/0

Health: https://cloud.api.trimble.com/visionlink/vlfault/1.0/Health/Faults/Search/v2		 Faults History API
Start/Stop: https://www.myvisionlink.com/APIService/CATDataTopics/v3/feed/Trimb/StartStop/0

Engine: https://www.myvisionlink.com/APIService/CATDataTopics/v6/feed/Trimb/Engine/0

Unified Asset Operation: https://cloud.api.trimble.com/visionlink/ulutilization/1.0/AssetOperation

Unified Asset Operation v2: https://cloud.api.trimble.com/visionlink/vlutilization/1.0/Utilization/AssetOperation/V2		 Asset Operation History API
Fence Alert: https://www.myvisionlink.com/APIService/CATDataTopics/v6/feed/Trimb/FenceAlert/0 Asset Fence History API
Asset Utilization: https://api.myvisionlink.com/AssetUtilization

Fuel Utilization: https://api.myvisionlink.com/FuelUtilization

Unified Utilization: https://cloud.api.trimble.com/visionlink/vlutilization/1.0/UnifiedFleet/Utilization/v2

Unified Utilization Details: https://cloud.api.trimble.com/visionlink/vlutilization/1.0/Utilization/details/v2		 Utilization History API
Assets: https://api.myvisionlink.com/Assets

Fleet Summary: https://www.myvisionlink.com/APIService/VISIONLINKReady/FleetSummary

Unified Fleet Summary: https://cloud.api.trimble.com/visionlink/vlfleet/1.0/UnifiedFleet/FleetSummary/v2

Unified Asset Details: https://cloud.api.trimble.com/visionlink/vlfleet/1.0/UnifiedFleet/AssetDetails/v2		 Asset Summary API

Note: The telematics data previously available through the AEMP 1.2 API is now provided through the ISO 15143-3 (AEMP 2.0). For detailed information about ISO-15143 (AEMP 2.0) API, see the ISO-15143 (AEMP 2.0) API Developer Guide.

Data Mapping

The following tables present the data mapping between the legacy, unified and new VisionLink APIs.

Utilization History API

New Utilization History API Legacy Asset Utilization API Legacy Fuel Utilization API Unified Utilization API Unified Utilization Details API
make MakeCode MakeCode makeCode makeCode
serialNumber SerialNumber SerialNumber serialNumber assetSerialNumber
equipment id AssetID AssetID n/a assetId
model Model Model model model
productFamily n/a n/a n/a n/a
unitInstallDate n/a n/a n/a n/a
customName n/a n/a n/a n/a
customValue n/a n/a n/a n/a
assetLocalDate CalendarDayAssetLocalTime CalendarDayAssetLocalTime date (UTC) date (UTC)
idleHours IdleHours IdleHours idleHours idleHours
workingHours WorkingHours WorkingHours workingHours workingHours
runtimeHours RuntimeHours RuntimeHours runtimeHours runtimeHours
workingEfficiency EfficiencyPercentage n/a workingEfficiency workingEfficiency
customUtilizationType n/a n/a n/a n/a
distanceTravelledKms n/a n/a distanceTravelledKilometers distanceTravelledKilometers
targetIdlePerformance n/a n/a targetIdlePerformance targetIdlePerformance
targetIdleHours n/a n/a targetIdle targetIdle
targetRuntimeHours ExpectedRuntimeHours n/a targetRuntime targetRuntime
targetRuntimePerformance n/a n/a targetRuntimePerformance targetRuntimePerformance
runtimeHours (hourCallouts) n/a n/a runtimeHoursCalloutTypes runtimeHoursCalloutTypes
idleHours(hourCallouts) n/a n/a idleHoursCalloutTypes idleHoursCalloutTypes
workingHours (hourCallouts) n/a n/a workingHoursCalloutTypes workingHoursCalloutTypes
runtimeFuelBurnedLiters n/a RuntimeFuelBurnedGallons runtimeFuelConsumedLiters runtimeFuelConsumedLiters
idleFuelBurnedLiters n/a IdleFuelBurnedGallons idleFuelConsumedLiters idleFuelConsumedLiters
workingFuelBurnedLiters n/a WorkingFuelBurnedGallons workingFuelConsumedLiters workingFuelConsumedLiters
runtimeFuelBurnRate n/a RuntimeFuelBurnRate runtimeFuelConsumptionRate runtimeFuelConsumptionRate
idleFuelBurnRate n/a IdleFuelBurnRate idleFuelConsumptionRate idleFuelConsumptionRate
workingFuelBurnRate n/a WorkingFuelBurnRate workingFuelConsumptionRate workingFuelConsumptionRate
mileage n/a n/a kmsPerRuntimeFuelConsumedLiter kmsPerRuntimeFuelConsumedLiter
runtimeFuelBurned(fuelCallouts) n/a n/a runtimeFuelConsumedLitersCalloutTypes runtimeFuelConsumedLitersCalloutTypes
idleFuelBurned (fuelCallouts) n/a n/a idleFuelConsumedLitersCalloutTypes idleFuelConsumedLitersCalloutTypes
workingFuelBurned (fuelCallouts) n/a n/a workingFuelConsumedLitersCalloutTypes workingFuelConsumedLitersCalloutTypes
latestUtilizationReport n/a n/a lastReportedTime lastReportedTime
defBurnedLiters n/a n/a dieselExhaustFluidLiters dieselExhaustFluidLiters
defBurnRate n/a n/a dieselExhaustFluidLitersBurnedRate dieselExhaustFluidLitersBurnedRate
deviceStatus n/a n/a n/a n/a
co2EmissionsKilogram n/a n/a cO2Emission co2Emission
assetStatus n/a n/a n/a n/a
nextCursor n/a n/a n/a n/a

Asset Fence History API

New Asset Fence History API Fence Alert API
make make
model model
serialNumber serialNumber
equipment ID nickname
productFamily n/a
customName n/a
customValue n/a
receivedTime receivedTime
event n/a
(fence) name n/a
(fence) id n/a
nextCursor n/a

Faults History API

New Faults History API Legacy Diagnostic API Legacy Events API Legacy Health API
make make make makeCode
model model model model
serialNumber serialNumber serialNumber serialNumber
equipmentId n/a n/a n/a
productFamily n/a n/a productFamily
customName n/a n/a n/a
customValue n/a n/a n/a
severity n/a n/a severityLabel/severityLevel
eid n/a eid n/a
fmi fmi n/a n/a
cid n/a n/a n/a
spn spn n/a n/a
faultType n/a n/a faultType
faultDescription n/a n/a faultDescription
mid mid mid n/a
sourceDescription n/a n/a sourceDescription
faultReceivedTime receivedTime n/a faultReceivedUtc
faultOccuredTime timestamp timestamp faultOccuredUTC
occurrences occurances occurances occurrences
dataLinkType n/a n/a dataLinkType
hourMeter n/a n/a hourMeter
odometerInKilometer n/a n/a odometer
assetLocalDate n/a n/a n/a
latitude n/a n/a locationLatitude
longitude n/a n/a locationLongitude
address n/a n/a n/a
nextCursor n/a n/a n/a

Asset Operation History API

New Asset Operations API Legacy Asset Operation API Legacy Engine Parameters API Legacy Engine StartStop API Unified AssetOperation V2 API
Make MakeCode make make makeCode
Serial Number SerialNumber serialNumber serialNumber serialNumber
equipment id AssetID moduleCode moduleCode assetId
Model Model model model model
productFamily n/a n/a n/a productFamily
assetOperationDateInfo n/a n/a n/a n/a
eventType WorkingState Starts

idleTime (Value)		 startStop n/a
eventTime n/a idleTime (UOM) start

stop		 n/a
customName n/a n/a n/a customStateDescription
customValue n/a n/a n/a n/a
revolutions n/a revolution n/a n/a
startStateTime StartStateUtc n/a n/a startTimeUtc
startStateAssetLocalTime StartStateAssetLocalTime n/a n/a startTimeLocal
startStateAssetTimezoneAbbrev n/a n/a n/a n/a
endStateUtc EndStateUtc n/a n/a endTimeUtc
endStateAssetLocalTime EndStateAssetLocalTime n/a n/a endTimeLocal
endStateAssetTimezoneAbbrev n/a n/a n/a n/a
durationSeconds DurationSeconds n/a n/a totalRuntimeDurationSeconds
customUtilizationCategory WorkDefinition n/a n/a n/a
segmentType n/a n/a n/a segmentType
ApiTrackingId n/a n/a n/a n/a
MakeSerialNumbers n/a n/a n/a n/a
responseMetadata n/a n/a n/a n/a
nextCursor n/a n/a n/a n/a
latitude (start state) Latitude (Start location) n/a n/a startLocationLatitude
longitude(start state) Longitude(Start location) n/a n/a startLocationLongitude
latitude (end state) Latitude (End location) n/a n/a endLocationLatitude
longitude(end state) Longitude(End location) n/a n/a endLocationLongitude
code n/a n/a n/a n/a
details n/a n/a n/a n/a
AdditionalInfo n/a n/a n/a n/a
subCode n/a n/a n/a code
field n/a n/a n/a n/a
message n/a n/a n/a message

Asset Summary API

New Asset Summary API Legacy Assets Utilization API Legacy Fleet Summary API Unified Fleet Summary API Unified Asset Details API
make MakeCode MakeCode makeCode makeCode
makeDescription MakeName n/a n/a n/a
model Model Model model model
serialNumber SerialNumber SerialNumber assetSerialNumber assetSerialNumber
equipmentId AssetID AssetID assetId assetId
productFamily ProductFamily n/a productFamily productFamily
assetStatus n/a LastKnownStatus status status
deviceStatus n/a n/a n/a deviceState
deviceType DeviceType n/a deviceType deviceType
deviceSerialNumber DeviceSerialNumber n/a n/a deviceSerialNumber
mainboardSoftwareVersion n/a n/a mainboardSoftwareVersion mainboardSoftwareVersion
radioFirmwarePartNumber n/a n/a n/a radioFirmwarePartNumber
gatewayFirmwarePartNumber n/a n/a n/a gatewayFirmwarePartNumber
dataLinkType n/a n/a n/a dataLinkType
name - geofence n/a n/a name name
areaSqm - geofence n/a n/a areaSqM areaSqM
name - groups n/a n/a n/a n/a
subscription n/a n/a n/a n/a
hourMeter n/a n/a hourMeter hourMeter
lastReportedTime n/a n/a lastHourMeterUTC lastHourMeterUTC
userEnteredRuntimeHours n/a n/a n/a n/a
odometerInKilometer n/a n/a odometer odometer
lastReportedTime n/a n/a lastOdometerUTC n/a
latitude n/a Latitude lastReportedLocationLatitude lastReportedLocationLatitude
longitude n/a Longitude lastReportedLocationLongitude lastReportedLocationLongitude
address n/a Address lastReportedLocation lastReportedLocation
lastReportedTimeUtc n/a LastLocationUTC lastReportedUTC lastLocationUpdateUTC
lastKnownFuelLevelPercent n/a FuelPercentRemaining fuelLevelLastReported fuelLevelLastReported
lastReportedTime n/a n/a lastPercentFuelRemainingUTC lastPercentFuelRemainingUTC
lifetimeFuelLiters n/a LifetimeFuelConsumed lifetimeFuelLiters lifetimeFuelLiters
lastReportedTime n/a n/a lastLifetimeFuelLitersUTC lastLifetimeFuelLitersUTC
defRemainingPercent n/a n/a percentDEFRemaining percentDEFRemaining
lastReportedTime n/a n/a lastPercentDEFRemainingUTC lastPercentDEFRemainingUTC
lifetimeDefLiters n/a n/a n/a lifetimeDEFLiters
lastReportedTime n/a n/a n/a lastLifetimeDEFLitersUTC
customUtilizationType n/a n/a n/a n/a
name - last operator n/a n/a lastOperatorName lastOperatorName
id - last operator n/a n/a lastOperatorID lastOperatorID
dealerName n/a n/a dealerName dealerName
dealerCode n/a n/a dealerCode n/a
dcn n/a n/a dealerCustomerNumber dealerCustomerNumber
name - Customer n/a n/a universalCustomerName universalCustomerName
ucid n/a n/a universalCustomerIdentifier universalCustomerIdentifier
customName n/a n/a n/a n/a
customValue n/a n/a n/a n/a
responseMetadata n/a n/a n/a n/a
nextCursor n/a n/a n/a n/a

Subscribing to the APIs

To access the API, you must first request a subscription:

  • Fill out the API Subscription Request Form.
  • The form will open in a new window without closing this page.
  • You may be asked to login to the Digital Marketplace again before completing the form.
  • After completing your subscription, you may close the subscription window to return to this page.
  • You will receive an email with your credentials when your subscription is approved. This process may take approximately two (2) weeks.

Security

The API uses the OAuth 2.0 protocol for authorization. In order to access the API, an OAuth access token is required in the request headers of each API call. A valid OAuth client ID and client secret is required to obtain an OAuth access token.

The following basic information is required to authenticate and generate the token.

Field Value
Grant Type Set this to "client_credentials".
Token URL https://fedlogin.cat.com/as/token.oauth2
Client ID Your application's Client ID. Contact your credentials owner.
Client Secret Your application's Client Secret. Contact your credentials owner.

An OAuth token expires after 60 minutes. An expired token will need to be replaced with a new token.

Additional OAuth information can be found in Caterpillar OAuth 2.0 Documentation.

API Environments

VisionLink APIs are only available in production environment.

Faults History API

The API returns each fault code recorded within the specified time range for the asset/fleet, along with the timestamp (UTC) when it was created. Data availability is dependent on machine support and commercial subscription. The Fault History API helps in determining the health of the machine by analyzing the various faults reported along with source, type, and severity.

Sample request

curl -v -X GET \
"https://services.cat.com/catDigital/faultsHistory/v1/faults" -H "Authorization: Bearer {token}" \
-H 'Accept: application/json' \

Use Accept header to specify the response format:

  • JSON - application/json
  • XML - application/xml

JSON is the default response format.

Sample JSON response

{
  "faults": [
    {
      "equipmentHeader": {
        "make": "CAT",
        "model": "368B",
        "serialNumber": "FA12345L-2D",
        "equipmentId": "myfavasset",
        "productFamily": "Motor Grader",
        "customFields": [
          {
            "customName": "region",
            "customValue": "North America"
          }
        ]
      },
      "faultBlock": {
        "severity": "Medium",
        "eid": 878,
        "fmi": 5,
        "cid": 247,
        "spn": 521891,
        "faultType": "Event",
        "faultDescription": "After treatment SCR Operator Inducement Severity - Data Valid But Above Normal Operational Range - Most Severe Level.",
        "mid": 299,
        "sourceDescription": "Steering Control",
        "faultReceivedTime": "2020-03-06T17:27:04.222Z",
        "faultOccuredTime": "2020-03-06T17:27:04.222Z",
        "occurrences": 127
      },
      "dataLinkType": "J1939",
      "hourMeter": 1583.2,
      "odometerInKilometer": 214.7,
      "assetLocalDate": "2016-01-31",
      "location": {
        "latitude": 38.07671,
        "longitude": -78.50494,
        "address": "201 Lambs Lane, Charlottesville, VA, Albemarle, United States, 22901."
      }
    }
  ],
  "responseMetadata": {
    "nextCursor": "eyJvZmZzZXQiOjR9"
  }
}

Depending on the combination of query parameters, the default value of the limit parameter defining the response size can be 500 ("bulk") or 50 records ("lightweight").

Use these query parameters to return a bulk response (500 records maximum):

  • all input query parameters blank
  • all optional query parameters specified: make, model, productFamily, dealerCode, language, ucid, faultType, deviceType, and cursor
  • severity
  • faultType
  • deviceType
  • make
  • model
  • productFamily
  • ucid
  • dealerCode
  • language
  • cursor
  • limit and startTime and endTime for a date range of 3 months from the current date
  • startTime and endTime for a date range of 3 months from the current date
  • limit and occurredTime within 3 month from the current date
  • limit and occurredTime
  • limit, faultType, startTime and endTime for a date range of 3 months from the current date
  • limit, severity, startTime and endTime for a date range of 3 months from the current date
  • limit, deviceType, startTime and endTime for a date range of 3 months from the current date
  • limit, model, startTime and endTime for a date range of 3 months from the current date
  • limit, make, startTime and endTime for a date range of 3 months from the current date
  • limit, productFamily, startTime and endTime for a date range of 3 months from the current date
  • limit, ucid, startTime and endTime for a date range of 3 months from the current date
  • limit, language,startTime and endTime for a date range of 3 months from the current date

Use these query parameters to return a lightweight response (50 records maximum):

  • limit and startTime and endTime for a date range of 1 month from the current date
  • limit, faultType, and startTime and endTime for a date range of 1 month from the current date
  • limit, language, and startTime and endTime for a date range of 1 month from the current date
  • limit, severity, and startTime and endTime for a date range of 1 month from the current date
  • limit and occurredTime within 1 month from the current date
  • limit, faultType, and occurredTime within 1 month from the current date
  • limit, severity, and occurredTime within 1 month from the current date
  • limit, language, and occurredTime within 1 month from the current date

You can paginate through the response data using the responseMetadata.nextCursor value in the cursor query parameter.

For detailed information about the API input parameters, response structure, and error messages, see the API reference documentation.

Asset Operation History API

The Asset Operation API returns the asset operation and asset operation feed data such as engine stop and start events.

Get Asset Operations History

To get asset operation data, use the GET https://services.cat.com/catDigital/assetOperationsHistory/v1/assetOperations endpoint.

Sample request

curl -v -X GET \
"https://services.cat.com/catDigital/assetOperationsHistory/v1/assetOperations" -H "Authorization: Bearer {token}" \
-H 'Accept: application/json' \

Use Accept header to specify the response format:

  • JSON - application/json
  • XML - application/xml

JSON is the default response format.

Sample JSON response

{
  "assetOperations": [
    {
      "equipmentHeader": {
        "make": "CAT",
        "model": "368B",
        "serialNumber": "FA12345L-2D",
        "equipmentId": "Myfavasset",
        "productFamily": "Motor Grader",
        "customFields": [
          {
            "customName": "region",
            "customValue": "North America"
          }
        ]
      },
      "calendarDayAssetLocalDate": "2016-01-31",
      "assetOperationDateInfo": [
        {
          "revolutions": "18",
          "startStateTime": "2020-03-06T17:27:04.222Z",
          "startStateAssetLocalTime": "2020-03-06T17:27:04.222Z",
          "startStateAssetTimezoneAbbrev": "EDT",
          "startLocation": {
            "latitude": 40.69223,
            "longitude": -89.58893
          },
          "endStateUtc": "2020-03-06T17:27:04.222Z",
          "endStateAssetLocalTime": "High Torque Converter Oil Temperature",
          "endStateAssetTimezoneAbbrev": "EDT",
          "endLocation": {
            "latitude": 40.69223,
            "longitude": -89.58893
          },
          "durationSeconds": "2017-10-31T11:52:32.0000000+00:00",
          "customUtilizationCategory": "Movement, Machine Sourced, Switches Movement, or Switches",
          "segmentType": "Running/Idle/Working"
        }
      ]
    }
  ],
  "responseMetadata": {
    "nextCursor": "eyJvZmZzZXQiOjR9"
  }
}

Depending on the combination of query parameters, the default value of the limit parameter defining the response size can be 500 ("bulk") or 50 records ("lightweight").

Use these query parameters to return a bulk response (500 records maximum):

  • all input query parameters blank
  • all optional query parameters specified: make, model, productFamily, dealerCode, ucid
  • make
  • model
  • productFamily
  • ucid
  • dealerCode
  • cursor
  • limit and startTime and endTime for a date range of 3 months from the current date
  • startDate and endTime for a date range of 3 months from the current date
  • limit, model, startDate and endTime for a date range of 3 months from the current date
  • limit, make, startDate and endTime for a date range of 3 months from the current date
  • limit, productFamily, startDate and endTime for a date range of 3 months from the current date
  • limit, ucid, startDate and endTime for a date range of 3 months from the current date

Use these query parameters to return a lightweight response (50 records maximum):

  • limit, make, serialNumber, and startDate and endTime for a date range of 1 month from the current date
  • limit and startDate and endTime for a date range of 1 month from the current date
  • makeSerialNumbers (an array of values)

You can paginate through the response data using the responseMetadata.nextCursor value in the cursor query parameter.

The following table provides the detailed information about the response data:

Field Name Type Description Sample
Equipment Header Block      
make String Make code of the asset CAT
model String Model of the Asset 368B
serialNumber String Serial number of the asset FA12345L-2D
equipmentId String Nickname or Equipment ID or Asset ID myfavasset
productFamily String Product family to which the machine belongs to Motor Grader
Custom Fields Block      
customName String Name of the custom variable being passed region
customValue String Value of the custom variable being passed America
Asset Operations Block      
calendarDayAssetLocalDate String($date) A date 2016-01-31
AssetOperationDateInfo Block      
revolutions String The total number of engine revolutions 18
startStateTime String($date-time) A date-time 2020-03-06T17:27:04.222Z
startStateAssetLocalTime String($date-time) A date-time 2020-03-06T17:27:04.222Z
startStateAssetTimezoneAbbrev String Abbreviation of the asset's local timezone at the time of start of the operation segment EDT
startLocation number($double) Asset start location N/A
endStateUtc String($date-time) A date-time 2020-03-06T17:27:04.222Z
endStateAssetLocalTime String Description of the fault for the specified language High Torque Converter Oil Temperature
endStateAssetTimezoneAbbrev String Abbreviation of the asset's local timezone at the time of end of the operation segment EDT
endLocation number($double) Asset end location N/A
durationSeconds String($date-time) Date time in UTC that the diagnostic received 2017-10-31T11:52:32.0000000+00:00
customUtilizationCategory String Describes on what basis the working state of the machine is interpreted Movement, Machine Sourced, Switches Movement, or Switches
segmentType String Segment types Running/Idle/Working
Location Block      
latitude number($double) Latitude of the location. Minimum -90 maximum 90 38.07671
longitude number($double) Latitude of the location, Minimum -180, maximum: 180 -78.50494
address String Reverse geolocation 201 Lambs Lane, Charlottesville, VA, Albemarle, United States, 22901
Error Block      
code String Error Code represents an alpha-numeric error code received from the error 400.100
description String Message represents a textual description of a given error code EndTime format is invalid
details String Details represents technical details about the error with additional message N/A
AdditionalInfo Block      
subCode String Error code sent by API for each validation 100
field String The property or field that was validated and triggered an error endTime
message String Each error message on the property level validation done by the API endTime must be in UTC format

Note: Once the Asset Operations API is published in the Digital Marketplace API Catalog, use the OpenAPI spec for detailed reference information.

Get Asset Operation Feeds

To get asset operation feed data, use the GET https://services.cat.com/catDigital/assetOperationsHistory/v1/feeds endpoint.

Sample request

curl -v -X GET \
"https://services.cat.com/catDigital/assetOperationsHistory/v1/feeds" -H "Authorization: Bearer {token}" \
-H 'Accept: application/json' \

Use Accept header to specify the response format:

  • JSON - application/json
  • XML - application/xml

JSON is the default response format.

Sample JSON response

{
  "assetOperationFeeds": [
    {
      "equipmentHeader": {
        "make": "CAT",
        "model": "368B",
        "serialNumber": "FA12345L-2D",
        "equipmentId": "MyfavAsset",
        "productFamily": "Motor Grader",
        "customFields": [
          {
            "customName": "region",
            "customValue": "North America"
          }
        ]
      },
      "calendarDayAssetLocalTime": "11-11-2020 11:11:23",
      "eventType": "Engine Start, Engine Stop, Movement Start, Movement Stop, Idle Start, Idle Stop.",
      "eventTime": "2020-03-06T17:27:04.222Z"
    }
  ],
  "responseMetadata": {
    "nextCursor": "eyJvZmZzZXQiOjR9"
  }
}

Asset operation feed response size, filtering, and pagination follow the same rules as the GET /assetOperations] endpoint.

The following table provides the detailed information about the response data:

Field Name Type Description Sample
Equipment Header Block      
make String Make code of the asset CAT
model String Model of the Asset 368B
serialNumber String Serial number of the asset FA12345L-2D
equipmentId String Nickname or Equipment ID or Asset ID myfavasset
productFamily String Product family to which the machine belongs to Motor Grader
Custom Fields Block      
customName String Name of the custom variable being passed region
customValue String Value of the custom variable being passed America
Asset Operation Feeds Block      
calendarDayAssetLocalTime String CalendarDay Asset LocalTime 11-11-2020 11:11:23
eventType String Event Types Engine Start, Engine Stop, Movement Start, Movement Stop, Idle Start, Idle Stop
eventTime String($date-time) A date-time 2020-03-06T17:27:04.222Z
Error Block      
code String Error Code represents an alpha-numeric error code received from the error 400.100
description String Message represents a textual description of a given error code EndTime format is invalid
details String Details represents technical details about the error with additional message N/A
AdditionalInfo Block      
subCode String Error code sent by API for each validation 100
field String The property or field that was validated and triggered an error endTime
message String Each error message on the property level validation done by the API endTime must be in UTC format

Note: Once the Asset Operations API is published in the Digital Marketplace API Catalog, use the OpenAPI spec for detailed reference information.

Asset Fence History API

The Asset Fence History API returns the site entry and site exit events reported for assets for a given period of time.

Sample request

curl -v -X GET \
"https://services.cat.com/catDigital/assetFenceHistory/v1/fences" -H "Authorization: Bearer {token}" \
-H 'Accept: application/json' \

Use Accept header to specify the response format:

  • JSON - application/json
  • XML - application/xml

JSON is the default response format.

Sample JSON response

{
  "fences": [
    {
      "equipmentHeader": {
        "make": "CAT",
        "model": "368B",
        "serialNumber": "FA12345L-2D",
        "equipmentId": "myfavasset",
        "productFamily": "Motor Grader",
        "customFields": [
          {
            "customName": "region",
            "customValue": "North America"
          }
        ]
      },
      "receivedTime": "2020-03-06T17:27:04Z",
      "event": "entry",
      "fence": {
        "name": "Chicago Grant Park",
        "id": "XYZFence"
      }
    }
  ],
  "responseMetadata": {
    "nextCursor": "eyJvZmZzZXQiOjR9"
  }
}

Depending on the combination of query parameters, the default value of the limit parameter defining the response size can be 500 ("bulk") or 50 records ("lightweight").

Use these query parameters to return a bulk response (500 records maximum):

  • all input query parameters blank
  • all optional query parameters specified: make, model, productFamily, group, ucid
  • make
  • model
  • productFamily
  • ucid
  • group
  • limit and startDate and endTime for a date range of 3 months from the current date
  • startDate and endTime for a date range of 3 months from the current date
  • limit, model, startDate and endTime for a date range of 3 months from the current date
  • limit, make, startDate and endTime for a date range of 3 months from the current date
  • limit, productFamily, startDate and endTime for a date range of 3 months from the current date
  • limit, group, startDate and endTime for a date range of 3 months from the current date
  • limit, ucid, startDate and endTime for a date range of 3 months from the current date

Use these query parameters to return a lightweight response (50 records maximum):

  • limit, make, serialNumber, and startDate and endTime for a date range of 1 month from the current date
  • limit and startDate and endTime for a date range of 1 month from the current date
  • makeSerialNumbers (an array of values)

You can paginate through the response data using the responseMetadata.nextCursor value in the cursor query parameter.

For detailed information about the API input parameters, response structure, and error messages, see the API reference documentation.

Utilization History API

The Utilization API returns asset and fuel utilization data that provides a reading of how efficiently your assets are using fuel per targets set for them.

Sample request

curl -v -X GET \
"https://services.cat.com/catDigital/utilizationHistory/v1/utilization" -H "Authorization: Bearer {token}" \
-H 'Accept: application/json' \

Use Accept header to specify the response format:

  • JSON - application/json
  • XML - application/xml

JSON is the default response format.

Sample JSON response

{
  "utilizations": [
    {
      "equipmentHeader": {
        "make": "CAT",
        "model": "368B",
        "serialNumber": "FA12345L-2D",
        "equipmentId": "Myfavasset",
        "productFamily": "Motor Grader",
        "unitInstallDate": "2020-03-06T17:27:04.222Z",
        "customFields": [
          {
            "customName": "region",
            "customValue": "North America"
          }
        ]
      },
      "assetLocalDate": "2016-01-31",
      "runtimeHours": 10.2,
      "idleHours": 3.6,
      "workingHours": 6.6,
      "customUtilizationType": "Movement",
      "distanceTravelledKms": 122.7,
      "workingEfficiency": 78,
      "targetIdlePerformance": 13,
      "targetIdleHours": 1.6,
      "targetRuntimeHours": 8.1,
      "targetRuntimePerformance": 88,
      "hourCallouts": {
        "runtimeHours": "Invalid value detected/detected in date range",
        "idleHours": "Invalid value detected/detected in date range",
        "workingHours": "Insufficient Runtime meter precision for valid calculation"
      },
      "runtimeFuelBurnedLiters": 27.5,
      "idleFuelBurnedLiters": 3.2,
      "workingFuelBurnedLiters": 24.3,
      "runtimeFuelBurnRate": 2.9,
      "idleFuelBurnRate": 0.9,
      "workingFuelBurnRate": 3.8,
      "mileage": 1.3,
      "fuelCallouts": {
        "runtimeFuelBurned": "Invalid value detected/detected in date range",
        "idleFuelBurned": "Invalid value detected/detected in date range",
        "workingFuelBurned": "Invalid value detected/detected in date range"
      },
      "latestUtilizationReport": "2021-07-13 23:52 CDT",
      "defBurnedLiters": 0.8,
      "defBurnRate": 0.1,
      "deviceStatus": "Not Reporting",
      "co2EmissionsKilogram": 590.5,
      "assetStatus": "Ready to Run"
    }
  ],
  "responseMetadata": {
    "nextCursor": "eyJvZmZzZXQiOjR9"
  }
}

Depending on the combination of query parameters, the default value of the limit parameter defining the response size can be 500 ("bulk") or 50 records ("lightweight").

Use these query parameters to return a bulk response (500 records maximum):

  • all input query parameters blank
  • all optional query parameters specified: make, model, productFamily, dealerCode, subscription, ucid, startDate, endDate, and cursor
  • make
  • model
  • productFamily
  • ucid
  • dealerCode
  • subscription
  • cursor
  • limit, make, startDate and endDate for a date range of 3 months from the current date
  • limit, model, startDate and endDate for a date range of 3 months from the current date
  • limit, productFamily, startDate and endDate for a date range of 3 months from the current date
  • limit, ucid, startDate and endDate for a date range of 3 months from the current date
  • limit, dealerCode, startDate and endDate for a date range of 3 months from the current date
  • limit, subscription,startDate and endDate for a date range of 3 months from the current date

Use these query parameters to return a lightweight response (50 records maximum):

  • limit, make, serialNumber, and startDate and endDate for a date range of 3 months from the current date
  • makeSerialNumbers (an array of values)

You can paginate through the response data using the responseMetadata.nextCursor value in the cursor query parameter.

For detailed information about the API input parameters, response structure, and error messages, see the API reference documentation.

Asset Summary API

The Asset Summary API returns the summary of each asset within the fleet view.

Sample request

curl -v -X GET \
"https://services.cat.com/catDigital/assetSummary/v1/assets" -H "Authorization: Bearer {token}" \
-H 'Accept: application/json' \

Sample JSON response

{
  "assetSummaries": [
    {
      "equipmentHeader": {
        "make": "CAT",
        "makeDescription": "Komatsu",
        "model": "368B",
        "serialNumber": "FA12345L-2D",
        "equipmentId": "Myfavasset",
        "productFamily": "Motor Grader"
      },
      "assetStatus": "Ready to Run",
      "deviceStatus": "Not Reporting",
      "deviceInfo": {
        "deviceType": "PLE742",
        "deviceSerialNumber": "2090F001TR",
        "mainboardSoftwareVersion": "6013399-00",
        "radioFirmwarePartNumber": "6013399-00",
        "gatewayFirmwarePartNumber": "6013399-00",
        "dataLinkType": "J1939"
      },
      "geofences": [
        {
          "name": "testgeofence",
          "areaSqm": 33.33
        }
      ],
      "groups": [
        {
          "name": "testgroup"
        }
      ],
      "subscription": "VisionlinkDaily",
      "hourMeter": {
        "value": 2356.7,
        "lastReportedTime": "2020-03-06T17:27:04.222Z"
      },
      "userEnteredRuntimeHours": 2500.8,
      "odometerInKilometer": {
        "value": 2356.7,
        "lastReportedTime": "2020-03-06T17:27:04.222Z"
      },
      "lastKnownLocation": {
        "latitude": 38.07671,
        "longitude": -78.50494,
        "address": "201 Lambs Lane, Charlottesville, VA, Albemarle, United States, 22901"
      },
      "lastReportedTimeUtc": "2020-03-06T17:27:04.222Z",
      "lastKnownFuelLevelPercent": {
        "value": 73,
        "lastReportedTime": "2020-03-06T17:27:04.222Z"
      },
      "lifetimeFuelLiters": {
        "value": 2322,
        "lastReportedTime": "2020-03-06T17:27:04.222Z"
      },
      "defRemainingPercent": {
        "value": 219.6,
        "lastReportedTime": "2020-03-06T17:27:04.222Z"
      },
      "lifetimeDefLiters": {
        "value": 219.6,
        "lastReportedTime": "2020-03-06T17:27:04.222Z"
      },
      "customUtilizationType": "Movement",
      "lastOperator": {
        "name": "Harry Hoggard",
        "id": 123456
      },
      "dealerInfo": {
        "dealerName": "Caterpillar Demo Dealer",
        "dealerCode": "TD00",
        "dcn": "1134ABC"
      },
      "customerInfo": {
        "name": "Demo Customer",
        "ucid": 2968305643
      },
      "customFields": [
        {
          "customName": "region",
          "customValue": "North America"
        }
      ]
    }
  ],
  "responseMetadata": {
    "nextCursor": "eyJvZmZzZXQiOjR9"
  }
}

Use Accept header to specify the response format. Specify application/xml for XML. Specify application/json for JSON. JSON is the default response format.

Depending on the combination of query parameters, the default value of the limit parameter defining the response size can be 500 ("bulk") or 50 records ("lightweight").

Use these query parameters to return a bulk response (500 records maximum):

  • all input query parameters blank
  • all optional query parameters specified: limit, make, model, productFamily, dealerCode, subscription, ucid, cursor, deviceType
  • deviceType
  • make
  • model
  • productFamily
  • ucid
  • dealerCode
  • subscription
  • cursor

Use these query parameters to return a lightweight response (50 records maximum):

  • limit, make, serialNumber, and startDate and endDate for a date range of 1 months from the current date
  • makeSerialNumbers (an array of values)

You can paginate through the response data using the responseMetadata.nextCursor value in the cursor query parameter.

For detailed information about the API input parameters, response structure, and error messages, see the API reference documentation.

Additional Documentation

The following additional documentation is available as part of the VisionLink APIs bundle:

Glossary

CID

Component Identifier (CID) identifies the on-board sensor that reported the diagnostic.

CWS

Caterpillar Corporate Web Security (CWS). CWS ID and password are created when an account is created within Caterpillar. The credentials can be used to log into various systems and applications within Caterpillar.

EID

Event ID (EID) identifies the specific event that was generated.

FMI

Failure Mode Indicator (FMI) identifies the diagnostic.

MID

Machine Component Identifier (MID) reporting the event.

SMU

Service Meter Unit.

Change History

Date Description of Change
11-21-2022 New document.
1-24-2023 Add review comments of Product Owner on API naming.

Related Articles

Art05065Art05065Modified

testtest modifiedArt05065
Art05064

test
Art05064

test
CAT QR
/apis/products/qa/cat-qr