VisionLink APIs Developer Guide | CAT Digital Marketplace (2024)

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

Migration from Legacy and Unified Vision Link APIs to New VisionLink APIs

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

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

Asset Fence History API

Faults History API

Asset Operations History API

* 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

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.

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": "2020-03-06T17:27:04.222Z"", "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", "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, "odometer": 1.5, "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", "dcnName":"Demo Customer" } ], "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 Recommendations

The following are recommendations for creating primary/unique keys when importing the API data into dealer systems.

Additional Documentation

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

• Access Guide: https://digital.cat.com/knowledge-hub/document/new-visionlink-api-access-guide
• VisionLink API Postman Collection: https://digital.cat.com/knowledge-hub/document/visionlink-apis-postman-collection
• VisionLink API Specifications: https://digital.cat.com/knowledge-hub/document/new-visionlink-specifications-document

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