Back to top
Overview
ISO 15143-3 API provides general information for tracking assets, understanding their usage, and planning how to manage those assets. The API is based on ISO-15143 (AEMP 2.0) specification to allow customers to easily connect to Caterpillar data without having to perform custom coding for their end system. This API is mainly consumed by dealers and customers. Typical use cases for these APIs are bulk data consumption (Timeseries) and real time data (snapshot).
Current Functionality
The API includes following endpoints.
ISO 15143-3 (AEMP 2.0) API endpoints:
- Fleet Snapshot
- Equipment Snapshot
- Timeseries-Fault Code
NextGen ISO 15143-3 (AEMP 2.0) API endpoints:
- Timeseries-Location
- Timeseries-Switch Status
- Timeseries-Cumulative Operating Hours
- Timeseries-Cumulative Idle Operating Hours
- Timeseries-Cumulative Fuel Used
- Timeseries-Engine Condition
- Timeseries-Fuel Remaining Ratio
AEMP 2.0 Subset Element Groups:
- Asset (make, model, serial number)
- Location (Latitude/Longitude)
- Address (ChinaCoordinateId/Address)
- Cumulative Operating hours, Idle hours
- Cumulative Fuel Used
- Cumulative Fuel Used last 24 hours
- Odometer & Engine status
- Fuel/DEF Remaining Ratio
- Cumulative Load count, Payload totals
- Snapshot Time (UTC)
- Fault Code Identifier, Description, Severity
- Air Temperature
- Temperature Unit
- Fault Code Source, Reported date and time
Back to top
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.
Back to top
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.
Back to top
API Environments
The API is only available in production environment.
Use this URL to access the APIs: https://services.cat.com/telematics/iso15143/
Back to top
Detailed reference information about the API input parameters, requested bodies, responses, and error messages can be found in the following OpenAPI specifications:
Back to top
Workflow Overview
The API provides the following endpoints for Caterpillar-to-dealer data transfer:
GET /{pageNumber}
- This endpoint provides a snapshot view of the fleet.
GET /equipment/makeModelSerial/{make}/{model}/{serialNumber}
- This endpoint provides the same data as the fleet snapshot endpoint but is limited to a single piece of equipment. A snapshot is a single point in time. Time-series data, such as fault codes and switch status, are not included in the snapshot view.
GET /equipment/makeModelSerial/{make}/{model}/{serialNumber}/faults/{startDateUTC}/{endDateUTC}/{pageNumber}
- This endpoint returns individual asset fault code timeseries data for a rolling 14-day period. The data includes all fault codes (with as fault code ID, description, severity) recorded within the specified time range for the specified asset, along with the timestamp (UTC) when it was created. The input timestamps (start and end) should be within 14-day time range. Data availability depends on machine support and commercial subscription. Diagnostic codes from the OEM can be used to alert the asset owner to the need for machine maintemamce service.
GET /equipment/makeModelSerial/{make}/{model}/{serialNumber}/locations/{startDateUTC}/{endDateUTC}/{pageNumber}
- This endpoint returns the location details in addition to the recorded time(UTC) of a given asset and the time range. The data can be requested for up to 14 days in the past. Data availability is dependent on machine support and commercial subscription.
GET /equipment/makeModelSerial/{make}/{model}/{serialNumber}/switchStatus/{startDateUTC}/{endDateUTC}/{pageNumber}
- This endpoint returns the switch status details in addition to the recorded time(UTC) of a given asset and the time range. The data can be requested for up to 14 days in the past. Data availability is dependent on machine support and commercial subscription.
GET /equipment/makeModelSerial/{make}/{model}/{serialNumber}/cumulativeOperatingHours/{startDateUTC}/{endDateUTC}/{pageNumber}
- This endpoint returns the cumulative operating hours details in addition to the recorded time(UTC) of a given asset and the time range. The data can be requested for up to 14 days in the past. Data availability is dependent on machine support and commercial subscription.
GET /equipment/makeModelSerial/{make}/{model}/{serialNumber}/cumulativeIdleHours/{startDateUTC}/{endDateUTC}/{pageNumber}
- This endpoint returns the cumulative idle hours details in addition to the recorded time(UTC) of a given asset and the time range. The data can be requested for up to 14 days in the past. Data availability is dependent on machine support and commercial subscription.
GET /equipment/makeModelSerial/{make}/{model}/{serialNumber}/cumulativeFuelUsed/{startDateUTC}/{endDateUTC}/{pageNumber}
- This endpoint returns the fuel used details in addition to the recorded time(UTC) of a given asset and the time range. The data can be requested for up to 14 days in the past. Data availability is dependent on machine support and commercial subscription.
GET /equipment/makeModelSerial/{make}/{model}/{serialNumber}/engineCondition/{startDateUTC}/{endDateUTC}/{pageNumber}
- This endpoint returns the engine condition details in addition to the recorded time(UTC) of a given asset and the time range. The data can be requested for up to 14 days in the past. Data availability is dependent on machine support and commercial subscription.
GET /equipment/makeModelSerial/{make}/{model}/{serialNumber}/fuelRemainingRatio/{startDateUTC}/{endDateUTC}/{pageNumber}
- This endpoint returns the fuel remaining ratio details in addition to the recorded time(UTC) of a given asset and the time range. The data can be requested for up to 14 days in the past. Data availability is dependent on machine support and commercial subscription.
Back to top
Fleet Snapshot
To get a snapshot of the fleet data, use the GET /{pageNumber}
endpoint.
- The
pageNumber
path parameter is required. First request must use 1
as page number. If there is more than one page of results, the next page number can be found in the Links
-element of the response. For more information, see Pagination.
- Use
Accept
header to specify the response format. Specify application/iso15143-snapshot+xml
for XML. Specify application/iso15143-snapshot+json
for JSON.
Sample request
curl -v -X GET \
"https://services.cat.com/telematics/iso15143/fleet/{{pageNumber}}"-H "Authorization: Bearer {token}" \
-H 'Accept: application/iso15143-snapshot+json' \
JSON is the default response format.
Sample JSON response
{
"Links": [
{
"Rel": "Current",
"Href": "https://api.cat.com/telematics/iso15143/fleet/1"
},
{
"Rel": "Next",
"Href": "https://api.cat.com/telematics/iso15143/fleet/2"
},
{
"Rel": "Last",
"Href": "https://api.cat.com/telematics/iso15143/fleet/2"
},
{
"Rel": "First",
"Href": "https://api.cat.com/telematics/iso15143/fleet/1"
}
],
"Equipment": [
{
"EquipmentHeader": {
"OEMName": "CAT",
"Model": "EEEE",
"EquipmentID": "EDED",
"SerialNumber": "SDSS"
},
"Location": {
"Latitude": 414.163130,
"Longitude": 41.148280,
"Altitude": 3019.000000,
"AltitudeUnits": "metre",
"Datetime": "2022-06-10T04:14:45Z"
},
"CumulativeIdleHours": {
"Hour": 1189.4,
"Datetime": "2022-06-10T04:14:45Z"
},
"CumulativeOperatingHours": {
"Hour": 7855.3,
"Datetime": "2022-06-10T04:14:45Z"
},
"CumulativePayloadTotals": {
"PayloadUnits": "kilogram",
"Payload": 1418969664000.0,
"Datetime": "2020-08-21T05:09:38Z"
},
"Distance": {
"OdometerUnits": "kilometre",
"Odometer": 7541.6,
"Datetime": "2022-06-10T04:14:45Z"
},
"EngineStatus": {
"EngineNumber": "FGFD",
"Running": true,
"Datetime": "2022-06-10T04:22:19Z"
},
"FuelUsed": {
"FuelUnits": "litre",
"FuelConsumed": 84434,
"Datetime": "2022-06-10T04:14:45Z"
},
"FuelUsedLast24": {
"FuelUnits": "litre",
"FuelConsumed": 130,
"Datetime": "2022-06-09T00:00:00Z"
},
"FuelRemaining": {
"Percent": 96.0,
"Datetime": "2022-06-10T04:14:45Z"
}
}
]
}
Back to top
Equipment Snapshot
To get a snapshot of data for a single piece of equipment, use the GET /equipment/makeModelSerial/{make}/{model}/{serialNumber}
endpoint.
- Use
make
, model
, and serialNumber
path parameters to identify the equipment.
- Use
Accept
header to specify the response format. Specify application/iso15143-snapshot+xml
for XML. Specify application/iso15143-snapshot+json
for JSON.
Sample request
curl -v -X GET \
"https://services.cat.com/telematics/iso15143/equipment/makeModelSerial/{make}/{model}/{serialNumber}"-H "Authorization: Bearer {token}" \
-H 'Accept: application/iso15143-snapshot+json' \
JSON is the default response format.
Sample JSON response
{
"EquipmentHeader": {
"OEMName": "CAT",
"Model": "924K",
"EquipmentID": "HU-HH-ZH",
"SerialNumber": "MEJ00000"
},
"Location": {
"latitude": "40.69223",
"longitude": "-89.58893",
"altitude": "42.007",
"AltitudeUnits": "meter",
"ChinaCoordinateId": "499478202"
},
"CumulativeOperatingHours": {
"Hour": "441.7",
"Datetime": "2015-07-11T03:49:16Z"
},
"FuelUsed": {
"FuelConsumed": "18.9271",
"FuelUnits": "liter",
"Datetime": "2015-07-11T03:49:16Z"
},
"Distance": {
"Odometer": "746.9",
"OdometerUnits": "kilometer",
"Datetime": "2015-07-11T03:49:16Z"
},
"CumulativeIdleHours": {
"Hour": "441.7",
"Datetime": "2015-07-11T03:49:16Z"
},
"FuelRemaining": {
"Percent": "72.1",
"Datetime": "2015-07-11T03:49:16Z"
},
"DEFRemaining": {
"Percent": "74",
"Datetime": "2015-07-11T03:49:16Z"
},
"EngineStatus": {
"Running": "True",
"Datetime": "2015-07-11T03:49:16Z"
}
}
Back to top
Timesseries-Fault Code
To get diagnostic codes timeseries for a single piece of equipment, use the GET /equipment/makeModelSerial/{make}/{model}/{serialNumber}/faults/{startDateUTC}/{endDateUTC}/{pageNumber}
endpoint.
- Use
make
, model
, and serialNumber
path parameters to identify the equipment.
- Use the
startDateUTC
and endDateUTC
path parameters to specify the date range.
- The
pageNumber
path parameter is required. First request must use 1
as page number. If there is more than one page of results, the next page number can be found in the Links
-element of the response. For more information, see Pagination.
- Use
Accept
header to specify the response format. Specify application/iso15143-snapshot+xml
for XML. Specify application/iso15143-snapshot+json
for JSON.
Sample request
curl -v -X GET \
"https://services.cat.com/telematics/iso15143/equipment/makeModelSerial/{make}/{model}/{serialNumber}/faults/{startDateUTC}/{endDateUTC}/{pageNumber}" \
-H "Authorization: Bearer {token}" \
--header 'Accept: application/iso15143-snapshot+json' \
JSON is the default response format.
Sample JSON response
{
"Links": [
{
"Rel": "Current",
"Href": "https://api.cat.com/telematics/iso15143/fleet/equipment/makeModelSerial…"
},
{
"Rel": "Last",
"Href": "https://api.cat.com/telematics/iso15143/fleet/equipment/makeModelSerial…"
},
{
"Rel": "First",
"Href": "https://api.cat.com/telematics/iso15143/fleet/equipment/makeModelSerial…"
}
],
"FaultCode": [
{
"CodeIdentifier": "490-3",
"CodeDescription": "Implement Lockout Switch:Voltage Above Normal",
"CodeSeverity": "Medium",
"CodeSource": "Impl Ctrl Valve Module",
"Datetime": "2022-06-04T20:48:27Z"
},
{
"CodeIdentifier": "490-3",
"CodeDescription": "Implement Lockout Switch:Voltage Above Normal",
"CodeSeverity": "Medium",
"CodeSource": "Impl Ctrl Valve Module",
"Datetime": "2022-06-04T19:30:05Z"
}
]
}
Back to top
Timesseries-Location
To get Last Known Location timeseries data for a single piece of equipment, use the GET /fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/locations/{startDateUTC}/{endDateUTC}/{pageNumber}
endpoint.
- Use
make
, model
, and serialNumber
path parameters to identify the equipment.
- Use the
startDateUTC
and endDateUTC
path parameters to specify the date range.
- The
pageNumber
path parameter is required. First request must use 1
as page number. If there is more than one page of results, the next page number can be found in the Links
-element of the response. For more information, see Pagination.
- Use
Accept
header to specify the response format. Specify application/iso15143-snapshot+xml
for XML. Specify application/iso15143-snapshot+json
for JSON.
Sample request
curl -v -X GET \
"https://api.cat.com/catDigital/iso15143/v1/fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/locations/{startDateUTC}/{endDateUTC}/{pageNumber}" \
-H "Authorization: Bearer {token}" \
--header 'Accept: application/iso15143-snapshot+json' \
JSON is the default response format.
Sample JSON response
{
"Links": [
{
"href": "https://api.cat.com/catDigital/iso15143/v1",
"rel": "Current"
}
],
"Location": [
{
"Latitude": 40.69223,
"Longitude": -89.58893,
"Altitude": 42.007,
"AltitudeUnits": "metre",
"ChinaCoordinateId": 499478202,
"datetime": "2015-07-11T03:49:16Z"
}
]
}
Back to top
Timesseries-Switch Status
To get Switch Status timeseries data for a single piece of equipment, use the GET /fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/switchStatus/{startDateUTC}/{endDateUTC}/{pageNumber}
endpoint.
- Use
make
, model
, and serialNumber
path parameters to identify the equipment.
- Use the
startDateUTC
and endDateUTC
path parameters to specify the date range.
- The
pageNumber
path parameter is required. First request must use 1
as page number. If there is more than one page of results, the next page number can be found in the Links
-element of the response. For more information, see Pagination.
- Use
Accept
header to specify the response format. Specify application/iso15143-snapshot+xml
for XML. Specify application/iso15143-snapshot+json
for JSON.
Sample request
curl -v -X GET \
"https://api.cat.com/catDigital/iso15143/v1/fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/switchStatus/{startDateUTC}/{endDateUTC}/{pageNumber}" \
-H "Authorization: Bearer {token}" \
--header 'Accept: application/iso15143-snapshot+json' \
JSON is the default response format.
Sample JSON response
{
"Links": [
{
"href": "https://api.cat.com/catDigital/iso15143/v1",
"rel": "Current"
}
],
"SwitchStatus": [
{
"SwitchNumber": 7,
"IsOn": true,
"datetime": "2015-07-11T03:49:16Z"
}
]
}
Back to top
Timesseries-Cumulative Operating Hours
To get Cumulative Operating Hours timeseries data for a single piece of equipment, use the GET /fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/cumulativeOperatingHours/{startDateUTC}/{endDateUTC}/{pageNumber}
endpoint.
- Use
make
, model
, and serialNumber
path parameters to identify the equipment.
- Use the
startDateUTC
and endDateUTC
path parameters to specify the date range.
- The
pageNumber
path parameter is required. First request must use 1
as page number. If there is more than one page of results, the next page number can be found in the Links
-element of the response. For more information, see Pagination.
- Use
Accept
header to specify the response format. Specify application/iso15143-snapshot+xml
for XML. Specify application/iso15143-snapshot+json
for JSON.
Sample request
curl -v -X GET \
"https://api.cat.com/catDigital/iso15143/v1/fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/cumulativeOperatingHours/{startDateUTC}/{endDateUTC}/{pageNumber}" \
-H "Authorization: Bearer {token}" \
--header 'Accept: application/iso15143-snapshot+json' \
JSON is the default response format.
Sample JSON response
{
"Links": [
{
"href": "https://api.cat.com/catDigital/iso15143/v1",
"rel": "Current"
}
],
"CumulativeOperatingHours": [
{
"Hour": 441.7,
"datetime": "2015-07-11T03:49:16Z"
}
]
}
Back to top
Timesseries-Cumulative Idle Operating Hours
To get Cumulative Idle Operating Hours timeseries data for a single piece of equipment, use the GET /fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/cumulativeIdleHours/{startDateUTC}/{endDateUTC}/{pageNumber}
endpoint.
- Use
make
, model
, and serialNumber
path parameters to identify the equipment.
- Use the
startDateUTC
and endDateUTC
path parameters to specify the date range.
- The
pageNumber
path parameter is required. First request must use 1
as page number. If there is more than one page of results, the next page number can be found in the Links
-element of the response. For more information, see Pagination.
- Use
Accept
header to specify the response format. Specify application/iso15143-snapshot+xml
for XML. Specify application/iso15143-snapshot+json
for JSON.
Sample request
curl -v -X GET \
"https://api.cat.com/catDigital/iso15143/v1/fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/cumulativeOperatingHours/{startDateUTC}/{endDateUTC}/{pageNumber}" \
-H "Authorization: Bearer {token}" \
--header 'Accept: application/iso15143-snapshot+json' \
JSON is the default response format.
Sample JSON response
{
"Links": [
{
"href": "https://api.cat.com/catDigital/iso15143/v1",
"rel": "Current"
}
],
"CumulativeIdleHours": [
{
"Hour": 441.7,
"datetime": "2015-07-11T03:49:16Z"
}
]
}
Back to top
Timesseries-Cumulative Fuel Used
To get Cumulative Fuel Used timeseries data for a single piece of equipment, use the GET /fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/cumulativeFuelUsed/{startDateUTC}/{endDateUTC}/{pageNumber}
endpoint.
- Use
make
, model
, and serialNumber
path parameters to identify the equipment.
- Use the
startDateUTC
and endDateUTC
path parameters to specify the date range.
- The
pageNumber
path parameter is required. First request must use 1
as page number. If there is more than one page of results, the next page number can be found in the Links
-element of the response. For more information, see Pagination.
- Use
Accept
header to specify the response format. Specify application/iso15143-snapshot+xml
for XML. Specify application/iso15143-snapshot+json
for JSON.
Sample request
curl -v -X GET \
"https://api.cat.com/catDigital/iso15143/v1/fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/cumulativeFuelUsed/{startDateUTC}/{endDateUTC}/{pageNumber}" \
-H "Authorization: Bearer {token}" \
--header 'Accept: application/iso15143-snapshot+json' \
JSON is the default response format.
Sample JSON response
{
"Links": [
{
"href": "https://api.cat.com/catDigital/iso15143/v1",
"rel": "Current"
}
],
"FuelUsed": [
{
"FuelConsumed": 600,
"datetime": "2015-07-11T03:49:16Z",
"FuelUnits": "litre"
}
]
}
Back to top
Timesseries-Engine Condition
To get Engine Condition timeseries data for a single piece of equipment, use the GET /fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/engineCondition/{startDateUTC}/{endDateUTC}/{pageNumber}
endpoint.
- Use
make
, model
, and serialNumber
path parameters to identify the equipment.
- Use the
startDateUTC
and endDateUTC
path parameters to specify the date range.
- The
pageNumber
path parameter is required. First request must use 1
as page number. If there is more than one page of results, the next page number can be found in the Links
-element of the response. For more information, see Pagination.
- Use
Accept
header to specify the response format. Specify application/iso15143-snapshot+xml
for XML. Specify application/iso15143-snapshot+json
for JSON.
Sample request
curl -v -X GET \
"https://api.cat.com/catDigital/iso15143/v1/fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/engineCondition/{startDateUTC}/{endDateUTC}/{pageNumber}" \
-H "Authorization: Bearer {token}" \
--header 'Accept: application/iso15143-snapshot+json' \
JSON is the default response format.
Sample JSON response
{
"Links": [
{
"href": "https://api.cat.com/catDigital/iso15143/v1",
"rel": "Current"
}
],
"EngineStatus": [
{
"datetime": "2015-07-11T03:49:16Z",
"EngineNumber": "ENG00001",
"Running": true
}
]
}
Back to top
Timesseries-Fuel Remaining Ratio
To get Fuel Remaining Ratio timeseries data for a single piece of equipment, use the GET /fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/fuelRemainingRatio/{startDateUTC}/{endDateUTC}/{pageNumber}
endpoint.
- Use
make
, model
, and serialNumber
path parameters to identify the equipment.
- Use the
startDateUTC
and endDateUTC
path parameters to specify the date range.
- The
pageNumber
path parameter is required. First request must use 1
as page number. If there is more than one page of results, the next page number can be found in the Links
-element of the response. For more information, see Pagination.
- Use
Accept
header to specify the response format. Specify application/iso15143-snapshot+xml
for XML. Specify application/iso15143-snapshot+json
for JSON.
Sample request
curl -v -X GET \
"https://api.cat.com/catDigital/iso15143/v1/fleet/equipment/makeModelSerial/{make}/{model}/{serialNumber}/fuelRemainingRatio/{startDateUTC}/{endDateUTC}/{pageNumber}" \
-H "Authorization: Bearer {token}" \
--header 'Accept: application/iso15143-snapshot+json' \
JSON is the default response format.
Sample JSON response
{
"Links": [
{
"href": "https://api.cat.com/catDigital/iso15143/v1",
"rel": "Current"
}
],
"FuelRemaining": [
{
"Percent": 72.1,
"datetime": "2015-07-11T03:49:16Z",
"FuelTankCapacityUnits": "litre",
"FuelTankCapacity": 500
}
]
}
Back to top
- You can paginate the results for fleet snapshot and fault code timeseries using the required path
pageNumber
path parameter. First request must use 1
as page number.
- If there is more than one page of results, the next page number can be found in the
Links
-element of the response.
- The
Href
property specifies the URL of the link.
- The
Rel
property specifies whether the link is the current, next, first, or last page of the result set.
"Links": [
{
"Rel": "Current",
"Href": "https://api.cat.com/telematics/iso15143/fleet/1"
},
{
"Rel": "Next",
"Href": "https://api.cat.com/telematics/iso15143/fleet/2"
},
{
"Rel": "Last",
"Href": "https://api.cat.com/telematics/iso15143/fleet/2"
},
{
"Rel": "First",
"Href": "https://api.cat.com/telematics/iso15143/fleet/1"
}
]
Back to top
Additional Documentation
The following additional documentation is available as part of the ISO 15143-3 (AEMP 2.0) API bundle:
Back to top
Glossary
CWS
Corporate Web Security. CWS ID and CWS Password are created when an account within Caterpillar is created. This can be used to login to various systems and applications within Caterpillar.
AEMP
Association of Equipment Management Professionals.
Back to top
Change History
Date |
Author |
Description of Change |
---|
05-25-2021 |
Mohamed Shajahan |
New document. |
01-10-2022 |
Pravin Singh |
NextGen ISO API document. |
02-27-2022 |
Pravin Singh |
Updated information in next gen api sections. |
03-08-2023 |
Sandeep Kasurde |
Updated format and review comments. |
03-14-2023 |
Sandeep Kasurde |
Updated postman collection link. |
Back to top