Basic Daily API Developer Guide (2024)

Overview

Basic Daily Application Programming Interface (API) bundle provides access to telemetry data including all subscriptions. The API bundle includes:

• Diagnostic V6 API
• Fuel V5 API
• SMULOC (Service Meter Units and Location) V6 API

Basic Daily Last Known data feed offers Caterpillar dealers basic telemetry asset tracking and service planning data. The offering includes Hours, Location, and Fuel information. Data is updated several times per day and rolled up once per day in asset’s local time zone and delivered in XML format.

Use cases include but are not limited to rental hours and location tracking, CSA oil change scheduling, PM scheduling for low severity/low time sensitive fault code actions, and general feeds for portals and applications.

This documents provides the detailed information for using the APIs.

API Limits

Calls can be made any time of the day and there are no blackout periods in this process. It is recommended that calls are limited to one per day. Caching is applied: Any additional calls within the last 22.5 hrs will return the same cached data. Additionally, API throttling might be applied from time to time. At present, a dealer can make 2000 calls per day (resets at 0:00 hrs UTC).

The XML feed will provide the last reported telemetry message data from the last 24 months for all assets that include delivery of all telemetry subscription data including Cat Daily subscription. Data is updated once per day at midnight of the assets local time zone. Calls can be made any time of the day and there are no blackout periods during the batch process.

Subscribing to the API

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

Accessing the API

Use these URLs to access the APIs:

• Diagnostics: https://services.cat.com/basicDaily/v6/Diagnostic/
• Fuel: https://services.cat.com/basicDaily/v5/Fuel/
• SMUs and Location: https://services.cat.com/basicDaily/v6/SmuLoc/

API Reference Information

Detailed reference information about the API input parameters, requested bodies, responses, and error messages can be found in thefollowing OpenAPI specifications:

• SMUs and Location:https://digital.cat.com/apis/api-list/prod/basic-daily-smuloc-v6
• Fuels:https://digital.cat.com/apis/api-list/prod/basic-daily-fuel-v5
• Diagnostics:https://digital.cat.com/apis/api-list/prod/basic-daily-diagnostic-v6

Diagnostic API

Diagnostic API V6 provides basic asset fault and electronic event information reported for the last 48 hours for all telemetry subscribed assets (all commercial subscriptions). The information includes severity level, Module Identification Code (MID), Diagnostic Code (SPN), Failure Mode Indicator (FMI), number of occurrences, reported time, Component Identification (CID), Event Identification (EID), faut type ID, and fault code description.

To get diagnostic information, use the GET /v6/Diagnostic/endpoint. Use the limit and offset query parameters for paginating the results set. For more information, see Pagination.

Request

curl -v -X GET "https://services.cat.com/basicDaily/v6/Diagnostic/?offset={integer}&limit={integer}"-H "Authorization: Bearer {access token}"

Response

<diagnostic:topic xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:diagnostic="Cat.AEMP.Services.Models"> <nextBuffer> <url>https://services.cat.com/basicDaily/v6/Diagnostic/?limit=1000&amp;offset=1000&a mp;continuationToken=1000</url> <moreData>true</moreData> </nextBuffer> <message> <header> <messageId>pl6xx_2CC5D865-77C5-42FB-A05E-E940A27528A0</messageId> <masterMsgId xsi:nil="true" /> <equipment> <serialNumber>TDT10182</serialNumber> <make>CAT</make> <model>323D</model> <nickname>TDT10182</nickname> <equipmentVin xsi:nil="true" /> </equipment> <moduleCode>2216S087YD</moduleCode> <moduleTime>2020-07-14T15:54:55</moduleTime> <receivedTime>2020-07-15T00:22:09.29</receivedTime> <owner>Equipment owner</owner> </header> <numberOfDiagnostics>1</numberOfDiagnostics> <diagnosticBlock> <diagnostic> <level>1</level> <mid>263</mid> <spn xsi:nil="true" /> <fmi>9</fmi> <occurances>1</occurances> <timestamp>2020-07-14T15:54:55</timestamp> <cid>1639</cid> <eid xsi:nil="true" /> <typeid>1</typeid> <description>Machine Security System Module:Abnormal Update Rate</description> </diagnostic> </diagnosticBlock> </message></Diagnostic>

Fuel API

Fuel API provides the last known telemetry data for lifetime/cumulative Fuel, Fuel Level, and Idle Fuel. All data elements have a unique “reported time” (date/timestamp) for all telemetry subscribed assets (all commercial subscriptions).

To get fuel information, use the GET /v5/Fuel/endpoint. Use the limit and offset query parameters for paginating the results set. For more information, see Pagination.

Request

curl -v -X GET "https://services.cat.com/basicDaily/v6/Fuel/?offset={integer}&limit={integer}"-H "Authorization: Bearer {access token}"

Response

<Fuel> <NextBuffer> <url>https://services.cat.com/basicDaily/v5/Fuel/?limit=1000&offset=0</url> <moreData>true</moreData> </NextBuffer> <Message> <Header> <messageId>pl6xx_11516030208</messageId> <masterMsgId xsi:nil="true" /> <equipment> <serialNumber>ABC12345</serialNumber> <make>CAT</make> <model>797</model> <nickname>nickname</nickname> </equipment> <moduleCode>23259011RC</moduleCode> <receivedTime>2016-11-22T11:10:11.783Z</receivedTime> <owner>Equipment Owner</owner> </Header> <consumption> <reportedTime>2016-11-22T05:00:59.000Z</reportedTime> <value>15353</value> <uom>Liters</uom> </consumption> <level> <reportedTime>2016-11-22T05:00:59.000Z</reportedTime> <value>20</value> <uom>Percentage</uom> </level> <idleFuel> <reportedTime>2016-11-22T05:00:59.000ZreportedTime> <value>20</value> <uom>Liters</uom> </idleFuel> </Message></Fuel>

SMULOC API

SMULOC API V6 provides the last known telemetry data for Service Meter Units (Hours), Idle Time, Mileage (when reported), Location for all telemetry subscribed assets (all commercial subscriptions). All data elements have a unique “reported time” (date/timestamp) to indicate the last reported time for that data element.

Note:

• For assets in China, the API returns either latitude and longitude or China coordinate ID and address format.
• For all other regions, the API returns latitude and longitude.

To get SMULOC information, use the GET /v5/SmuLoc/endpoint. Use the limit and offset query parameters for paginating the results set. For more information, see Pagintion.

Request

curl -v -X GET "https://services.cat.com/basicDaily/v6/SmuLoc/?offset={integer}&limit={integer}"-H "Authorization: Bearer {access token}"

Response

<Smuloc> <NextBuffer> <url>https://services.cat.com/basicDaily/v6/SMULoc/?limit=1000&amp;offset=0</url> <moreData>true</moreData> </NextBuffer> <Header> <messageId>pl6xx_11516030208</messageId> <masterMsgId xsi:nil="true" /> <equipment> <serialNumber>ABC12345</serialNumber> <make>CAT</make> <model>797</model> <nickname>nickname</nickname> </equipment> <moduleCode>23259011AC</moduleCode> <receivedTime>2016-11-22T05:00:59.000Z</receivedTime> <owner>Equipment Owner</owner> </Header> <serviceMeter> <reportedTime>2016-11-22T05:00:59.000Z</reportedTime> <value>19</value> <uom>Hours</uom> </serviceMeter> <idleTime> <reportedTime>2016-11-22T05:00:59.000Z</reportedTime> <value>2</value> <uom>Hours</uom> </idleTime> <mileage> <reportedTime>2016-11-22T05:00:59.000Z</reportedTime> <value>42</value> <uom>Miles</uom> </mileage> <location> <reportedTime>2016-11-22T05:00:59.000Z</reportedTime> <latitude>40.69223</latitude> <longitude>-89.58893</longitude> <validity>V</validity> </location> <chinaLocation> <reportedTime>2016-11-22T05:00:59.000Z</reportedTime> <chinaCoordinateId>40692</chinaCoordinateId> <address>JIANGSUWuxiBinhu District No.5, Xinqing Rd</address> <validity>V</validity> </chinaLocation></Smuloc>

Pagination

Every Basic daily API call returns a response with maximum of 1000 records per page.

• Use the limit to control the number of results per page.
• Use the offset parameter to specify the number of records to skip before displaying the next page.
• The nextBuffer property of the result set indicates whether additional data is available (moreData equals true) and provides the URL of the next page.

<NextBuffer> <url>https://services.cat.com/basicDaily/v6/SmuLoc/limit=1000&amp;offset=1000&amp;continuationToken=1000</url> <moreData>true</moreData></NextBuffer>

Testing Procedures

Testing can be performed without Caterpillar DICE Team assistance.

Additional Documentation

The following additional documentation is available as part of the Basic Daily API bundle:

• Access Guide: https://digital.cat.com/knowledge-hub/articles/basic-daily-api-access-guide

• Basic Daily API Specification Sheet: https://digital.cat.com/knowledge-hub/document
• Basic Daily - Postman Collection: https://digital.cat.com/knowledge-hub/document

Glossary

Change History