Frequently Asked Questions | Construction Equipment

AEMP API 2.0

Why does the machine data not change every time I call the API?

The data in the API feed after every call is the most up-to-date data available. Volvo Construction Equipment machines will report different data points after different events (described below). If you call the API prior to one of these events, the machine data will appear unchanged from the previous call.
Diagnostic trouble codes are reported in real time and trigger a reporting event. This event includes the diagnostic trouble code, machine hours, and location.
Every time the machine is keyed on, a reporting event occurs. This event includes machine hours and location.
The first key on event of each day will include the previous days operational and production data such as cumulative idle hours, cumulative load count, etc.

Why am I only seeing a limited amount of data points in the API?

Please review the following steps to understand why you may only be seeing a limited number of data points. If the issue persists, please refer to your local Volvo dealership.
1. Verify that you are subscribed to the proper AEMP 2.0 plan. To do so, refer to the FAQ titled “HOW TO CHANGE THE PLAN YOU ARE USING IN A SUBSCRIPTION: E.G. MOVE FROM THE TEST PLAN TO THE PRODUCTION PLAN OF AEMP 2.0 API”.
2. Ensure that you are subscribed to the proper CareTrack services in the CareTrack Portal. A list of necessary services can be found within the business document of the API you are subscribed to. You can view the CareTrack services you are subscribed to by logging into the CareTrack Portal, going to your machine’s summary, and review the service packages under your customer name. To make changes to your subscribed CareTrack services, contact your local dealership.
3. Confirm that the machine is properly reporting to the CareTrack Portal. To do so, log into CareTrack, go your machine’s summary, and check the following:
a. Last Update Date is accurate compared to last time machine was run
b. ECU Configuration Process at bottom of screen shows “completed”

Why does the Engine Status never change values when calling the Fleet endpoints?

The Engine Status data point found within the fleet endpoints of the API is the same value found at the machine summary in the CareTrack Portal. This datapoint has two possible values and is only reported at machine’s key on: Key on Engine on , Key on Engine off. As an example, if you key on the machine and start the engine, you will receive key on engine on status. When the machine is keyed off, you will receive no new update of engine status. If you then turn the key on and start the engine a second time, the value will appear as engine on again. Thus, you would never receive an engine off status.
If you wish to view the timeseries of engine status including engine on and engine off, you should rather call the Engine Condition call. This call is made per machine and provides a time series of all engine conditions. More information on this call can be found within the API documentation.

What Diagnostic Trouble Codes (DTCs) will be communicated in my API feed?

Diagnostic Trouble Codes (DTCs) are only communicated by CEA2+ machines. The CEA2+ machines will only communicate what is considered a priority 1 (highest urgency) code. To confirm if your machine is CEA2+ or to validate if a specific DTC is available in the API, please contact your local dealership.

Using our APIs

I just want to use an API? What are plans?

A plan is collection of API resources or subsets of resources from one or more APIs. A plan can contain a mixture of operation types from different APIs. A plan can have a common rate limit for all the resources or each resource can have a different rate limit. Rate limits specify how many requests an application is allowed to make during a specified time interval.

Use this Developer Portal to browse the different plans that are available to you and select a plan that is most suitable for your requirements. Some plans have restricted access that you must request access to use. When you submit your request, the organization is notified, the API administrator assesses your request and they might contact you for more details. Other plans are available to use straight away.

How do I see my API usage?

The numbers of requests, for different APIs, that your application has made are shown on your application page.

Click 'Apps' in the main menu and then click on your application. In the 'Product Subscriptions' table you will see all plans your application is subscribed to.

For each API contained in that plan you can see the usage compared to the rate limit of the plan.

How can I test an API?

It is possible to test an API from this Developer Portal.

When looking at the details of an API you will see a list of the operations contained in the API. This will show the verb and path to use for the operation.

If you click on the operation you will see more information about it, what parameters it might take, what it returns, what possible return codes it might use and what they mean.

There is also a 'Try' button on REST APIs which enables you to try the operation out direct from the Developer Portal.

If the API requires a client ID or a client secret for identification then you can specify these using your application credentials at the top of the 'Try' section.

Apps

How do I register an application?

When you add an application you are provided with an API Key and Secret for the application. You must supply these credentials when you call an API that requires you to authenticate your application.

To register an application click on Apps in the main menu and then click on the 'Create new app' link. Once you have provided an application name, description, etc you will be shown your application API Key and Secret.

Make a note of your API Secret because it is only displayed once.

How do I reset my application API Secret?

Your API Secret is stored encrypted so we cannot retrieve the unencrypted version to tell you the value if you forget it.

You can reset it, which will update the stored value and return the new value to you.

To do that click 'Apps' in the main menu, click on the application in question and then you can click the 'Reset' link in the 'API Secret' section.

Your new Secret will be displayed at the top of the page.