Add static Axle and Total Mass information fields to the Vehicle endpoint

Type of request

[X] I'd like to add something to the OTM 5 spec
[ ] I'd like to change something in the OTM 5 spec

Is your feature request related to a problem? With the current OTM 5.5 specification it's not possible to add vehicle (and combination) weights and axle loads to the Vehicle-endpoint (https://otm5.opentripmodel.org/#tag/Vehicle/paths/~1api~1v5~1vehicles/put). This revolves around static weight and axle information and dynamic total masses and axle weights (from sensors)

These data elements/ fields will be more and more used in city logistics and motorway environments in the future, as well as statistics provisioning. I'd like OTM to prepare for this to add data elements/ fields for this in an upcoming version of OTM.

NB. emptyWeight is already available in OTM 5.5 under the Vehicles Endpoint. All other defined fields below are not. NB. This change request is for the static axle and weights information. Another CR will follow for dynamic weight and axle information.

Describe the solution you'd like At the Vehicles endpoint, I'd like to see fields for:

massRoadReadyVehicle (integer in kg) - NL: massa rijklaar. This value indicates the mass of the vehicle in running order, expressed in kilograms, with a 90 percent full fuel tank and a driver (75 kg).
permittedMaxVehicleMass (integer in kg) - NL: toegestaan maximaal gewicht. The legally permitted maximum mass of the vehicle, derived from the technically permitted maximum mass of the vehicle. If necessary, reduced on the basis of legal provisions or at the request of the applicant for the registration certificate.
maxGrossCombinationWeight (integer in kg) - NL: maximum massa samenstel. The highest weight that the towing and towed vehicle may weigh together. Maximum mass of the combination.
maxVehiclePayload (integer in kg) - NL: laadvermogen. This is the legally permitted maximum mass of the vehicle minus the unladen mass, expressed in kilograms.
axleCountStatic (integer) - NL: aantal assen op het voertuig. Count of the number of axles available on the vehicle
axleNumber (integer) - NL: asnummer. The number of the (physical) axle calculated from the front of the vehicle. With swing axles, the number is determined from left to right, seen from the direction of travel.
permittedMaxAxleLoad (integer in kg) - NL: wettelijk toegestane maximale aslast. The legally permitted maximum mass on the axle, derived from the technically permitted maximum mass. If necessary, this has been reduced on the basis of legal provisions or at the request of the applicant for the registration certificate.

Note that axleNumber should give an array, that is: a single vehicle could have 2 or more axles, with varying max axle weights per axle. All individual axles should therefore be counted and permittedMaxAxleLoad should be added for each.

Describe alternatives you've considered For permittedMaxAxleLoads, an alternative could be to just take the maximum of any axle load. For example: if a tractor unit has 2 axles, 1st axle with max 7500 kg and 2nd axle with max 11500 kg, then just keep the 11500, and discard the array. Disadvantage, however, is that this works well for tandem (2 axles in a row) or tridem (trailers with 3 axles in a row) but not so much for tractor units. And as soon as we add dynamic axle loads (another CR), then it's probably easier to just match that with the individual axles.

Additional context With regard tot static Axle information (that is, information of the available axes on the vehicle, either the tractor or trailer unit), an IT company may populate the fields in their systems/ databases based on capturing data from the RDW open vehicle data endpoints (using the license plate of the vehicle as key). Below is a workout example.

NB. Dynamic axle load information of course is not available from the RDW, but should be gathered from onboard fleet-management system (CANbus/OBDII, etc) or from wireless axle load sensors attached to fleet management system. Or more practically from the massRoadReadyVehicle + weight from the Goods path an a possible approximation of the actual vehicle combination weight(https://otm5.opentripmodel.org/#tag/Goods/paths/~1api~1v5~1goods~1%7BUUID%7D/get)

Basic vehicle information: GET https://opendata.rdw.nl/resource/m9d7-ebf2.json?kenteken=87BKB8

Fuel type, axle configuration, vehicle body information Axle configuration: GET https://opendata.rdw.nl/resource/3huj-srit.json?kenteken=87BKB8

Vehicle body information: GET https://opendata.rdw.nl/resource/vezc-m2t6.json?kenteken=87BKB8

Fuel type: GET https://opendata.rdw.nl/resource/8ys7-d773.json?kenteken=87BKB8

Hello @robbertjanssen85, thanks for your extensive Change Request. I think these are very relevant. We have planned a release 5.6 for November for which we already had a cutoff. However, this gives us some time to think on the details of this approach. I am not an expert on vehicle data, but here is some feedback:

I think it would be more consistent if all values are value-with-unit like other dimensions and weights for vehicles.So not just an int, but a record that has a value (double) and unit.
I expect that trailers can have the same attributes, at least to a certain extend. So we likely need to add it to transportEquipment as well. I would be interested where the similarities and differences lie.
If axleNumber is an array, then I think it would be more logical to call it axleNumbers.
You said something about dynamic properties. I would like to take that into account for the total change request.

Maybe this topic is too big to discuss just offline. So maybe you can join one of the sessions we have to discuss the details of your change reques?

Hi @bmeesters thanks for the feedback. agree with all the points.

and sure, would like to join one of the meetings to discuss further. I'll ask Wout for an invite.

Cheers Robbert

@robbertjanssen85 I looked at the examples and tried to come up with a format that fits with the rest of the OTM5 specification:

{
   "entityType": "vehicle",
   .. // other vehicle data
   "legal": {
     "permittenMassVehicleMass": {
       "value": 0,
       "unit": "kg"
     },
     "maxGrossCombinationWeight": {
       "value": 0,
       "unit": "kg"
     },
     "maxPayload": {
       "value": 0,
       "unit": "kg"     
     }
   },
   "axles": [
     {
       "driveAxle": true, // aangedreven as
       "liftAxle": true, // hefas
       "sequenceNr": 1,
       "placement": "G", // plaats code, not sure what would be sensible values
       "legallyAllowedMass": {
         "value": 0,
         "unit": "kg"     
       },
       "technicalAllowedMass": {
         "value": 0,
         "unit": "kg"     
       }       
     }
   ]
}

Some notes:

There is a new field legal. I think a lot of the data is very specific, so I think it is easier to read if it is in its own object.
There is a new field axles that can contain multiple axle information. I looked at the provided examples for the relevant fields.
I am not sure what to do with massRoadReadyVehicle. It seems a very Dutch name, so I am not sure whether it makes much sense. It is also feels like quite 'loose', since a driver weight seems very subjective. I do assume though that it is commonly used and it needs some place in the message?

Any thoughts, ideas, questions?

FYI @woutvandenheuvel, maybe this can be discussed next time?

A truck (vrachtwagen) is in the Dutch law defined in RVV and has the following definition" vrachtauto: motorvoertuig, niet ingericht voor het vervoer van personen, waarvan de toegestane maximum massa meer bedraagt dan 3500 kg;

I believe you need to have this value to determine what is allowed because there is not another RDW field that can be used to do the same, if i am not mistaken. This is also relevant for low emission zone because being or not being a truck is often essential to determine access.

The city of Amsterdam implented this in the bereikbaarheidskaart: https://bereikbaarheid.amsterdam.nl/op-kenteken getting the required data from RDW license plate API: https://github.com/Amsterdam/bereikbaarheid-frontend/tree/main/src/api/rdw

determining if there is access to the low emission zone: https://github.com/Amsterdam/bereikbaarheid-frontend/blob/main/src/pages/ProhibitorySigns/hooks/usePermitLowEmissionZone.ts

This second script uses the inputs from the RDW API in the equations.

@robbertjanssen85 I looked at the examples and tried to come up with a format that fits with the rest of the OTM5 specification:
{
   "entityType": "vehicle",
   .. // other vehicle data
   "legal": {
     "permittenMassVehicleMass": {
       "value": 0,
       "unit": "kg"
     },
     "maxGrossCombinationWeight": {
       "value": 0,
       "unit": "kg"
     },
     "maxPayload": {
       "value": 0,
       "unit": "kg"     
     }
   },
   "axles": [
     {
       "driveAxle": true, // aangedreven as
       "liftAxle": true, // hefas
       "sequenceNr": 1,
       "placement": "G", // plaats code, not sure what would be sensible values
       "legallyAllowedMass": {
         "value": 0,
         "unit": "kg"     
       },
       "technicalAllowedMass": {
         "value": 0,
         "unit": "kg"     
       }       
     }
   ]
}
Some notes:

There is a new field legal. I think a lot of the data is very specific, so I think it is easier to read if it is in its own object.

There is a new field axles that can contain multiple axle information. I looked at the provided examples for the relevant fields.

I am not sure what to do with massRoadReadyVehicle. It seems a very Dutch name, so I am not sure whether it makes much sense. It is also feels like quite 'loose', since a driver weight seems very subjective. I do assume though that it is commonly used and it needs some place in the message?

Any thoughts, ideas, questions?

FYI @woutvandenheuvel, maybe this can be discussed next time?

Hi Bas,

seems very good to me. The massRoadReadyVehicle was a quick invention to get something close to the Dutch word, but a better translation is welcome of course :)

I dont' really understand what "drive axle true" means? Of course in tractor units there is a drive axle. Or is this to distinguish between trailer units and tractor units?

also I agree with @bbussink for including the truck parameter :)

I think I was wrong.

I found out that the API "Open-Data-RDW-Gekentekende_voertuigen" ( https://opendata.rdw.nl/api/id/m9d7-ebf2.json?kenteken=BGVG60 ) returns ""europese_voertuigcategorie":"N3""

N3 is defined here, this is also a EU standaard. source: https://www.rdw.nl/particulier/paginas/voertuigcategorieen

This variable is useable to determine directly if you are a truck without the need for the variable massRoadReadyVehicle.

I think I was wrong.

I found out that the API "Open-Data-RDW-Gekentekende_voertuigen" ( https://opendata.rdw.nl/api/id/m9d7-ebf2.json?kenteken=BGVG60 ) returns ""europese_voertuigcategorie":"N3""

N3 is defined here, this is also a EU standaard. source: https://www.rdw.nl/particulier/paginas/voertuigcategorieen

This variable is useable to determine directly if you are a truck without the need for the variable massRoadReadyVehicle.

I Used the massRoadReadyVehicle as an indication of the emptyWeight of the vehicle. emptyWeight is already available in OTM, and perhaps we should use that.

My hypothesis is: if cities want to curb/restrict heavy vehicles, they would look either at high total mass, or high axle loads. If, for instance, the high total mass cannot be gathered from an on-board device, I think it makes most sense to approximate it using [the emptyWeight of the vehicle] + [total payload] = total actual mass. However, then you would exclude the (approximated) weight of the driver and the diesel fuel. Yet still - the massaRijklaar only adds like 100 kgs to the empty weight so perhaps this is all too much detail for it to actually make sense in the real world (as diesel + driver can typically be much more for big semi-trailer combinations)

@bbussink do you know what Amsterdam and Utrecht use for ANPR-camera check if vehicles are too heavy? I assume they do licence-plate checks on emptyWeight as parameter, rather than 'massa rijklaar'?

opentripmodel / otm5-change-requests

Add static Axle and Total Mass information fields to the Vehicle endpoint #84