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.
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
{
"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 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: 2019-08-30
endDate: 2019-08-30
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: 2019-08-30T00:00:00
end: 2019-08-31T00:00:00
machine_id: f838db85-b25a-4438-8dc8-2181ced80063
- start and end only support date with time format
- timezone should not be included, only the date and time in the format above
- machine_id is optional
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...
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...
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)
Example:
equipment: 72b663f7-fcf4-4225-8ad4-d210dc60af8e
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
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
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...
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.
