In this article

Back

ISO 15143-3 (AEMP 2.0) API Developer Guide

  • APIs
  • ISO 15143-3 (AEMP 2.0) API
Mohamed Shajahan Raja Mohamed 06/09/2022 - 10:55 PM
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.

Current Functionality

ISO 15143-3 API consist of following three endpoints and provides subset element groups.

Endpoints:

  • Fleet Snapshot
  • Equipment Snapshot
  • Timeseries-Fault

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

API Reference Information

Detailed reference information about the API input parameters, requested bodies, responses, and error messages can be found in the following OpenAPI specifications: https://digital.cat.com/apis/api-list/prod/iso15143-aemp-20

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

Request

curl -v -X GET \
"https://services.cat.com/telematics/iso15143/fleet/{{pageNumber}}"-H "Authorization: Bearer {token}" \
-H 'Accept: application/iso15143-snapshot+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.

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' \

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

Equipment Diagnostic Codes Timeseries

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.

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' \

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

Pagination

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

Document Name Description Path
ISO 15143-3 (AEMP 2.0) API - Access Guide Provides step by step information to access the API using Postman tool https://digital.cat.com/knowledge-hub/articles/iso-15143-3-aemp-20-api-…
ISO 15143-3 (AEMP 2.0) API Specification Sheet Provides all the high-level technical information related to the API https://digital.cat.com/knowledge-hub/document
Back to top

Glossary

Term Definition
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.
Back to top

Related Articles

Overview

ISO 15143-3 API provides general information for tracking assets, understanding their usage, and planning how to manage those assets.

This Article helps API consumer with testing their credentials for CAT ISO 15143-3 (AEMP 2.0) API and understand ways of accessing the API.

GAIN FULL VISIBILITY INTO YOUR OPERATIONS 

/apis/products/prod/iso-15143-3-aemp-20-api