MANITOU API

Connected Solutions - Using the service

Aug 18th 2021 - version 2.5

Page 1 / 34
Description : this document provides information on how to obtain the best results of
the MANITOU API service for Connected Solutions range of API products. This
documentation is for customer IT teams to understand the service’s design and know
how to use its features, upon agreement signature and terms & conditions
acceptance.

NOTE : changes from the previously published version of this document are marked with the
“new” symbol in the margin.

Preamble 4

Understanding the Connected Solution service’s design 5

Overview 5
Security through API manager 5
Static information with connected-machine API 5
Dynamic machine state information with machine-state API 6
Dynamic sensor information with sensor-state API 6
Analytic information with machine-analytic API 6
Upload maintenance data with machine-operation API 7

Best practices reminder 8

In details : the connected-machine API 9

Endpoint URLs 9
Data set examples 9
API parameters 10

In details : the machine-state API 14

Endpoint URL 14
Data set example 14
API parameters 15

In details : the sensor-state API 18

Endpoint URL 18
Data set example 18
API parameters 19

In details : the machine-analytic API 21

Endpoint URL 21
Data set example 21
API parameters 22

In details : the maintenance-operation API 24

Endpoint URLs 24

Page 2 / 34
 Data set example 24
API parameters 25
Return values 26

Appendix : list of sensor id’s and description 30

Page 3 / 34
Preamble
MANITOU API is a data service in the form of APIs (Application Programming
Interface) that provides the Customer access to protected resources, in coherence
with the Customer’s service level of subscription.

These APIs provide a wide range of features that help improve efficiency and
productivity. All the features rely on the principles of RESTful APIs, which consider
every accessible item as a resource with its unique id that can be used and reused,
using a set of methods.

Each API serves a specific set of information, but shares common features of results
paging, attribute filtering, records sorting. All these features are described with
examples in this document, which is focused on one range of API products named
“Connected Solutions”.

Using this documentation comes as a second step after creating an account on

the MANITOU API Developer Portal.
The user should already have received approval for a subscription to one of the
“Connected Solutions” products, obtained keys and a secret user token, and
understood the technicalities of the MANITOU API service, as described in the
“MANITOU API - How to get onboard” companion document.

Page 4 / 34
Understanding the Connected Solution service’s design

Overview

The following schema describes the global design of MANITOU API’s Connected
Solutions service :

Security through API manager

It is necessary for the API user to be authenticated when performing a call to
data APIs.
Please refer to the “MANITOU API - How to get onboard” documentation
for more information on this process and a detailed technical
explanation.

Page 5 / 34
Static information with connected-machine API
This API holds the list of all the machines that are part of the customer
fleet.
Among many static information (serial number, brand, model, etc), this API
provides the customer with machine id’s, each of which is unique to one
machine and permanently affected to it.
The machine id information is the key that lets the customer retrieve dynamic
information about the machines through the other data APIs.
This API also provides the user with the reference needed to retrieve
information on the tracker the machine is equipped with, when necessary for
the customer.

This API only needs to be called once in a while by the customer, each time a
machine moves in or out of the fleet, to keep the machine id’s catalog up to
date.

Using the tracker reference provided by connected-machine, this API lets the
user retrieve information about the telematics device used to retrieve
machine data.

This API only needs to be called once in a while by the customer, each time a
machine moves in or out of the fleet, to keep the customer’s tracker
references catalog up to date.

Dynamic machine state information with machine-state API

Using the machine id provided by connected-machine, this API lets the user
know where the machine is, how much time is on the hourmeter, etc.

This API is designed to be called several times a day, for the user to keep
track of the machine’s movement and overall state.

Dynamic sensor information with sensor-state API

Using the machine id provided by connected-machine, this API lets the user
know the latest information of each exposed sensor of a given machine
(CAN-based information).

This API is designed to be called several times a day, for the user to keep
track of the sensors’ evolution.

Page 6 / 34
Analytic information with machine-analytic API
Using the machine id provided by connected-machine, this API lets the user
access several analytic indicators.
These indicators are calculated daily, on the basis of the machine sensors
evolution, among other composite indicators that provide analytic insight on
the machine’s usage and performance.

This API is designed to be called once a day, for the user to keep track of the
indicators progress over time.

Upload maintenance data with machine-operation API

Using the machine id provided by connected-machine, this API lets the user
upload details about the maintenance operations performed on the
machine to MANITOU.
This is helpful for MANITOU to keep track of the machine’s life, installed
replacement parts, respect of manufacturer recommendations, etc.

This API is designed to be called every time maintenance operations are

performed on the machine.

Page 7 / 34
Best practices reminder
When pairing your IT system with the Connected Solutions products, remember to
keep an eye on these 5 best practices, detailed in “MANITOU API - How to get
onboard” :

Keep the page size low

Pinpoint what you want

Design a realistic data request strategy

Avoid hammering

Pick only what matters

Page 8 / 34
In details : the connected-machine API

Endpoint URLs
The API can be reached at :
https://api.manitou-group.com/connected-machine/connected-machine
https://api.manitou-group.com/connected-machine/machine-tracker

Data set examples

The following chart lists the fields exposed by the API for connected-machine
resources :
JSON data Comments

{
"data" : [ Record list start indicator
{ Record start indicator
"attributes" : {
"brand" : “Manitou”, Machine brand
"model" : “MRT 123”, Machine model
"description" : "MRT 123 Forklift", Machine description
"serial-number" : "MAN00000Z000000123", Machine serial number
"height" : “312”, Machine overall height in cm
"width" : “288”, Machine overall width in cm
"length" : “513”, Machine overall length in cm
"weight" : “2140”, Machine gross weight in kg
"build-year" : “2019”, Machine build year
"build-date": "2019-06-14T00:00:00", Machine build date
"start-up-date": "2019-07-12T00:00:00", Formal start up date of the equipment
(beginning of warranty)
"contractual-warranty-end-date": End date of “basic” contract warranty
for the equipment
"2020-07-12T00:00:00", End date of extended warranty for the
"extended-warranty-end-date": equipment

2022-07-12T00:00:00"
},
"relationships" : {
"machine-tracker" : {
"links" : { Machine-dependent objects list
"self" :
"/connected-machine/abcd1234-ab12-34cd-ab12-abcdef123456/
relationships/machine-tracker", Machine-dependent tracker info start
"related" :
"/connected-machine/abcd1234-ab12-34cd-ab12-abcdef123456/
machine-tracker"
}
} Resource type
}, Resource id (connected-machine id)
"type" : "connected-machine",
"id" : "abcd1234-ab12-34cd-ab12-abcdef123456"
},

The following chart lists the fields exposed by the API for machine-tracker resources :
JSON data Comments

Page 9 / 34
{
"meta": {
"total-records": 1 Record count indicator
},
"links": { Self link
"self":
"/machine-tracker?filter[id]=3266136d-5ce1-4756-a9be-8975
395c133f"
},
"data": [ Data set beginning
{
"type": "machine-tracker", Record type
"id": "3266136d-5ce1-4756-a9be-8975395c133f", Record id
"attributes": { Record attributes
"tracker-serial-number": "751321", Tracker serial number
"tracker-phone-number": null, Tracker phone number
"tracker-imei": null Tracker GSM equipment IMEI
},
"relationships": { Resource relationships beginning
"tracker-model": {
"links": {
"self":
"/machine-tracker/3266136d-5ce1-4756-a9be-8975395c133f/re
lationships/tracker-model",
"related":
"/machine-tracker/3266136d-5ce1-4756-a9be-8975395c133f/tr
acker-model"
}
}
},
"links": {
"self":
"/machine-tracker/3266136d-5ce1-4756-a9be-8975395c133f"
}
}
]
}

API parameters
This API allows the use of the following parameters :
Parameter name Type Manda Usage
-
tory

Applicable for all resources

Ocp-Apim-Subscrip Header yes Customer subscription key (primary or secondary)

tion-Key

X-token Header yes Customer secret user token. Provide the API with
the secret user token that lets the customer retrieve
its resources.

api-version Header yes Version number of the API (v1, v2, etc.)

Page 10 / 34
page[size] Query no The API may return many resources records when
page[number]
called. The page[size] allows the user to define the
number of records wanted per page, and the
page[number] allows the user to jump to the
desired result page.
Examples :
● page[size]=30 ⇒ the API will return a
maximum of 30 records per response
● page[number]=3 ⇒ the API will return page
number 3 of all available results page.

sort Query no The API will order the result records list according
to ascending or descending value of the given
attribute name. Using a dash (“-”) before the
attribute name indicates the API to perform the sort
in a descending way. Elseway the sort is
ascending.
Examples :
● sort=height ⇒ the API will return every
recorded machine for the user, ordered from
lowest height attribute value to highest
● sort=-weight ⇒ the API will return every
recorded machine for the user, ordered from
highest weight attribute value to lowest

include Query no The API will include in the result records the data
related to the specified relationship
Example :
● include=machine-tracker ⇒ the API will
return data about the machine-tracker
relationship, including the machine-tracker’s
id
Result :
[...]
"relationships": {
"machine-tracker": {
"links": {
"self":
"/connected-machine/abcd1234-ab12-34cd-ab12-ab
cdef123456/relationships/machine-tracker",
"related":
"/connected-machine/abcd1234-ab12-34cd-ab12-ab
cdef123456/machine-tracker"
},
"data": {
"type": "machine-tracker",
"id":
"defg5678-cd34-56ef-cd34-ghijkl789012"
}
}
},
[...]

Page 11 / 34
fields Query no The API will only return the resource attributes
listed in this parameter, which helps deliver the data
faster and focus only on data useful for the
customer
Example :
● fields=serial-number,build-year ⇒ for a
connected-machine resource, the API will
return only the serial number and build year
attributes.

Applicable for connected-machine resources

filter[brand] Query no The API will filter the result so that only machines
filter[model]
matching the given attribute’s value are retrieved
filter[description]
filter[serial-number] Examples :
● filter[brand]=GEHL ⇒ get only GEHL
machines
● filter[model]=MT 625 H COMFORT 75K ST5
S1 ⇒ get all machines matching this model
● filter[serial-number]=MAN00000A0000000
⇒ get only the machine matching this serial
number

filter[height] Query no The API will filter the result so that only machines
filter[width]
matching the given attribute’s value or provided
filter[length]
filter[weight] value comparison are retrieved
filter[build-year] Examples :
● filter[height]=lt:2.5 ⇒ get machines
under 2.5 meters in height
● filter[weight]=ge:3000 ⇒ get machines
over or equal 3000 kg in weight
● filter[build-year]=ge:2015,le:2018 ⇒ get
machines built from 2015 to 2018 (including
boundaries)
● filter[build-year]=in(2017, 2019) ⇒ get
machines built in 2015 and 2019
● filter[brand]=nin(‘GEHL’,’MANITOU’) ⇒
get machines not branded as GEHL and
MANITOU

Applicable for machine-tracker resources

filter[tracker-serial- Query no The API will filter the result so that only machine
number]
trackers matching the given attribute’s value are
filter[tracker-phone-n
umber] retrieved
filter[tracker-imei] Example :
● filter[tracker-serial-number]=123456 ⇒
get all trackers matching this serial number

Page 12 / 34
Please note that the filter parameters can be combined one with another, so one can retrieve
all the machines of a given brand and for a given build year range, for example.

NOTE : as attribute values can differ from numerals to character strings, the attribute name
provided to perform the sort or filter must be chosen wisely.
When performing comparisons on a character string attribute, the user must understand that
even if the attribute value is expressed as a number (“1234”), it is not considered a number
data type, so sorting and comparing is made through lexicographic comparison.

Page 13 / 34
In details : the machine-state API

Endpoint URL
The API can be reached at :
https://api.manitou-group.com/machine-state/machine-state

Data set example

The following chart lists the fields exposed by the API :
JSON data Comments

{
"data" : [ Record list start indicator
{ Record start indicator
"attributes" : {
"latitude" : 56.88721000, latitude
"longitude" : -111.36433500, longitude
"altitude" : 0, Altitude in m
"street-address" : "Unnamed Road", Approximate street address
"city" : "Division No. 16", Approximate city
"zip-code" : "T0P", Approximate zip code
"country" : "CA", Approximate country code (2 letters)
"engine-status" : 0, Engine status (0 = off, 1 = on)
"key-status" : 1, Ignition key status (0 = off, 1 = on)
"odometer" : 124.20, Odometer in km
"cumulative-operation-hours" : 156, Tracking device’s engine on hours
"cumulative-idle-hours" : 148, Tracking device’s ignition on hours
"input3" : "0", Digital input 3 value (0 = off, 1 =
"input4" : "0", on)
"input5" : "0", Digital input 4 value (0 = off, 1 =
"input6" : "0", on)
"input7" : "0", Digital input 5 value (0 = off, 1 =
"input8" : "0", on)
"input9" : "0", Digital input 6 value (0 = off, 1 =
"input10" : "0", on)
"gps-fix-time" : "2019-12-08T17:40:50", Digital input 7 value (0 = off, 1 =
"message-time" : "2019-12-08T17:40:50", on)
"battery-voltage" : 14.00 Digital input 8 value (0 = off, 1 =
"cumulativeOperationSeconds" : 561600 on)
}, Digital input 9 value (0 = off, 1 =
"relationships" : { on)
"connected-machine" : { Digital input 10 value (0 = off, 1
"links" : { =on)
"self" : Gps positioning timestamp
"/machine-state/9e6c5a77-588c-4192-a01b-00cc07baa72a/rela Machine state timestamp
tionships/connected-machine", Machine battery voltage in V
"related" : Number of seconds of machine engine
"/machine-state/9e6c5a77-588c-4192-a01b-00cc07baa72a/conn operation (similar to
ected-machine" cumulativeOperationHours, but with a
}, better precision)
"data" : {
"type" : "connected-machine", Machine-dependent objects list
"id" : Machine-dependent connected-machine
"abcd1234-ab12-34cd-ab12-abcdef123456" info start
}
}
},
"type" : "machine-state",
"id" : "9e6c5a77-588c-4192-a01b-00cc07baa72a"
},

Page 14 / 34
 Connected resource type
Connected resource id
(See parameter “include” below)

Resource type
Resource id (machine-state id)

API parameters
This API allows the use of the following parameters :
Parameter name Type Manda Usage
-
tory

Ocp-Apim-Subscrip Header yes Customer subscription key (primary or secondary)

tion-Key

X-token Header yes Customer secret user token. Provide the API with
the secret user token that lets the customer retrieve
its resources.

api-version Header yes Version number of the API (v1, v2, etc.)

include=connected-mach Query no The API will return the id of the corresponding

ine
connected-machine in the
“relationships/connected-machine/data”
sub-schema.

page[size] Query no The API may return many resources records when
page[number]
called. The page[size] allows the user to define the
number of records wanted per page, and the
page[number] allows the user to jump to the
desired result page.
Examples :
● page[size]=30 ⇒ the API will return a
maximum of 30 records per response
● page[number]=3 ⇒ the API will return page
number 3 of all available results page.

filter[attribute name] Query no Similarly to the filtering feature of

connected-machine API, this API will filter the result

Page 15 / 34
 so that only machine state records matching the
given attribute’s value are retrieved
Examples :
● filter[message-time]=ge:2019-12-01T10:00
:00,le:2019-12-01T11:00:00 ⇒ the API will
return every recorded machine state for the
user, comprised between 10am and 11am
for Dec 1st 2019
● filter[connected-machine.id]=abcd1234-a
b12-34cd-ab12-abcdef123456 ⇒ the API
will return every available machine-state
record for the given machine id (as retrieved
from connected-machine API)
● filter[battery-voltage]=lt:10.5 ⇒ the
API will return every available machine-state
record indicating a machine battery voltage
under 10.5 volts
● filter[country]=in(‘FR’,’IT’) ⇒ get
machines located in France and Italy
● filter[country]=nin(‘BE’,’NL’) ⇒ get
machines not located in Belgium or the
Netherlands

sort Query no The API will order the result records list according
to ascending or descending value of the given
attribute name. Using a dash (“-”) before the
attribute name indicates the API to perform the sort
in a descending way. Elseway the sort is
ascending.
Examples :
● sort=battery-voltage ⇒ the API will return
every recorded machine state for the user,
ordered from lowest battery voltage attribute
value to highest
● sort=-odometer ⇒ the API will return every
recorded machine state for the user,
ordered from highest odometer attribute
value to lowest

fields Query no The API will only return the resource attributes
listed in this parameter, which helps deliver the data
faster and focus only on data useful for the
customer
Example :
● fields=message-time,battery-voltage ⇒
for a machine-state resource, the API will
return only the message time and battery
voltage attributes.

Page 16 / 34
The filter parameters can be combined one with another, so you can retrieve all the
machine-state records obtained today that show a cumulative-operation-hours over 3000 and
a battery voltage under 10 volts, for example.

NOTE : as attribute values can differ from numerals to character strings, the attribute name
provided to perform the sort or filter must be chosen wisely.
When performing comparisons on a character string attribute, the user must understand that
even if the attribute value is expressed as a number (“1234”), it is not considered a number
data type, so sorting and comparing is made through lexicographic comparison.
It must be noted that time-related information is expressed in Coordinated Universal Time
(UTC), unless otherwise mentioned.

Page 17 / 34
In details : the sensor-state API

Endpoint URL
The API can be reached at :
https://api.manitou-group.com/sensor-state/sensor-state

Data set example

The following chart lists the fields exposed by the API :
JSON data Comments

{
"data" : [ Record list start indicator
{ Record start indicator
"attributes" : {
"sensor-value" : "6.86", Sensor value (expressed in sensor
"tracker-Sensor-Id" : 10007, unit)
"sensor-name" : "Engine Percent Load At Sensor id
Current Speed", Sensor name
"sensor-unit" : "%", Sensor unit
"timestamp" : "2019-12-08T23:15:02" Sensor record timestamp
},
"relationships" : { Sensor-state dependent objects list
"equipment" : { Sensor-state dependent equipment info
"links" : { start
"self" :
"/sensor-state/ca058771-0d50-4392-a14f-7d19303896fe/relat
ionships/equipment",
"related" :
"/sensor-state/ca058771-0d50-4392-a14f-7d19303896fe/equip
ment"
},
"data" : {
"type" : "connected-machine", Dependant resource type
"id" : Dependent resource id
"abcd1234-ab12-34cd-ab12-abcdef123456" (See parameter “include” below)
}
}
}, Resource type
"type" : "sensor-state", Resouce id (machine-state id)
"id" : "ca058771-0d50-4392-a14f-7d19303896fe"
}, ...other records of sensor-state…
[...] Result pages link records start
"links" : { Next result page link
"next" :
"/sensor-state?page[size]=10&page[number]=2&filter[id]=ab
cd1234-ab12-34cd-ab12-abcdef123456", Last result page link
"last" :
"/sensor-state?page[size]=10&page[number]=652&filter[id]=
abcd1234-ab12-34cd-ab12-abcdef123456"
},
"meta" : { Total number of available records
"total-records" : 6513 matching the request
}
}

Page 18 / 34
 API parameters
This API allows the use of the following parameters :
Parameter name Type Manda Usage
-
tory

Ocp-Apim-Subscrip Header yes Customer subscription key (primary or secondary)

tion-Key

X-token Header yes Customer secret user token. Provide the API with
the secret user token that lets the customer retrieve
its resources.

api-version Header yes Version number of the API (v1, v2, etc.)

include=equipment Query no The API will return the id of the corresponding

equipment (connected-machine) in the
“relationships/equipment/data” sub-schema.

page[size] Query no The API may return many resources records when
page[number]
called. The page[size] allows the user to define the
number of records wanted per page, and the
page[number] allows the user to jump to the
desired result page.
Examples :
● page[size]=30 ⇒ the API will return a
maximum of 30 records per response
● page[number]=3 ⇒ the API will return page
number 3 of all available results page.

filter[attribute name] Query no Similarly to the filtering feature of

connected-machine API, this API will filter the result
so that only sensor state records matching the
given attribute’s value are retrieved
Examples :
● filter[tracker-Sensor-id]=10001 ⇒ the
API will return every recorded sensor state
for the user, for sensor id 10001 (see list in
the appendix)
● filter[timestamp]=ge:2019-12-01T10:00:00
,le:2019-12-01T11:00:00 ⇒ the API will
return every recorded sensor state for the
user, comprised between 10am and 11am
for Dec 1st 2019
● filter[equipment.id]=abcd1234-ab12-34c
d-ab12-abcdef123456 ⇒ the API will return
every available sensor-state record for the

Page 19 / 34
 given equipment id (as retrieved from
connected-machine API, provided the
equipment related to the sensor is of the
connected-machine type)
● filter[sensor-value]=lt:10 ⇒ the API will
return every available machine-state record
indicating a sensor-value under 10
● filter[tracker-Sensor-id]=in(10001,
10012) ⇒ get data for sensors 10001 and
10012
● filter[brand]=nin(10001, 10005) ⇒ get
data for sensors other than 10001 or 10012

sort Query no The API will order the result records list according
to ascending or descending value of the given
attribute name. Using a dash (“-”) before the
attribute name indicates the API to perform the sort
in a descending way. Elseway the sort is
ascending.
Examples :
● sort=sensor-value ⇒ the API will return
every recorded sensor state for the user,
ordered from lowest sensor-value attribute
value to highest
● sort=-sensor-value ⇒ the API will return
every recorded sensor state for the user,
ordered from highest sensor-value attribute
value to lowest

fields Query no The API will only return the resource attributes
listed in this parameter, which helps deliver the data
faster and focus only on data useful for the
customer
Example :
● fields=tracker-Sensor-Id,sensor-value ⇒
for a sensor-state resource, the API will
return only the sensor’s id and value.

NOTE : as attribute values can differ from numerals to character strings, the attribute name
provided to perform the sort or filter must be chosen wisely.
When performing comparisons on a character string attribute, the user must understand that
even if the attribute value is expressed as a number (“1234”), it is not considered a number
data type, so sorting and comparing is made through lexicographic comparison.
It must be noted that time-related information is expressed in Coordinated Universal Time
(UTC), unless otherwise mentioned.

Page 20 / 34
In details : the machine-analytic API

Endpoint URL
The API can be reached at :
https://api.manitou-group.com/machine-analytic/machine-analytic

Data set example

The following chart lists the fields exposed by the API :
JSON data Comments

{
"data" : [ Record list start indicator
{ Record start indicator
"attributes" : {
"reference-number" : "MAN00000Z000000123", Machine reference number (S/N)
"message-date" : "2019-11-12T00:00:00", Calculation date
"message-date-first": Date of the first message used to
compute the analytic value
"2021-08-18T06:13:53.217", Date of the last message used to
"message-date-last": compute the analytic value
Sensor id
"2021-08-18T06:58:53.726", Sensor name
"variable-id" : 10003, Sensor unit of measure
"var-name" : "Engine Total Hours of Min sensor value of the day
Operation", Max sensor value of the day
"uom" : "hr", Average sensor value of the day
"value-min" : 29.75, Sum of available values of the day
"value-max" : 36.049999237060547, Nb of available values of the day
"value-avg" : 33.072158813476562,
"value-sum" : 5820.7001953125, Machine-analytic dependent objects
"value-count" : 176.0 list
}, Machine-analytic dependent equipment
"relationships" : { info start
"equipment" : {
"links" : {
"self" :
"/equipment-analytic/6ccae061-e613-4fc7-9da4-0139dc68777d
/relationships/equipment",
"related" :
"/equipment-analytic/6ccae061-e613-4fc7-9da4-0139dc68777d
/equipment"
} Resource type
} Resouce id (equipment-analytic id)
},
"type" : "equipment-analytic", ...other records of machine-analytic…
"id" : "6ccae061-e613-4fc7-9da4-0139dc68777d" Result pages link records start
}, Last result page link
[...]
"links" : {
"last" :
"/equipment-analytic?page[size]=10&page[number]=1&filter[
reference-number]=MAN00000Z000000123&filter[message-date] Total number of available records
=ge:2019-11-12&filter[message-date]=le:2019-11-12" matching the request
},
"meta" : {
"total-records" : 2
}
}

Page 21 / 34
 API parameters
This API allows the use of the following parameters :
Parameter name Type Manda Usage
-
tory

Ocp-Apim-Subscrip Header yes Customer subscription key (primary or secondary)

tion-Key

X-token Header yes Customer secret user token. Provide the API with
the secret user token that lets the customer retrieve
its resources.

api-version Header yes Version number of the API (v1, v2, etc.)

page[size] Query no The API may return many resources records when
page[number]
called. The page[size] allows the user to define the
number of records wanted per page, and the
page[number] allows the user to jump to the
desired result page.
Examples :
● page[size]=30 ⇒ the API will return a
maximum of 30 records per response
● page[number]=3 ⇒ the API will return page
number 3 of all available results page.

filter[attribute name] Query no Similarly to the filtering feature of

connected-machine API, this API will filter the result
so that only sensor state records matching the
given attribute’s value are retrieved
Examples :
● filter[variable-id]=10001 ⇒ the API will
return every recorded machine-analytic for
the user, for sensor id 10001 (see list in the
appendix)
● filter[message-date]=ge:2019-12-01T10:00
:00,le:2019-12-01T11:00:00 ⇒ the API will
return every recorded machine-analytic for

Page 22 / 34
 the user, comprised between 10am and
11am for Dec 1st 2019
● filter[reference-number]=MAN00000Z0000001
23⇒ the API will return every available
machine-analytic record for the given
machine serial number

sort Query no The API will order the result records list according
to ascending or descending value of the given
attribute name. Using a dash (“-”) before the
attribute name indicates the API to perform the sort
in a descending way. Elseway the sort is
ascending.
Examples :
● sort=value-max ⇒ the API will return every
recorded machine-analytic for the user,
ordered from lowest value-max attribute
value to highest
● sort=-value-count ⇒ the API will return
every recorded machine-analytic for the
user, ordered from highest value-count
attribute value to lowest

fields Query no The API will only return the resource attributes
listed in this parameter, which helps deliver the data
faster and focus only on data useful for the
customer
Example :
● fields=variable-id,value-avg ⇒ for a
machine-analytics resource, the API will
return only the variable id and average
value attributes.

NOTE : as attribute values can differ from numerals to character strings, the attribute name
provided to perform the sort or filter must be chosen wisely.
When performing comparisons on a character string attribute, the user must understand that
even if the attribute value is expressed as a number (“1234”), it is not considered a number
data type, so sorting and comparing is made through lexicographic comparison.
It must be noted that time-related information is expressed in Coordinated Universal Time
(UTC), unless otherwise mentioned.

Page 23 / 34
In details : the maintenance-operation API

Endpoint URLs
The API can be reached at :
https://api.manitou-group.com/maintenance-operation/maintenance-op
eration
https://api.manitou-group.com/maintenance-operation/maintenance-it
em
https://api.manitou-group.com/maintenance-operation/maintenance-wo
rk

Data set example

The following chart lists the fields to transmit to the API for the creation of a
maintenance-operation resource :
JSON data Comments

{
"data": {
"type": "maintenance-operation", Resource type
"attributes": {
"dealer-code": "1", Machine dealer’s MANITOU customer #
"dealer-name": "FakeDealer001", Machine dealer’s name
"sender-software-name": "DealerERP", Machine dealer’s software name
"sender-software-version": "v2.021", Machine dealer’s software version
"operation-timestamp": "2021-02-10T10:10:10", Maintenance operation timestamp
"operation-number": "264", Maintenance operation reference
"equipment-hourmeter": 510, Machine hourmeter during maintenance
"operation-range": "Planned maintenance", Operation range
"operation-label": "500h complete checkup", Operation label
"operation-description": "Manufacturer recommended Operation description
500h planned maintenance + hydraulic leakage repair"
},
"relationships": { Relationship declaration
"connected-machine": { Concerned connected-machine resource
"data": {
"type": "connected-machine", Linked resource type
"id": "abcd1234-ab12-34cd-ab12-abcdef123456" Linked resource id
}
}
}
}
}

The following chart lists the fields to transmit to the API for the creation of a
maintenance-item resource :
JSON data Comments

{
"data": {
"type": "maintenance-item", Resource type
"attributes": {
"item-code": "4321", Item code

Page 24 / 34
 "item-name": "elbow grease", Item name
"item-quantity": 2.3 Item quantity
},
"relationships": { Relationship declaration
"maintenance-operation": { Concerned maintenance-operation
"data": { resource
"type": "maintenance-operation", Linked resource type
"id": "operat1234-op12-34er-op12-operat123456" Linked resource id
}
}
}
}
}

The following chart lists the fields to transmit to the API for the creation of a
maintenance-work resource :
JSON data Comments

{
"data": {
"type": "maintenance-work", Resource type
"attributes": {
"work-label": "Test général", Work operation label
"work-type": "Test", Work operation type
"work-quantity": 0.25 Work operation quantity
},
"relationships": { Relationship declaration
"maintenance-operation": { Concerned maintenance-operation
"data": { resource
"type": "maintenance-operation", Linked resource type
"id": "operat1234-op12-34er-op12-operat123456" Linked resource id
}
}
}
}
}

API parameters
This API allows the use of the following parameters :
Parameter name Type Manda Usage
-
tory

Applicable for all resources

Ocp-Apim-Subscrip Header yes Customer subscription key (primary or secondary)

tion-Key

X-token Header yes Customer secret user token. Provide the API with
the secret user token that lets the customer retrieve
its resources.

Page 25 / 34
api-version Header yes Version number of the API (v1, v2, etc.)

Message body Body yes See data set examples.

Return values
Here are the possible return values when sending a POST request to create a
maintenance-operation resource :
Content Comments

Successful creation

HTTP 201 Created Successfully created

Location: New resource location (contains the

/maintenance-operation/operat1234-op12-34er-op12-operat12 resource id)
3456

Body:
{
"links": {
"self": "/maintenance-operation"
},
"data": {
"type": "maintenance-operation",
"id": "operat1234-op12-34er-op12-operat123456", New resource id
"attributes": { Resource attributes
"dealer-code": "1",
"dealer-name": "FakeDealer001",
"sender-software-name": "DealerERP",
"sender-software-version": "v2.021",
"operation-timestamp": "2021-02-10T10:10:10",
"operation-number": "264",
"equipment-hourmeter": 510.00,
"operation-range": "Planned maintenance",
"operation-label": "500h complete checkup",
"operation-description": "Manufacturer
recommended 500h planned maintenance + hydraulic leakage
repair"
},
"relationships": { Relationships of the resource
"connected-machine": {
"links": {
"self": Link to the connected-machine
"/maintenance-operation/operat1234-op12-34er-op12-operat1
23456/relationships/connected-machine",
"related":
"/maintenance-operation/operat1234-op12-34er-op12-operat1
23456/connected-machine"
}
}
},
"links": {
"self": Link to self
"/maintenance-operation/operat1234-op12-34er-op12-operat1
23456"
}
}
}

Page 26 / 34
 Bad request

HTTP 400 Bad request Request couldn’t be handle because of

an error in the request
Body :
Error explanation when possible

Server error

HTTP 500 Internal server error Request couldn’t be handled because

of an error on the server’s side

Here are the possible return values when sending a POST request to create a
maintenance-item resource :
Content Comments

Successful creation

HTTP 201 Created Successfully created

Location: New resource location (contains the

/maintenance-item/item1234-it12-34em-it12-item1234 resource id)

Body:
{
"links": {
"self": "/maintenance-item"
},
"data": {
"type": "maintenance-item",
"id": "item1234-it12-34em-it12-item1234", New resource id
"attributes": { Resource attributes
"item-code": "4321",
"item-name": "elbow grease",
"item-quantity": 2.30
},
"relationships": { Relationships of the resource
"maintenance-operation": {
"links": {
"self": Link to the maintenance-operation
"/maintenance-item/item1234-it12-34em-it12-item1234/relat
ionships/maintenance-operation",
"related":
"/maintenance-item/item1234-it12-34em-it12-item1234/maint
enance-operation"
}
}
},
"links": {
"self": Link to self
"/maintenance-item/item1234-it12-34em-it12-item1234"
}
}
}

Bad request

HTTP 400 Bad request Request couldn’t be handle because of

an error in the request
Body :

Page 27 / 34
 Error explanation when possible

Server error

HTTP 500 Internal server error Request couldn’t be handled because

of an error on the server’s side

Here are the possible return values when sending a POST request to create a
maintenance-work resource :
Content Comments

Successful creation

HTTP 201 Created Successfully created

Location: New resource location (contains the

/maintenance-work/work5678-wo56-78rk-wo56-work5678 resource id)

Body:
{
"links": {
"self": "/maintenance-work"
},
"data": {
"type": "maintenance-work",
"id": "work5678-wo56-78rk-wo56-work5678", New resource id
"attributes": { Resource attributes
"work-label": "Test général",
"work-type": "Test",
"work-quantity": 0.25
},
"relationships": { Relationships of the resource
"maintenance-operation": {
"links": {
"self": Link to the maintenance-operation
"/maintenance-work/work5678-wo56-78rk-wo56-work5678/relat
ionships/maintenance-operation",
"related":
"/maintenance-work/work5678-wo56-78rk-wo56-work5678/maint
enance-operation"
}
}
},
"links": {
"self": Link to self
"/maintenance-work/b2345968-82f1-41db-b415-08d908c2de28"
}
}
}

Bad request

HTTP 400 Bad request Request couldn’t be handle because of

an error in the request
Body :
Error explanation when possible

Server error

Page 28 / 34
HTTP 500 Internal server error Request couldn’t be handled because
of an error on the server’s side

Page 29 / 34
Appendix : list of sensor id’s and description
This list details all availables sensor id’s. Please note that not all sensors listed below
do exist on every machine : depending on the machine range, model and options,
some may not be available.
Please note also that this list may be updated as new machines and options are
made available.
Sensor Description In In
id sensor- machine-
state analytic
API API

101 Temperature1

102 Temperature2

498 Engine Starter Mode X X

512 Ambient Air Temperature X X

884 Transmission Oil Temperature 1 X X

1296 attachment recognition X X

1300 Boom movement cut off X X

1301 Current engine status X X

1302 Current ignition status X X

1303 Attachment Confirmed X X

1304 Fuel less than 10% X X

1305 Command position X X

1306 Machine Type (PLUS 2150 = 1;Plus 2550 = 2; etc) X X

1307 Engine type (Mercedes-Benz = 1; Perkins = 2; etc) X X

1308 transmission type (Sauer = 1; Rexroth = 2;etc) X X

1310 Diesel Particulate Filter Status X X

1311 SPN Error code from CPC4 (Mercedes-Benza Master ECU) X X

X X
1312 FMI Error code from CPC4 (Mercedes-Benza Master ECU)

Page 30 / 34
1313 Distributor errors X X

1314 Transmission errors X X

1315 Manitou Error codes X X

1316 Manitou Warning message X X

1317 Actual load X X

1319 Radius X X

1320 Height X X

1321 turret position X X

1322 Angle X X

1323 Lmi percentage X X

1324 SPN Error code from MCM X X

1325 FMI Error code from MCM X X

1326 SPN Error code from ACM X X

1327 FMI Error code from ACM X X

1471 Transmission Oil Pressure X X

1475 Total Vehicle Distance X X

1476 Engine Intake Air Temperature X X

1770 Auxiliary I/O #03 X X

1771 Auxiliary I/O #02 X X

1783 Ambient Air Temperature X X

1792 Engine Coolant Level 1 X X

1793 Engine Air Filter 1 Differential Pressure X X

1794 Aftertreatment Diesel Particulate Filter Active Regeneration Status X X

2030 Telescop In status X X

2031 Cab/ Platform /RC mode status X X

2032 Fork / Bucket / Suspended load mode status X X

Page 31 / 34
2033 DEF tank level below 10% X X

2034 Direction engaged X X

2035 Strain gauge (Max/min) X X

2036 Strain gauge (Average) X X

2077 Engine Oil Temperature 1 X X

Diesel Particulate Filter Active Regeneration Inhibited Due to Inhibit

2084 Switch X X

2085 Aftertreatment SCR Operator Inducement Severity X X

2086 Aftertreatment 1 Diesel Particulate Filter Soot Load Percent X X

2087 Aftertreatment 1 Diesel Particulate Filter Ash Load Percent X X

2106 STOP Lamp X X

2107 WARNING Lamp X X

2108 Servicing Lamp X X

2109 Active Error Code X X

2950 Active Diagnostic Trouble Codes X X

3660 Door opened while driving X X

3661 Travelling with boom angle high X X

4873 Driving without seatbelt X X

10001 Engine Coolant Temperature X X

10002 Engine Speed X X

10003 Engine Total Hours of Operation X X

10004 Maximum load X X

10005 Engine Total Fuel Used X X

10006 Engine Oil Pressure X X

10007 Engine Percent Load At Current Speed X X

10008 Aftertreatment 1 Diesel Exhaust Fluid Concentration X X

Page 32 / 34
10009 Aftertreatment Diesel Particulate Filter Status X X

X
10010 Aftertreatment 1 Diesel Exhaust Fluid Tank Level X

10011 Air Filter Clogging lamp X X

10012 Alternator Not Charging lamp X X

10013 Wheel-Based Vehicle Speed X X

10014 Coolant Temperature lamp X X

10015 Dpf lamp X X

10016 Engine Fuel Rate X X

10017 Engine Oil Pressure lamp X X

10018 Exhaust System High Temperature Lamp Command X X

10019 Fault Braking lamp X X

10020 Fuel Level X X

10021 Hydraulic Filter Clogging lamp X X

10022 Low Brake Fluid Level lamp X X

10023 Low Coolant Fluid Level lamp X X

10024 Outriggers on ground X X

10025 Override X X

10026 Scr lamp X X

10027 Seat X X

10028 Steering Default lamp X X

10029 Transmission Oil Pressure lamp X X

10030 Transmission Oil Temperature lamp X X

10031 Water In Fuel Indicator 1 X X

10032 Power battery charge level X X

10033 Power battery voltage X X

Page 33 / 34
10034 Power battery capacity X X

20002 Hourly breakdown : engine use duration during a 1h period (in seconds) X

20003 Fuel consumption during a 1h period (in liters) X

20004 CO2 mass emission during a 1h period (in kg) X

30000 ISO 15143 - Peak daily speed in the last 24h (in km/h) X

30001 ISO 15143 - Peak daily speed in the last 24h (in mph) X

30002 ISO 15143 - Fuel consumption in the last 24h (in liters) X

30003 ISO 15143 - Fuel consumption in the last 24h (in US gallons) X

30005 ISO 15143 - Average engine load factor in the last 24h (in %) X

40000 ISO 15143 - Peak daily speed in the last 24h of engine runtime (in km/h) X

40001 ISO 15143 - Peak daily speed in the last 24h of engine runtime (in mph) X

ISO 15143 - Fuel consumption in the last 24h of engine runtime (in
40002 liters) X

ISO 15143 - Fuel consumption in the last 24h of engine runtime (in US
40003 gallons) X

ISO 15143 - Average engine load factor in the last 24h of engine
40005 runtime (in %) X

Page 34 / 34