1. Home
  2. Document
  3. Anchor visibility Document preprod

Anchor visibility Document preprod

Back

Anchor visibility Document preprod

APIs
Doc Mgr Test

Introduction

Caterpillar VisionLink APIs enable dealers and customers to access the fleet data remotely reported by the VisionLink® application.The asset needs to have an active Premium subscription in order to be returned in the API Feed.

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:

  • Asset Fence History API
  • Asset Operations History API
  • Asset Summary API
  • Faults 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
VisionLink APIs (V1.0,V2.0) ISO 15143-3 (AEMP 2.0) API
SMU Location Feed: https://legacy.myvisionlink.com/APIService/CATDataTopics/v4/feed/Trimb/SMULOC/0

Fuel Information Feed: https://legacy.myvisionlink.com/APIService/CATDataTopics/v4/feed/Trimb/Fuel/0

AEMP 1.2: https://www.myvisionlink.com/APIService/AEMP/v1/Fleet		 Fleet Snapshot

Equipment Snapshot
Switch Status :https://www.myvisionlink.com/APIService/CATDataTopics/v3/feed/Trimb/DigStatus3/0 TimeSeries Switch Status

Note: 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

Legacy Asset Utilization API Legacy Fuel Utilization API Unified Utilization API Unified Utilization Details API New Utilization History API
MakeCode MakeCode MakeCode MakeCode make
Serial Number Serial Number Serial Number Serial Number serialNumber
Asset ID Asset ID Asset ID Asset ID equipmentID
Model Model Model Model model
CalendarDayAssetLocalTime CalendarDayAssetLocalTime date date assetLocalDate
IdleHours IdleHours idleHours idleHours idleHours
IdleHoursCallout n/a IdleHoursCallout IdleHoursCallout hoursCallout
WorkingHours WorkingHours workingHours workingHours workingHours
WorkingHoursCallout n/a workingHoursCallout workingHoursCallout hoursCallout
RuntimeHours RuntimeHours RuntimeHours RuntimeHours RuntimeHours
RuntimeHoursCallout n/a RuntimeHourCallout RuntimeHourCallout hoursCallout
ExpectedRuntimeHours n/a targetRuntimeHours targetRuntimeHours targetRuntimeHours
RunningUtilizationPercentage n/a targetRuntimePerformance targetRuntimePerformance targetRuntimePerformance
EfficiencyPercentage n/a workingEfficiency workingEfficiency workingEfficiency
Work Definition Work Definition workDefinitionType workDefinitionType customUtilizationType
n/a IdleFuelBurnedGallons idleFuelConsumedLitres idleFuelConsumedLiters idleFuelBurnedLiters
n/a WorkingFuelBurnedGallons workingFuelConsumedLiters workingFuelConsumedLiters workingFuelBurnedLiters
n/a RuntimeFuelBurnedGallons RuntimeFuelConsumedLitres runtimeFuelConsumedLiters runtimeFuelBurnedLiters
n/a IdleFuelBurnRate idleFuelConsumptionRate idleFuelConsumptionRate idleFuelBurnRate
n/a WorkingFuelBurnRate workingFuelConsumptionRate workingFuelConsumptionRate workingFuelBurnRate
n/a RuntimeFuelBurnRate RuntimeFuelConsumptionRate runtimeFuelConsumptionRate runtimeFuelBurnRate
n/a n/a distanceTravelledKilometers distanceTravelledKilometers distanceTraveledKms
n/a n/a idleEfficiency idleEfficiency idlePercentage
n/a n/a IdleFuelCallout IdleFuelCallout fuelCallouts
n/a n/a RuntimeFuelCallout RuntimeFuelCallout fuelCallouts
n/a n/a WorkingFuelCallout WorkingFuelCallout fuelCallouts
n/a n/a targetIdleHours targetIdleHours targetIdleHours
n/a n/a targetIdlePerformance targetIdlePerformance targetIdlePerformance
n/a n/a lastReportedTimeLocal and Timezone lastReportedTimeLocal and Timezone latestUtilizationReport
n/a n/a kmsPerRuntimeFuelConsumedLiter kmsPerRuntimeFuelConsumedLiter mileage
n/a n/a lastIdleFuelConsumptionLitersMeter lastIdleFuelConsumptionLitersMeter lifetimeIdleFuelBurned
n/a n/a lastOdometerMeter lastOdometerMeter odometer
n/a n/a lastIdleHourMeter lastIdleHourMeter idleMeter
n/a n/a lastRuntimeFuelConsumptionLitersMeter lastRuntimeFuelConsumptionLitersMeter lifetimeTotalFuelBurned
n/a n/a RuntimeHourMeter RuntimeHourMeter hourMeter
VLIdentifier VLIdentifier AssetIdentifier AssetIdentifier Not available in new VisionLink
n/a n/a SupportsIdle SupportsIdle Not available in new VisionLink
WorkingUtilizationPercentage n/a Not available in Unified Fleet Not available in Unified Fleet Not available in new VisionLink
n/a n/a Asset Icon Asset Icon Not available in new VisionLink
n/a n/a hasActiveFuelSubscription hasActiveFuelSubscription Not available in new VisionLink
n/a n/a n/a n/a lifetimeDEF
n/a n/a n/a n/a customHours
n/a n/a n/a n/a defBurnedLiters
n/a n/a n/a n/a defBurnRate
n/a n/a n/a n/a deviceStatus
n/a n/a n/a n/a co2EmissionsKilogram
n/a n/a n/a n/a assetStatus
n/a n/a n/a n/a idlePercentage
n/a n/a n/a n/a odometer
n/a n/a n/a n/a productFamily

Asset Fence History API

Fence Alert API New Asset Fence History API
make make
model model
serialNumber serialNumber
Nickname(Asset/EqpID) equipmentId
receivedTime receivedTime
timeWatchActive Not available in new VisionLink
exclusiveWatchActive Not available in new VisionLink
inclusiveWatchActive Not available in new VisionLink
timeWatchAlarm Not available in new VisionLink
exclusiveWatchAlarm Not available in new VisionLink
inclusiveWatchAlarm Not available in new VisionLink
satelliteBlockage Not available in new VisionLink
disconnectSwitchUsed Not available in new VisionLink
n/a productFamily
n/a customName
n/a customValue
n/a event
n/a (fence) name
n/a (fence) id
n/a nextCursor

Faults History API

Legacy Diagnostic API Legacy Events API Unified Faults API New Faults History API
make make makeCode make
model model model model
serialNumber serialNumber serialNumber serialNumber
Nickname(Asset/EqpID) Nickname(Asset/EqpID) assetID equipmentId
n/a n/a productFamily productFamily
diagnosticsLevel eventLevel severity severity
n/a eventID n/a eid
fmi n/a n/a fmi
spn n/a n/a spn
n/a n/a faultType faultType
n/a n/a description faultDescription
mid mid n/a mid
receivedTime receivedTime faultReceivedUTC faultReceivedTime
timestamp moduleTime faultOccuredUTC faultOccurredTime
diagnosticOccurances eventOccurrences occurrences occurrences
n/a n/a dataLinkType dataLinkType
n/a n/a lastHourMeter hourMeter
n/a n/a lastOdometer odometerInKilometer
n/a n/a lastReportedLocationLatitude latitude
n/a n/a lastReportedLocationLongitude longitude
n/a n/a address address
n/a MID URL n/a Not Needed with New API
n/a EID URL n/a Not Needed with New API
URL (Diagnostics) n/a n/a Not Needed with New API
n/a n/a Operator Name Not available in new VisionLink
n/a n/a Operator ID Not available in new VisionLink
n/a n/a notifications Not available in new VisionLink
n/a n/a sourceIdentifier Not available in new VisionLink
n/a n/a n/a customName
n/a n/a n/a customValue
n/a n/a n/a cid
n/a n/a n/a sourceDescription
n/a n/a n/a nextCursor

Asset Operations History API

Legacy Asset Operation API Legacy Engine Parameters API Legacy Engine StartStop API Unified AssetOperation V2 API New Asset Operations API
MakeCode make make makeCode Make
SerialNumber serialNumber serialNumber serialNumber Serial Number
AssetID Nickname(Asset/EqpID) Nickname(Asset/EqpID) assetId equipment id
Model model model model Model
n/a n/a n/a customStateDescription customName
StartUTC n/a startUTC startTimeUtc startStateUtc
StartLocalTime n/a n/a startTimeLocal startStateAssetLocalTime
n/a n/a n/a startStateTimezoneAbbrev startStateAssetTimezoneAbbrev
EndUtc n/a stopUTC endTimeUtc endStateUtc
EndLocalTime n/a n/a endTimeLocal endStateAssetLocalTime
n/a n/a n/a endStateAssetTimezoneAbbrev endStateAssetTimezoneAbbrev
Duration n/a n/a totalRuntimeDurationSeconds durationSeconds
WorkDefinition n/a n/a WorkDefinitionType customUtilizationCategory
n/a n/a n/a segmentType segmentType
StartLocation (contains latitude) n/a n/a startLocationLatitude latitude (start location)
StartLocation (contains longitude) n/a n/a startLocationLongitude longitude (start location)
Latitude (End location) n/a n/a endLocationLatitude latitude (end location)
Longitude (End location) n/a n/a endLocationLongitude longitude (end location)
n/a Engine Starts n/a n/a Not available in Asset Operations API *
n/a Module Code Module Code n/a Not available in new VisionLink
n/a Module Time Module Time n/a Not available in new VisionLink
n/a Engine Revolutions n/a n/a Not available in new VisionLink
VL Identifier n/a n/a n/a Not available in new VisionLink
n/a n/a n/a hasActiveCoreSubscription Not available in new VisionLink
n/a n/a n/a hasActiveFuelSubscription Not available in new VisionLink
n/a n/a n/a AssetIdentifier Not available in new VisionLink
n/a n/a n/a Asset Icon Not available in new VisionLink
n/a n/a n/a dateRangeRuntimeDuration Not available in new VisionLink **
n/a n/a n/a n/a customValue
n/a n/a n/a n/a productFamily
n/a n/a n/a n/a nextCursor

* Available as eventType in Asset Operations Feed API

** This is not a total, but the runtime duration from this specific time period in this date range. A total is not provided by the API, but you can add the values of dateRangeRuntimeDuration fields together for this particular asset to get a total.

Asset Operations Feed API

The Asset Operations Feed API only contains data that was not available in any legacy API.

Asset Summary API

Legacy Assets Legacy Fleet Summary Unified Fleet Summary New Asset Summary API
VLIdentifier VLIdentifier AssetIdentifier N/A
MakeCode MakeCode MakeCode make
Manufacturer n/a Manufacturer makeDescription
Serial Number Serial Number Serial Number serialNumber
Asset ID Asset ID Asset ID equipmentId
Model Model Model model
Product Family n/a Product Family productFamily
ManufactureYear n/a ModelYear modelYear
n/a n/a Asset Icon N/A
Device Type n/a Device Type deviceType
Device SerialNumber n/a n/a deviceSerialNumber
n/a n/a mainboardSoftwareVersion mainboardSoftwareVersion
n/a n/a isGpsRollOverAffected N/A
n/a LastKnownStatus status deviceStatus
n/a RuntimeHours hourMeter hourMeter
n/a n/a lastHourMeterUTC lastReportedTime
n/a n/a odometer odometerInKilometer
n/a n/a lastOdometerUTC lastReportedTime
n/a Latitude lastReportedLocationLatitude latitude
n/a Longitude lastReportedLocationLongitude longitude
n/a Address Address address
n/a LastLocationUTC LocationUTC lastReportedTimeUtc
n/a FuelPercentRemaining fuelLevelLastReported lastKnownFuelLevelPercent
n/a LifetimeFuelConsumed lifetimeFuelLiters lifetimeFuelLiters
n/a n/a percentDEFRemaining defRemainingPercent
n/a n/a notifications n/a
n/a n/a customStateDescription customAssetState
n/a n/a lastOperatorName n/a
n/a n/a lastOperatorID n/a
n/a n/a fenceIdentifier n/a
n/a SiteName geofenceName name n/a geofence
n/a n/a areaSqM areaSqm n/ageofence
n/a Speed(MPH) Speed(KMH) n/a
n/a Altitude (m) Altitude (Km) n/a
n/a n/a DC Name dcn
n/a n/a DCN n/a
n/a n/a DealerCode dealerCode
n/a n/a DealerName dealerName
n/a n/a UC Name customInfo n/a name
n/a n/a UCID customInfo n/a ucid
n/a n/a ObjectType customName, customValue
n/a n/a Category customName, customValue
n/a n/a ProjectStatus customName, customValue
n/a n/a SortField customName, customValue
n/a n/a Source source
n/a n/a Classification customName, customValue
n/a n/a userEnteredRuntimeHours n/a
n/a n/a Planning Group customName, customValue
n/a n/a region customName, customValue
n/a n/a district customName, customValue
n/a n/a project customName, customValue
n/a mileage n/a n/a
n/a n/a n/a radioFirmwarePartNumber
n/a n/a n/a gatewayFirmwarePartNumber
n/a n/a n/a dataLinkType
n/a n/a n/a assetStatus
n/a n/a n/a name n/agroups
n/a n/a n/a subscription
n/a n/a n/a lifetimeDefLiters
n/a n/a n/a customUtilizationType

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.

"Duplicate" values

This data is coming in pages for easier and more reliable transfer. However, especially in very large datasets, you may see duplicate entries in the data returned by the API. This happens because the data is "in-flight" - that is, the data you had asked for was altered in the middle of you receiving data.

Here's an example: You have 10 pages of data, and you have called 3 times to get 3 pages of data.

Let's assume there is an entry at the very end of page 3. If a new entry is added to the database, and it would have appeared on page 1 under the order by and sort by constraints of your query, several things occur:

  1. You won't see the new entry (at least until you make another query). Its position is on a page that you've already called for.

  2. The entry that used to be on the very end of page 3 would have been bumped forward in the order by one. Since it was on the boundary of a page, that means it will appear again on page 4.

These sorts of issues are common with APIs, particularly ones that deal with large datasets. Please be aware of this, and set your systems to account for these duplicate records appropriately.

Request Limits

For each user of the Visionlink API, there is a limit of 50,000 requests per day shared between the 6 endpoints of the API.

That means you could use all 50,000 calls on Fault History. In another scenario, you could also make 30,000 calls to Utilization History, 10,000 calls to Asset Operation History, and 10,000 to Fault History.

If you exceed this limit, you will receive the following error:

{
  "code": "429.002",
  "description": "Quota rate limit exceeded."
}

If this occurs, the request will reset at 12:00am GMT.

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",
        "faultOccurredTime": "2020-03-06T17:27:04.222Z",
        "occurrences": 127
      },
      "dataLinkType": "J1939",
      "hourMeter": 1583.2,
      "odometerInKilometer": 214.7,
      "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"). You can filter the data for specific date ranges within the last 24 months from the current date.

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

  • all input query parameters blank. API will return last 7 days of data from current date
  • startTime and endTime for a date range of 3 months from the current date
  • occurredTime within 3 month from the current date
  • limit with value less than 500, startTime and endTime for a date range of 3 months from the current date
  • limit with value less than 500, occurredTime within 3 month from the current date
  • limit with value less than 500, faultType, startTime and endTime for a date range of 3 months from the current date
  • limit with value less than 500, severity, startTime and endTime for a date range of 3 months from the current date
  • limit with value less than 500, deviceType, startTime and endTime for a date range of 3 months from the current date
  • limit with value less than 500, model, startTime and endTime for a date range of 3 months from the current date
  • limit with value less than 500, make, startTime and endTime for a date range of 3 months from the current date
  • limit with value less than 500, productFamily, startTime and endTime for a date range of 3 months from the current date
  • limit with value less than 500, ucid, startTime and endTime for a date range of 3 months from the current date
  • limitwith value less than 500, language,startTime and endTime for a date range of 3 months from the current date
  • all or some optional query parameters specified: make, model, productFamily, dealerCode, ucid, faultType, deviceType, severity

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

  • makeSerialNumbers (an array of values), all other input query parameters blank. API will return last 7 days of data from current date
  • makeSerialNumbers (an array of values), startTime and endTime for a date range of 1 month from the current date
  • makeSerialNumbers (an array of values), limit value with less than 50, faultType, and startTime and endTime for a date range of 1 month from the current date
  • makeSerialNumbers (an array of values), limit value with less than 50, severity, and startTime and endTime for a date range of 1 month from the current date
  • makeSerialNumbers (an array of values), limit value with less than 50, and occurredTime within 1 month from the current date
  • makeSerialNumbers (an array of values), limit value with less than 50, faultType, and occurredTime within 1 month from the current date
  • makeSerialNumbers (an array of values), limit value with less than 50, severity, and occurredTime within 1 month from the current date

language query parameter helps to get faultDescription response field values in any of the supported language format. Default value is English. List of other language support is listed in API specifications. `cursor' query parameter can be used to paginate through the different pages if account has more than one pages of data.

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 Operations 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/assetOperationHistory/v1/assetOperations endpoint.

Sample request

curl -v -X GET \
"https://services.cat.com/catDigital/assetOperationHistory/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"
          }
        ]
      },
      "assetOperationDateInfo": [
        {
          "startStateUtc": "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": "runtime"
        }
      ]
    }
  ],
  "responseMetadata": {
    "nextCursor": "eyJvZmZzZXQiOjR9"
  }
}

Depending on the combination of query parameters, the default value of the limit parameter defining the response size can be 100 ("bulk") or 50 records ("lightweight"). You can filter the data for specific date ranges within the last 24 months from the current date.

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

  • all input query parameters blank. API will return last 7 days of data from current date
  • startDate and endDate for a date range of 3 months from the current date
  • limit with value less than 100, startDate and endDate for a date range of 1 month from the current date
  • limit with value less than 100, model, startDate and endDate for a date range of 1 month from the current date
  • limit with value less than 100, make, startDate and endDate for a date range of 1 month from the current date
  • limit with value less than 100, productFamily, startDate and endDate for a date range of 1 month from the current date
  • limit with value less than 100, dealerCode, startDate and endDate for a date range of 1 month from the current date
  • limit with value less than 100, ucid, startDate and endDate for a date range of 1 month from the current date
  • all optional query parameters specified: make, model, productFamily, dealerCode, ucid

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

  • makeSerialNumbers(an array of values), and all input query parameters blank. API will return last 7 days of data from current date
  • makeSerialNumbers(an array of values), startDate and endDate for a date range of 1 months from the current date
  • makeSerialNumbers(an array of values), limit value less than 50, startDate and endDate for a date range of 1 month from the current date ?????
  • makeSerialNumbers(an array of values), limit value less than 50 , startDate and endDate for a date range of 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.

Get Asset Operation Feeds

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

Sample request

curl -v -X GET \
"https://services.cat.com/catDigital/assetOperationHistory/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"
          }
        ]
      },
      "events": [
        {
          "eventType": "EngineStart",
          "eventTime": "2023-01-31T12:39:15"
        }        
        {
          "eventType": "IdleStop",
          "eventTime": "2023-01-31T12:39:25"
        }
        {
          "eventType": "MovementStart",
          "eventTime": "2023-01-31T12:39:32"
        }
        {
          "eventType": "MovementStop",
          "eventTime": "2023-01-31T12:42:15"
        }
        {
          "eventType": "SwitchON",
          "eventTime": "2023-01-31T12:44:45"
        }
        {
          "eventType": "SwitchOFF",
          "eventTime": "2023-01-31T12:47:05"
        }
        {
          "eventType": "IdleStop",
          "eventTime": "2023-01-31T12:49:11"
        }        
        {
          "eventType": "EngineStop",
          "eventTime": "2023-01-31T12:51:42"
        }
      ]
    }
  ],
  "responseMetadata": {
    "nextCursor": "eyJvZmZzZXQiOjR9"
  }
}

Retrieves Asset Operation Feed information based on input. For 7 days and below date range returns 100 assets, a 1-month date range of 50 assets, and 3 months date range of 10 assets per page. You can filter the data for specific date ranges within the last 24 months from the current date.

The eventType field in each entry contains text that describes the type of event. One of each event type is displayed in the API response example.

Use these query parameters to return a API response:

  • all input query parameters blank. API will return last 7 days of data from current date
  • startDate and endDate for a date range of 3 months from the current date
  • startDate and endDate for a date range of 1 month from the current date
  • startDate and endDate for a date range of 7 days from the current date

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

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"). You can filter the data for specific date ranges within the last 24 months from the current date.

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

  • all input query parameters blank. API will return last 7 days of data from current date.
  • startTime and endTime for a date range of 3 months from the current date
  • limit value less than 500, startTime and endTime for a date range of 3 months from the current date
  • limit value less than 500, model, startTime and endTime for a date range of 3 months from the current date
  • limit value less than 500, make, startTime and endTime for a date range of 3 months from the current date
  • limit value less than 500, productFamily, startTime and endTime for a date range of 3 months from the current date
  • limit value less than 500, ucid, startTime and endTime for a date range of 3 months from the current date
  • limit value less than 500, dealerCode, startTime and endTime for a date range of 3 months from the current date
  • all or some of the optional query parameters specified: make, model, productFamily,dealerCode, ucid

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

  • makeSerialNumbers (an array of values), and all input query parameters blank. API will return last 7 days of data from current date.
  • makeSerialNumbers (an array of values), startTime and endTime for a date range of 1 month from the current date
  • makeSerialNumbers (an array of values), limit value less than 50, and startTime and endTime for a date range of 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.

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"
          }
        ]
      },
      "dailyUtilizations": [
        {
          "assetLocalDate": "2016-01-31",
          "hourMeter": 2,
          "idleMeter": 2,
          "lifetimeTotalFuelBurned": 2,
          "lifetimeIdleFuelBurned": 2,
          "lifetimeDef": 2,
          "runtimeHours": 10.2,
          "idleHours": 3.6,
          "workingHours": 6.6,
          "customUtilizationType": "Movement",
          "customHours": 2,
          "distanceTraveledKms": 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 100 ("bulk") or 50 records ("lightweight"). You can filter the data for specific date ranges within the last 24 months from the current date.

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

  • all input query parameters blank. API will return last 7 days of data from current date.
  • startDate and endDate for a date range of 3 months from the current date
  • limit with value less than 100, make, startDate and endDate for a date range of 3 months from the current date
  • limit with value less than 100, model, startDate and endDate for a date range of 3 months from the current date
  • limit with value less than 100, productFamily, startDate and endDate for a date range of 3 months from the current date
  • limit with value less than 100, ucid, startDate and endDate for a date range of 3 months from the current date
  • limit with value less than 100, dealerCode, startDate and endDate for a date range of 3 months from the current date
  • limit with value less than 100, subscription,startDate and endDate for a date range of 3 months from the current date
  • all or some of the optional query parameters specified: make, model, productFamily, dealerCode, subscription, ucid

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

  • makeSerialNumbers (an array of values), startDate and endDate for a date range of 1 months from the current date
  • makeSerialNumbers (an array of values), limit with value less than 50, startDate and endDate for a date range of 1 months 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 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",
        "modelYear": "2006"
      },
      "assetStatus": "Ready to Run",
      "customAssetState": "Allocated",
      "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",
      "source": "Caterpillar",
      "hourMeter": {
        "value": 2356.7,
        "lastReportedTime": "2020-03-06T17:27:04.222Z"
      },
      "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",
      "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").

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

  • all input query parameters blank.
  • all or some of the optional query parameters specified: make, model, productFamily, dealerCode, subscription, ucid, deviceType, and source
  • limit with value less than 500, make query parameter specified
  • limit with value less than 500, model query parameter specified
  • limit with value less than 500, productFamily query parameter specified
  • limit with value less than 500, dealerCode query parameter specified
  • limit with value less than 500, subscription query parameter specified
  • limit with value less than 500, ucid query parameter specified
  • limit with value less than 500, deviceType query parameter specified
  • limit with value less than 500, source query parameter specified

Use these query parameters to return a lightweight response:

  • 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.

Pagination

You can paginate the API responses as follows:

  • Use the limit query parameter to override the default page size, if necessary.
  • If the initial response size is greater than the default page size or the value of the limit parameter, the responseMetadata.nextCursor response property contains a value.
  • Use the responseMetadata.nextCursor value in the cursor query parameter to return the next page of the result set.
  • A null value of responseMetadata.nextCursor indicates that you have reached the last page of the result set.

Primary/Unique Key Recommodation

Following are the suggestions for creating primary/unique keys when importing the API data into dealer systems.

API Primary/Unique Key Suggestions
Faults History make + model + serial number + faultRecievedTime + faultOccurredTime
Utilization History make + model + serial number + assetLocalDate
Asset Summary make + model + serial number
Fence Alert History make + model + serial number + receivedTime
Asset Operations History make + model + serial number + startStateUtc + startStateAssetLocalTime
Asset Operations Feeds History make + model + serial number + eventTime

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.
2-15-2023 Added review comments based on field followup dealer comments
3-24-2023 Added list of the VL 2.0 fields which are missing from new vision link API and reason for decision to not add in new API
5-9-2023 Changed order of data tables and added new sections based on user comments
Viewing 1 - 1 of 1

Related Document

Document
Doc21062Doc21062Modified
Doc10066Doc10066Modified
Doc10064Doc10064Modified
CAT QR
/apis/products/qa/cat-qr