AEMP / ISO-15143-3 API feed

Authentication

This uses OAuth or OAuth2.0 and a client is expected to supply a bearer token with every request. The authenticate-endpoint returns an idToken and a RefreshToken that can be exchanged for another idToken. Client requests to the API should supply the idToken in the Authorization Header.

OAuth

POST /v1/auth/authenticate

Request

https://api.machinemax.com/v1/auth/authenticate

Body

{
"email":"API_EMAIL",
"password":"PASSWORD"
}

(please request this information)

OAuth 2.0

POST /v1/auth/authenticate

Request

https://api.machinemax.com/v1/auth/authenticate

Body

Format: x-www-form-urlencoded

"username":"API_EMAIL"
"password":"PASSWORD"
"client_id":"54c581f5c6bba1d37d167cc49ce138f3"
"client_secret":"12c32811cb72aee03c7aea33afaf9b5b9e13e5c277ee32f7d293b298cfa676af"

(please request this information)

MachineMax OEM Fleet AEMP 2.0 v1.1

GET /v1/iso/Fleet/{pageNumber}

Request

https://api.machinemax.com/v1/iso/Fleet/1

Headers

Accept: application/json
Authorization: bearer eyJhbGciOiJSUz...

Supported content types: application/json and application/xml

Example response

{
"Fleet": {
"version": 1,
"snapshotTime": "2019-08-30T13:02:21Z",
"Links": [
{
"rel": "self",
"href": "https://api.machinemax.com/v1/iso/Fleet/1"
}
{
"rel": "next",
"href": "https://api.machinemax.com/v1/iso/Fleet/2"
}
{
"rel": "first",
"href": "https://api.machinemax.com/v1/iso/Fleet/1"
}
{
"rel": "last",
"href": "https://api.machinemax.com/v1/iso/Fleet/4"
}
]
"Equipment": [
{
"EquipmentHeader": {
"OEMName": "JCB",
"Model": "M",
"EquipmentID": "ID1",
"SerialNumber": "1234567890",
"PIN": "1234567890"
},
"Location": {
"Latitude": 2.12343,
"Longitude": 1.2345,
"datetime": "2019-08-30T13:02:21Z",
},
"CumulativeIdleHours": {
"Hour": 555,
"datetime": "2019-08-30T13:02:21Z",
},
"CumulativeOperatingHours": {
"Hour": 999,
"datetime": "2019-08-30T13:02:21Z",
},
"FuelUsed": {
"FuelUnits": "litre",
"FuelConsumed": 5342,
"datetime": "2019-08-30T13:02:21Z",
},
"FuelUsedLast24": {
"FuelUnits": "litre",
"FuelConsumed": 34,
"datetime": "2019-08-30T13:02:21Z",
}
}
]
}
}

Please note, these fields will only be present in the response if there is a value coming from the original OEM API feed.

Notes

The Equipment ID will display the name that the machine has in the OEM data. If you want the Asset id from MachineMax to be displayed then you must add "assetId" to the end of the URL, e.g. https://api.machinemax.com/v1/iso/Fleet?assetId

MachineMax Sensor Fleet AEMP 2.0 v2.0

GET /v2/iso/Fleet/{pageNumber}

Request

https://api.machinemax.com/v2/iso/Fleet/1

Headers

Accept: application/json
Authorization: Bearer eyJhbGciOiJSUz...

Supported content types: application/json and application/xml

Example response

Please note, these fields will only be present in the response if there is a value for the relevant field.

MachineMax Sensor Summary V2.0

GET /v2/machines/summary

This provides an overview of the fleet of machines in an organisation.
Authentication is performed using a bearer token.

Request

https://api.machinemax.com/v2/machines/summary

Headers

Accept: application/json
Authorization: Bearer eyJhbGciOiJSUz...

Parameters

startDate: request data from this date (inclusive), required, format: YYYY-MM-DD
‍endDate: request data up until this date (inclusive), required, format: YYYY-MM-DD‍
tz: timezone, optional, sets the timezone on all response timestamps. Supported values can be found here (use "TZ Identifier").
Example:

startDate: 2019-08-30
endDate: 2019-08-30
tz: Europe%2FLondon

Example response

{
"start": "2019-08-30T00:00:00+01:00",
"end": "2019-08-31T00:00:00+01:00",
"machines": [
{
"id": "d1356b75-7a16-4231-bc5a-1ba54e60f0ab",
"assetId": "BY001",
"name": "Big Yellow",
"oem": "CAT",
"vin": "CBY123456789",
"manufacturingYear": "2021",
"profileUrl": "https://machinemax.com/machines/d1356b75-7a16-4231-bc5a-1ba54e60f0ab",
"imageUrl": "https://api.machinemax.com/v1/images/machines/fea99f7f3f44b7372d5398573882dbd0",
"site": "My Big Site",
"ownership": {
"type": "Owned",
"owner": "MachineMax"
},
"location": {
"trackerId": "12345",
"latitude": 51.5,
"longitude": -0.06,
"lastUpdated": "2019-08-30T13:02:21+01:00"
},
"activity": {
"totalHourMeter": 15921,
"activeHours": 1,
"idleHours": 1,
"onHours": 2,
"offHours": 18,
"missingHours": 2,
"lastState": "ACTIVE",
"lastUpdated": "2019-08-30T14:33:24+01:00"
},
"metadata": {},
"machineType": {
"type": "Electric Crane",
"category": "CRANE",
"model": "EC102X",
"engine": {
"type": "Diesel",
"emissionStandard": "Stage IIIB"
}
}
}
]
}

MachineMax Sensor Details v1.1

GET /v1/machines/detail

This provides a detailed overview of the fleet of machines in an organisation. Any idle periods have a location associated with them.
Authentication is performed using a bearer token.

Request

https://api.machinemax.com/v1/machines/detail

Headers

Accept: application/json
Authorization: Bearer eyJhbGciOiJSUz...

Parameters

start: request data from this timestamp, required, format: YYYY-MM-DDTHH:MM:SS. Don't include a timezone
‍end: request data up until this timestamp, required, format: YYYY-MM-DDTHH:MM:SS. Don't include a timezone
machine_id: optional, filter response to specific machine.
tz: timezone, optional, sets the timezone on all response timestamps. Supported values can be found here (use "TZ Identifier").
Example:

start: 2019-08-30T00:00:00
end: 2019-08-31T00:00:00
machine_id: f838db85-b25a-4438-8dc8-2181ced80063
tz: Europe%2FBerlin

Example response

The datetimes in the response will be in the user’s timezone.

{
"start": "2019-08-30T00:00:00+01:00",
"end": "2019-08-31T00:00:00+01:00",
"machines": [
{
"id": "d1356b75-7a16-4231-bc5a-1ba54e60f0ab",
"name": "Big Yellow",
"assetId": "MX10001",
"vin": "1234567890",
"machineType": {
"oem": "MachineMax",
"model": "EC1231",
"type": "ELECTRIC_CRANE",
"category": "CRANE"
},
"profileUrl": "https://machinemax.com/machines/d1356b75-7a16-4231-bc5a-1ba54e60f0ab",
"imageUrl": "https://api.machinemax.com/v1/images/machines/fea99f7f3f44b7372d5398573882dbd0",
"activity": {
"activeHours": 0.5,
"idleHours": 0.25,
"onHours": 0.75,
"offHours": 18,
"missingHours": 5.25,
"lastState": "ACTIVE",
"lastUpdated": "2019-08-30T14:33:24+01:00"
},
"location": {
"trackerId": "12345",
"latitude": 51.5,
"longitude": -0.06,
"lastUpdated": "2019-08-30T13:02:21+01:00"
},
"segments": [
{
"start": "2019-08-31T13:46:01+01:00",
"end": "2019-08-31T14:01:00+01:00",
"state": "IDLE",
"sensor": "ABCDE",
"group": "GROUP 1",
"shift": "A",
"shiftDate": "2019-08-30",
"zone": "GEO 1",
"location": {
"trackerId": "12345678023",
"latitude": 51.5,
"longitude": -0.06,
"lastUpdated": "2019-08-30T13:02:21+01:00"
}
},
{
"start": "2019-08-31T04:01:01+01:00",
"end": "2019-08-31T04:31:00+01:00",
"state": "ACTIVE",
"sensor": "12345",
"group": "",
"shift": "B",
"shiftDate": "2019-08-30",
"zone": "GEO 2"
}
]
}
]
}

MachineMax Sensor Location v1.1

GET /v1/portal/machines/latest_location

Return the latest location available for all machines scoped to that user. This means that if the machine was out of scope for the user at the timestamp of the latest location, then it will not be included in the response.
Since some of the scoping is done on a date-basis (e.g. customer for rental orgs), each location’s date will need to be checked in its respective machine’s timezone to ensure that it is in scope.

Request

https://api.machinemax.com/v1/portal/machines/latest_location

Headers

Accept: application/json
Authorization: Bearer eyJhbGciOiJSUz...

Parameters

‍tz: timezone, optional, sets the timezone on all response timestamps. Supported values can be found here (use "TZ Identifier").
‍Example:

tz: Etc%2FUTC

Example response

{
"machines": [
{
"OEMName": "JCB",
"Model": "M",
"EquipmentID": "ID1",
"SerialNumber": "1234567890",
"PIN": "1234567890",
"Location": {
"Latitude": 2.12343,
"Longitude": 1.2345,
"datetime": "2019-08-30T13:02:21Z"
}
},
{
"OEMName": "JCB",
"Model": "M",
"EquipmentID": "ID2",
"SerialNumber": "0987654321",
"PIN": "0987654321",
"Location": {
"Latitude": 4.23434,
"Longitude": -1.5349,
"datetime": "2019-08-30T11:33:21Z"
}
},
{
// ...
}
]
}

MachineMax Sensor Dealer v1.1

GET/v1/portal/dealer/machines

Request

https://api.machinemax.com/v1/portal/dealer/machines

Headers

Accept: application/json
Authorization: Bearer eyJhbGciOiJSUz...

Parameters

‍tz: timezone, optional, sets the timezone on all response timestamps. Supported values can be found here (use "TZ Identifier").
‍Example:

tz: Europe%2FLondon

Example response

{
"machines": [
{
"assetId": "DealerMachine1",
"hours": {
"datetime": "2021-08-12T10:35:55+01:00",
"hours": 987.7
},
"location": {
"Latitude": 51.6107,
"Longitude": 0.3155,
"datetime": "2021-08-12T10:37:13+01:00"
},
"name": "DealerMachine1",
"owner": "ME",
"ownershipType": "OWNED",
"type": "COMPRESSOR"
},
{
"assetId": "CustomerMachine1",
"hours": null,
"location": null,
"name": "CustomerMachine1",
"owner": "Them",
"ownershipType": "LEASED",
"type": "DOZER"
},
{
"assetId": "CustomerMachine2",
"hours": {
"datetime": "2021-08-12T10:33:07+01:00",
"hours": 1234.5
},
"location": null,
"name": "CustomerMachine2",
"owner": "They",
"ownershipType": "RENTED",
"type": "CONVEYOR"
}
]
}

MachineMax Fleet v1.0

GET /v1/fleet

This provides the current equipment information for the entire active fleet.Authentication is performed using a bearer token.

Request

https://api.machinemax.com/v1/fleet

Headers

Authorization: Bearer eyJhbGciOiJSUz..

Parameters

equipment: one or more equipment ID, optional, default = get all equipment in response (omitted)
tz: timezone, optional, sets the timezone on all response timestamps. Supported values can be found here (use "TZ Identifier").
‍Example:

equipment: 72b663f7-fcf4-4225-8ad4-d210dc60af8e
tz: Etc%2FUTC

Example response

{
"snapshotTime": "2022-03-28T23:59:59Z",
"equipment": [
{
"identity": {
"id": "72b663f7-fcf4-4225-8ad4-d210dc60af8e",
"name": "My Machine",
"assetId": "MM0001",
"vin": "MX123456789M"
},
"classification": {
"type": "Mini Excavator",
"category": "Excavator",
"oem": "Hitachi",
"model": "ZX26U-6",
"year": 2022
},
"engine": {
"type": "Diesel",
"emissionStandard": "Stage V"
},
"ownership": {
"type": "Owned",
"owner": "MachineMax"
},
"sources": [
{
"id": "123456789012345",
"short": "901234",
"type": "MaxActive - Cellular"
}
],
"allocation": {
"organisation": "MachineMax",
"customer": "CustomerMax",
"site": "London",
"group": "SW1"
},
"links": [
{
"rel": "profile",
"href": "https://machinemax.com/machines/72b663f7-fcf4-4225-8ad4-d210dc60af8e"
},
{
"rel": "equipment",
"href": "https://api.machinemax.com/v1/fleet?equipment=72b663f7-fcf4-4225-8ad4-d210dc60af8e"
},
{
"rel": "summary",
"href": "https://api.machinemax.com/v2/machines/summary?machineId=72b663f7-fcf4-4225-8ad4-d210dc60af8e&startDate=2022-03-28&endDate=2022-03-28"
},
{
"rel": "segments",
"href": "https://api.machinemax.com/v1/activity/segments?equipment=72b663f7-fcf4-4225-8ad4-d210dc60af8e&start=2022-03-28T00%3A00%3A00%2B08%3A00&end=2022-03-29T00%3A00%3A00%2B01%3A00"
}
]
}
]
}

Please note, fields will only be present in the response if there is a value for the relevant field.

MachineMax Activity - Segments v1.0

GET /v1/activity/segments

This provides the segment breakdown of a fleet’s activity. Authentication is performed using a bearer token.

Request

https://api.machinemax.com/v1/activity/segments

Headers

Authorization: Bearer eyJhbGciOiJSUz...

Parameters

start: request data from this timestamp, required, format: YYYY-MM-DDTHH:MM:SS+TZ, URL encoded
‍end: request data up until this timestamp, required, format: YYYY-MM-DDTHH:MM:SS+TZ, URL encoded
‍equipment: one or more equipment ID, optional, default = get all equipment in response (omitted)
‍page: request data for this page, optional, default = 1
tz: timezone, optional, sets the timezone on all response timestamps. Does not affect the timezone of the start and end parameters. Supported values can be found here (use "TZ Identifier")
Example:

start: 2022-03-28T00%3A00%3A00%2B01%3A00
end: 2022-03-29T00%3A00%3A00%2B01%3A00
equipment: 72b663f7-fcf4-4225-8ad4-d210dc60af8e
page: 3
tz: Europe%2FBerlin

Example response

{
"links": [
{
"rel": "self",
"href": "https://api.machinemax.com/v1/activity/segments?start=2022-03-28T00%3A00%3A00%2B01%3A00&end=2022-03-29T00%3A00%3A00%2B01%3A00&equipment=72b663f7-fcf4-4225-8ad4-d210dc60af8e&page=3"
},
{
"rel": "first",
"href": "https://api.machinemax.com/v1/activity/segments?start=2022-03-28T00%3A00%3A00%2B01%3A00&end=2022-03-29T00%3A00%3A00%2B01%3A00&equipment=72b663f7-fcf4-4225-8ad4-d210dc60af8e&page=1"
},
{
"rel": "previous",
"href": "https://api.machinemax.com/v1/activity/segments?start=2022-03-28T00%3A00%3A00%2B01%3A00&end=2022-03-29T00%3A00%3A00%2B01%3A00&equipment=72b663f7-fcf4-4225-8ad4-d210dc60af8e&page=2"
},
{
"rel": "next",
"href": "https://api.machinemax.com/v1/activity/segments?start=2022-03-28T00%3A00%3A00%2B01%3A00&end=2022-03-29T00%3A00%3A00%2B01%3A00&equipment=72b663f7-fcf4-4225-8ad4-d210dc60af8e&page=4"
},
{
"rel": "last",
"href": "https://api.machinemax.com/v1/activity/segments?start=2022-03-28T00%3A00%3A00%2B01%3A00&end=2022-03-29T00%3A00%3A00%2B01%3A00&equipment=72b663f7-fcf4-4225-8ad4-d210dc60af8e&page=10"
}
],
"start": "2022-03-28T00:00:00+01:00",
"end": "2022-03-29T00:00:01+01:00",
"page": 3,
"segments": [
{
"start": "2022-03-28T00:00:00+01:00",
"end": "2022-03-28T01:00:01+01:00",
"state": "ACTIVE",
"equipment": {
"id": "72b663f7-fcf4-4225-8ad4-d210dc60af8e",
"name": "My Machine",
"assetId": "MM0001",
"links": [
{
"rel": "profile",
"href": "https://machinemax.com/machines/72b663f7-fcf4-4225-8ad4-d210dc60af8e"
},
{
"rel": "equipment",
"href": "https://api.machinemax.com/v1/fleet?equipment=72b663f7-fcf4-4225-8ad4-d210dc60af8e"
},
{
"rel": "summary",
"href": "https://api.machinemax.com/v2/machines/summary?machineId=72b663f7-fcf4-4225-8ad4-d210dc60af8e&startDate=2022-03-28&endDate=2022-03-28"
},
{
"rel": "segments",
"href": "https://api.machinemax.com/v1/activity/segments?equipment=72b663f7-fcf4-4225-8ad4-d210dc60af8e&start=2022-03-28T00%3A00%3A00%2B01%3A00&end=2022-03-29T00%3A00%3A01%2B01%3A00"
}
]
},
"site": {
"id": "8ce1eefa-0ee3-4a70-863c-35f14613ce15",
"name": "London"
},
"group": {
"id": "0cfff394-74d2-4d8c-8ad6-a8630c31a528",
"name": "SW1"
},
"shift": {
"id": "2454156d-1d76-4c98-975b-f612aeb3cda5",
"name": "Morning",
"date": "2022-03-28"
},
"geofences": [
{
"id": "329cdff7-2761-4904-9350-8393f59202f8",
"name": "Depot"
}
]
}
]
}

Please note, fields will only be present in the response if there is a value for the relevant field.

Segment state can be one of the following values ACTIVE, IDLE, OFF, or MISSING.

MachineMax Device Health v1.0

GET /v1/devices/health

This provides the health status of a MM device

Request

https://api.machinemax.com/v1/devices/health

Headers

Accept: application/json
Authorization: Bearer eyJhbGciOiJSUz...

Parameters

tz: timezone, optional, sets the timezone on all response timestamps. Does not affect the timezone of the start and end parameters. Supported values can be found here (use "TZ Identifier")
Example:

tz: Etc%2FUTC

Example response

{
"snapshotTime": "2022-02-22T12:26:26Z",
"devices": [
{
"id": "1234561212112", // external_id
"short": "12345", // external_short
"type": "MaxActive",
"model": "MAX-ALE",
"status": "unresponsive",
"batteryStatus": "good",
"latestConnection": "YYYY-MM-DDTHH:MM:SS+01:00",
"latestHoursUpdate": "YYYY-MM-DDTHH:MM:SS+01:00",
"location": {
"latitude": 12.12,
"longitude": 14.14,
"lastUpdated": "YYYY-MM-DDTHH:MM:SS+01:00"
},
"equipment": {
"id": "72b663f7-fcf4-4225-8ad4-d210dc60af8e",
"name": "My Machine",
"assetId": "MM0001",
"links": [
{
"rel": "profile",
"href": "https://machinemax.com/machines/72b663f7-fcf4-4225-8ad4-d210dc60af8e"
},
{
"rel": "equipment",
"href": "https://api.machinemax.com/v1/fleet?equipment=72b663f7-fcf4-4225-8ad4-d210dc60af8e"
}
]
}
}
]
}

Please note, fields will only be present in the response if there is a value for the relevant field.

Segment state can be one of the following values ACTIVE, IDLE, OFF, or MISSING.

MachineMax APIs

Quick Links

Quick links

AEMP / ISO-15143-3 API feed

Authentication

OAuth

POST /v1/auth/authenticate

OAuth 2.0

POST /v1/auth/authenticate

MachineMax OEM Fleet AEMP 2.0 v1.1

GET /v1/iso/Fleet/{pageNumber}

MachineMax Sensor Fleet AEMP 2.0 v2.0

GET /v2/iso/Fleet/{pageNumber}

MachineMax Sensor Summary V2.0

GET /v2/machines/summary

MachineMax Sensor Details v1.1

GET /v1/machines/detail

MachineMax Sensor Location v1.1

GET /v1/portal/machines/latest_location

MachineMax Sensor Dealer v1.1

GET/v1/portal/dealer/machines

MachineMax Fleet v1.0

GET /v1/fleet

MachineMax Activity - Segments v1.0

GET /v1/activity/segments

MachineMax Device Health v1.0

GET /v1/devices/health