Goods

Open Trip Model (v5.7)

Why OTM?

In this day and age more and more information about logistics and traffic is shared over the Internet between various parties. To make this communication easier the Open Trip Model specification was created. It is a lightweight data model used to exchange real-time logistic trip data on the web, and to make it easier for shippers, carriers, software vendors, OEMs, and truck manufacturers to create new multi-brand applications and services.

To learn more about the what, the why and the how see the OTM documentation website.

Changelog

Found any bugs on this page? Or have any feature requests for OTM? Create a new ticket on the OTM5 change requests Github page

Version 5.7 (released on 2025-05-23)

  • Fix broken link to goods packaging type codes. See 87.
  • Fix inconsistent use of plural name 'geoReferences' for non array property in route definitions. Add new property 'geoReference' and deprecate 'geoReferences'. First one is now required. See 86.
  • Add enums for location types 'fuelStation', 'serviceStation' and 'other'. Add new property 'otherLocationType' to specify the location type in case of 'other'. See 73.
  • Add eight new action result reasons, including 'deliveredElsewhere', 'deliveredToWrongReceiver' and 'other'. In case of 'other' the result reason can be provided as free text in the existing remark property. See 89.
  • Add distance property in move action. This can be provided by means of value and unit (e.g. 120 km) See 90
  • Add two specializations of actor, i.e. 'peron' and 'company'. Each with an additional set of properties. See 100

Version 5.6 (released on 2023-11-17)

  • Add loading and unloading consignment in and from transport equipment. See 63.
  • Add enforceability of a constraint. See 75.
  • Add recurring date times & durations on actions & events. See 75.
  • Add sub-locations as optional field on a location. See 77.
  • Add owner as a new type of actor role. See 78.
  • Add routeEntityConstraint and deprecate routeConstraint. See 80.

Version 5.5 (released on 2023-02-07)

  • Explain when to use Consignment vs Goods constraints. See 42.
  • Make fuel on vehicle an enum instead of a free string. See 51.
  • Add emissionStandardConstraint as a possible constraint. See 52.
  • Add transportOrder as a field on Consignment to enable the two-way relationship. See 59.
  • Add eori as a possible contact detail option. See 60.
  • Add valueBoundConstraint as a possible constraint. See 61.
  • Add refuel as a possible action. See 62.
  • Add accessConstraint as possible constraint. See 69.

Version 5.4 (released on 2022-05-09)

  • _Add a TransportEquipmentConstraint. See 46.
  • _Add averageFuelConsumption to vehicle. See 48.
  • _Add fuel consumption and emission events. See 49.
  • _Add contextEvents on entities. See 49.
  • _Add sequenceNr to all action types. See 50.
  • _Add cancelled on action results and receiverAbsent as 'reason' type. See 53.
  • _Add actors to all event types. See 55.
  • _Add description to all constraint types. See 56.

Version 5.3 (released on 2021-12-16)

  • Support 204 (No Content) for delete requests. See 23.
  • Add classification lines to goods. See 26.
  • Add a result to actions. See 30.
  • Extend ADR with points and transport category. See 31.
  • Support relatedConsignments in consignments. See 32.
  • Support UNCode and GLN in locations. See 36.
  • Support temperatureConstraint as a possible constraint type. See 37.
  • Add some references to existing code lists. See 27.
    • Using ISO country codes in the country field in addresses.
    • Using ISO currency codes in 'value-with-unit' fields.
    • Using the metric system as recommend and default system for dealing with mass, velocity, weight and sizes.
    • Using the package material codes from the GS1 standard.

Version 5.2 (released on 2021-09-09)

  • _Add transportEquipmentSubType for example to indicate what type of pallets you use. See 19.
  • _Add timeWindowConstraint to replace startDateTimeConstraint and endDateTimeConstraint. See 6.
  • _Add operationalBase as a location type. See 22.
  • _Add more actor role types. See 20.
  • _Add new break and wait actions. See 17.
  • _Allow for server side UUID generation. See 16.

Version 5.1 (released on 2021-06-01)

  • Add an optional emission to Vehicle. See 13.
  • Add an optional transportMode to Trip and Move. See 12.
  • Add optional grossWeight to Goods. See 11.
  • AddmobilePhone as contact detail option. See 5.
  • Add an optional lastModified field to each entity. See 2.
  • Add an optional language to contact details. See 9.
  • Add a new entity Document to deal with information about files that can be shared. See 7.
  • Add new statuses to Trip and Consignment. See 4.
  • Add an optional sensors association to vehicle. See 2.

Version 5.0 (only documentation changes)

  • Add documentation about validation endpoints.
  • Add reference to the otm5-change-requests github.
  • Fix the broken checkbox for actions when choosing the Stop action.
  • Document the license plate on a TransportEquipment (i.e. a trailer).
Download OpenAPI description
otm.json
otm.yaml
Languages
Servers
Mock server

https://otm-api-spec.redocly.app/_mock/api/5.7/otm/

https://example.com/

Vehicle

A Vehicle is a means to transport consignments from one location to potentially multiple other locations. There are various types of vehicles, each with their own unique properties like size, dimensions, fuel type and means of tranport (by air, on land, over sea).

Operations

Route

A route models the path going from one location to at least one other location.

Operations

Sensor

A sensor is a device that is able to measure a quantity in a certain unit, such as measuring the speed in km/h.

Operations

Location

Object describing a geographic location. A location can either be a point or an area.

Operations

Actor

An Actor models a legal entity. A legal entity is an individual, company, or organization that has legal rights and obligations. The use of Actors is optional, and is not necessary to use OpenTripModel. Actors can be used e.g. to group all locations that belong to an organisation, or to address an OpenTripModel message to a specific person or organisation.

Operations

Consignment

A consignment is a description of an identifiable collection of goods items to be transported between the consignor and the consignee. This information may be defined within a transport contract.

Operations

Trip

A Trip is an aggregate entity that combines various entities to model visiting various locations, potentially doing one or multiple actions on each location, such as loading or unloading consignments. It is optionally coupled to a Vehicle that is/was driving this trip.

Operations

Event

Events - like actions - model dynamic entities that couple various static entities at a certain moment in time. Events are used for either real-time updates, or updates on earlier provided data. Notice that in both event types these are updates on earlier provided data, whereas actions are usually used together with the entities they dynamically couple.

There are various kinds of events that fall into the two earlier mentioned kinds.

Real-time updates:

  • The LocationUpdateEvent that provides location data received from some GPS.
  • The SensorUpdateEvent that provides sensor value updates (such as temperature or speed measurements) received from a sensor.
  • The StartMovingEvent, StopMovingEvent, StartEngineEvent, StopEngineEvent that indicate events provided by Fleet Management Systems.

Both real-time and projected/realized events

  • The EmissionEvent that contains information about how much emission has been produced during a move / on a trip / per consignment. Can be provided as an actual value, projected based on some calculation, or realized as measured by some sensor.
  • The FuelConsumedEvent that contains information about how much fuel was consumed during a move / on a trip / per consignment. Can be provided as an actual value, projected based on some calculation, or realized as measured by some sensor.

Updates on earlier provided data:

  • The UpdateEvent that is used to update an earlier provided entity with new information. Note that only the changed data has to be provided.
  • The AssociationCreatedEvent and AssociationRemovedEvent that allow for static entities to be coupled after the fact. Such as coupling a Vehicle to a Trip.
Operations

Action

Actions are dynamic entities that are able to couple together various static entities at a certain moment in time. For instance a Load action couples together a Consignment and a Vehicle at the moment the Loading happens.

There are various types of Actions:

  • The Stop that models visiting a certain location at a certain time and potentially doing several other actions at that location.
  • The Load action, that models loading in one or multiple Consignments into a vehicle or some sort of container.
  • The Unload action, that models unloading one or multiple Consignments from a vehicle or some other sort of container.
  • The HandOver that indicates transferring a consignment from one Actor to another.
  • The Move that models moving between two or more locations, potentially with detailed route information on how to move between these locations.
  • The AttachTransportEquipment that allows you to attach some equipment to the associated vehicle. Note that you can both load/unload and attach/detach TransportEquipments. For instance loading a container on a ship, or attach a trailer to a truck. So choose the one that is most appropriate.
  • The DetachTransportEquipment that allows you to detach some previously attached equipment from the associated vehicle.
  • The Break action that models a mandatory resting period for the driver of the vehicle. During this period the driver is prohibited from doing any driving activities or other work.
  • The Wait action that models waiting at a particular location during the trip. This can be due to various circumstances such as waiting for the vehicle to be transported by a ferry or train. Or because of waiting at frontiers or docks (e.g. the dock of the loading/unload location is occupied) or traffic prohibitions. The driver is allowed to leave the vehicle during this period. An important aspect distinguishing this from the break action is that waiting times can be shortened because of changing circumstances. For example, if the original waiting time was expected to be 15 minutes because of an occupied dock, but the driver is 10 minutes late, the waiting time can be shortened to 5 minutes until the dock is free.
  • The GenericAction for whenever any of the above actions cannot model the situation appropriately.
Operations

Goods

Goods are the items to be transported as part of a consignment. Goods can be divided into two sub-types of goods, depending on the use case and the level of detail. Goods either consists of items, describing the actual goods to be transported. Or a transport equipment, which is equipment used to carry the actual goods to be transported. Transport equipment is (usually) a means to an end, not something that needs to be transported on itself, such as pallets.

Note that goods can either be or contain dangerous goods. OTM uses the official specification of ADR to describe in what manner and how dangerous those goods are. The used descriptions in the OTM documentation are extracted from document ADR2021_Vol1e_0.pdf. The official documentation is always leading and should be consulted.

Operations

Get a specific Goods by its UUID

Request

Path
UUIDstring(uuid)required

The unique UUID of this Goods

curl -i -X GET \
  'https://otm-api-spec.redocly.app/_mock/api/5.7/otm/api/v5/goods/{UUID}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Returned the entity with the provided UUID

Bodyapplication/json
typestringrequired
Value"items"
Example: "items"
Discriminator
idstring

Uniquely identifies this entity. A URI can be assigned by the client to indicate where more information can be retrieved. Note that every entity always has a unique EntityId. However since, OTM5.2 it is not required to send it in the request. One can be generated for you by the server.

Example: "903807df-ee62-47aa-bf8e-7efd747618ce"
namestring

Name of the entity. For display purposes and search only.

creationDatestring

The creation date of this entity.

lastModifiedstring

The last modified date of this entity. If none is given the creation date is used instead.

contextEventsArray of any(events)

The context events provides some optional information about the events that can provide additional information on the current state of this entity.

For example: your system might send ETA information for the arrival of a vehicle on a location. To make it clear what caused this ETA to be updated, we can include some information about what caused this ETA update by including an event as context. If your ETA update was caused by a location update, this event can be included as context. If the ETA was caused by a traffic accident on the route of the vehicle, you can include that event in the context.

externalAttributesobject

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

descriptionstring

A free text description of these goods.

Example: "Box of bananas"
remarkstring

Remark belonging to the goods that need to be transported. For example a delivery note.

Example: "Please deliver in time, we want fresh bananas"
barCodestring

A barcode present on the (packaging of the) goods that uniquely identifies these goods.

Example: "CSE370"
quantityinteger(int32)

A quantity determines how many of a certain good you have. Note that all other measurements are measured for a single product, not for the total of products.

weightobject

The net weight of a 'single' good, the total weight can be calculated by using the quantity and multiplying it with this weight.

grossWeightobject

The gross weight of a 'single' good, the total weight can be calculated by using the quantity and multiplying it with this weight.

widthobject

The width of a 'single' good, the total width can be calculated by using the quantity and multiplying it with this width.

heightobject

The height of a 'single' good, the total height can be calculated by using the quantity and multiplying it with this height.

lengthobject

The length of a 'single' good, the total length can be calculated by using the quantity and multiplying it with this length.

adrobject

Information about the potentially dangerous properties of these goods.

productTypestring

The product type of goods, for instance bananas.

Example: "Fruit"
packagingMaterialstring

Description of the package type. Use as described by the GS1 standard.

Example: "Box"
classificationLinesArray of objects

Product classification information often required at customs. A single product can contain multiple classification lines. For example whenever the product consists of multiple components that can each be classified. The most important information in the classification lines is often the HS code.

actorsArray of any

All parties associated with these goods, for example the consignor and consignee.

constraintany

The constraints put on these goods, most notably the required temperature range or size of the vehicle. You should only put constraints on the goods themselves when it is important to distinguish goods within one consignment with different requirements. Individual constraints on a goods are powerful, but also complicate the solution. When possible, prefer to put the constraint on the consignment of the goods.

Example: {"entity":{"value":{"and":[{"startTime":"2021-06-23T10:00:00Z","endTime":"2021-06-23T13:00:00Z","description":"alert-threshold","type":"timeWindowConstraint"},{"constraintType":"maximum","maximum":{"value":5,"unit":"C"},"type":"temperatureConstraint"},{"or":[{"fuelTypes":["battery"],"type":"fuelTypeConstraint"},{"fuelTypes":["biodiesel"],"type":"fuelTypeConstraint"},{"minimum":"euro5","type":"emissionStandardConstraint"}],"type":"orConstraint"}],"type":"andConstraint"}},"associationType":"inline"}
Response
application/json
{
  "id": "903807df-ee62-47aa-bf8e-7efd747618ce",
  "description": "Box of bananas",
  "remark": "Please deliver in time, we want fresh bananas",
  "barCode": "CSE370",
  "productType": "Fruit",
  "packagingMaterial": "Box",
  "constraint": {
    "entity": { … },
    "associationType": "inline"
  },
  "type": "items"
}

Deletes a Goods

Request

Path
UUIDstring(uuid)required

The unique UUID of the Goods to be deleted

curl -i -X DELETE \
  'https://otm-api-spec.redocly.app/_mock/api/5.7/otm/api/v5/goods/{UUID}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Deleted goods with the provided UUID

Response
No content

Adds a new Goods

Request

Bodyapplication/json
typestringrequired
Value"items"
Example: "items"
Discriminator
idstring

Uniquely identifies this entity. A URI can be assigned by the client to indicate where more information can be retrieved. Note that every entity always has a unique EntityId. However since, OTM5.2 it is not required to send it in the request. One can be generated for you by the server.

Example: "903807df-ee62-47aa-bf8e-7efd747618ce"
namestring

Name of the entity. For display purposes and search only.

creationDatestring

The creation date of this entity.

lastModifiedstring

The last modified date of this entity. If none is given the creation date is used instead.

contextEventsArray of any(events)

The context events provides some optional information about the events that can provide additional information on the current state of this entity.

For example: your system might send ETA information for the arrival of a vehicle on a location. To make it clear what caused this ETA to be updated, we can include some information about what caused this ETA update by including an event as context. If your ETA update was caused by a location update, this event can be included as context. If the ETA was caused by a traffic accident on the route of the vehicle, you can include that event in the context.

externalAttributesobject

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

descriptionstring

A free text description of these goods.

Example: "Box of bananas"
remarkstring

Remark belonging to the goods that need to be transported. For example a delivery note.

Example: "Please deliver in time, we want fresh bananas"
barCodestring

A barcode present on the (packaging of the) goods that uniquely identifies these goods.

Example: "CSE370"
quantityinteger(int32)

A quantity determines how many of a certain good you have. Note that all other measurements are measured for a single product, not for the total of products.

weightobject

The net weight of a 'single' good, the total weight can be calculated by using the quantity and multiplying it with this weight.

grossWeightobject

The gross weight of a 'single' good, the total weight can be calculated by using the quantity and multiplying it with this weight.

widthobject

The width of a 'single' good, the total width can be calculated by using the quantity and multiplying it with this width.

heightobject

The height of a 'single' good, the total height can be calculated by using the quantity and multiplying it with this height.

lengthobject

The length of a 'single' good, the total length can be calculated by using the quantity and multiplying it with this length.

adrobject

Information about the potentially dangerous properties of these goods.

productTypestring

The product type of goods, for instance bananas.

Example: "Fruit"
packagingMaterialstring

Description of the package type. Use as described by the GS1 standard.

Example: "Box"
classificationLinesArray of objects

Product classification information often required at customs. A single product can contain multiple classification lines. For example whenever the product consists of multiple components that can each be classified. The most important information in the classification lines is often the HS code.

actorsArray of any

All parties associated with these goods, for example the consignor and consignee.

constraintany

The constraints put on these goods, most notably the required temperature range or size of the vehicle. You should only put constraints on the goods themselves when it is important to distinguish goods within one consignment with different requirements. Individual constraints on a goods are powerful, but also complicate the solution. When possible, prefer to put the constraint on the consignment of the goods.

Example: {"entity":{"value":{"and":[{"startTime":"2021-06-23T10:00:00Z","endTime":"2021-06-23T13:00:00Z","description":"alert-threshold","type":"timeWindowConstraint"},{"constraintType":"maximum","maximum":{"value":5,"unit":"C"},"type":"temperatureConstraint"},{"or":[{"fuelTypes":["battery"],"type":"fuelTypeConstraint"},{"fuelTypes":["biodiesel"],"type":"fuelTypeConstraint"},{"minimum":"euro5","type":"emissionStandardConstraint"}],"type":"orConstraint"}],"type":"andConstraint"}},"associationType":"inline"}
curl -i -X PUT \
  https://otm-api-spec.redocly.app/_mock/api/5.7/otm/api/v5/goods \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "903807df-ee62-47aa-bf8e-7efd747618ce",
    "description": "Box of bananas",
    "remark": "Please deliver in time, we want fresh bananas",
    "barCode": "CSE370",
    "productType": "Fruit",
    "packagingMaterial": "Box",
    "constraint": {
      "entity": {
        "value": {
          "and": [
            {
              "startTime": "2021-06-23T10:00:00Z",
              "endTime": "2021-06-23T13:00:00Z",
              "description": "alert-threshold",
              "type": "timeWindowConstraint"
            },
            {
              "constraintType": "maximum",
              "maximum": {
                "value": 5,
                "unit": "C"
              },
              "type": "temperatureConstraint"
            },
            {
              "or": [
                {
                  "fuelTypes": [
                    "battery"
                  ],
                  "type": "fuelTypeConstraint"
                },
                {
                  "fuelTypes": [
                    "biodiesel"
                  ],
                  "type": "fuelTypeConstraint"
                },
                {
                  "minimum": "euro5",
                  "type": "emissionStandardConstraint"
                }
              ],
              "type": "orConstraint"
            }
          ],
          "type": "andConstraint"
        }
      },
      "associationType": "inline"
    },
    "type": "items"
  }'

Responses

The same entity

Bodyapplication/json
typestringrequired
Value"items"
Example: "items"
Discriminator
idstring

Uniquely identifies this entity. A URI can be assigned by the client to indicate where more information can be retrieved. Note that every entity always has a unique EntityId. However since, OTM5.2 it is not required to send it in the request. One can be generated for you by the server.

Example: "903807df-ee62-47aa-bf8e-7efd747618ce"
namestring

Name of the entity. For display purposes and search only.

creationDatestring

The creation date of this entity.

lastModifiedstring

The last modified date of this entity. If none is given the creation date is used instead.

contextEventsArray of any(events)

The context events provides some optional information about the events that can provide additional information on the current state of this entity.

For example: your system might send ETA information for the arrival of a vehicle on a location. To make it clear what caused this ETA to be updated, we can include some information about what caused this ETA update by including an event as context. If your ETA update was caused by a location update, this event can be included as context. If the ETA was caused by a traffic accident on the route of the vehicle, you can include that event in the context.

externalAttributesobject

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

descriptionstring

A free text description of these goods.

Example: "Box of bananas"
remarkstring

Remark belonging to the goods that need to be transported. For example a delivery note.

Example: "Please deliver in time, we want fresh bananas"
barCodestring

A barcode present on the (packaging of the) goods that uniquely identifies these goods.

Example: "CSE370"
quantityinteger(int32)

A quantity determines how many of a certain good you have. Note that all other measurements are measured for a single product, not for the total of products.

weightobject

The net weight of a 'single' good, the total weight can be calculated by using the quantity and multiplying it with this weight.

grossWeightobject

The gross weight of a 'single' good, the total weight can be calculated by using the quantity and multiplying it with this weight.

widthobject

The width of a 'single' good, the total width can be calculated by using the quantity and multiplying it with this width.

heightobject

The height of a 'single' good, the total height can be calculated by using the quantity and multiplying it with this height.

lengthobject

The length of a 'single' good, the total length can be calculated by using the quantity and multiplying it with this length.

adrobject

Information about the potentially dangerous properties of these goods.

productTypestring

The product type of goods, for instance bananas.

Example: "Fruit"
packagingMaterialstring

Description of the package type. Use as described by the GS1 standard.

Example: "Box"
classificationLinesArray of objects

Product classification information often required at customs. A single product can contain multiple classification lines. For example whenever the product consists of multiple components that can each be classified. The most important information in the classification lines is often the HS code.

actorsArray of any

All parties associated with these goods, for example the consignor and consignee.

constraintany

The constraints put on these goods, most notably the required temperature range or size of the vehicle. You should only put constraints on the goods themselves when it is important to distinguish goods within one consignment with different requirements. Individual constraints on a goods are powerful, but also complicate the solution. When possible, prefer to put the constraint on the consignment of the goods.

Example: {"entity":{"value":{"and":[{"startTime":"2021-06-23T10:00:00Z","endTime":"2021-06-23T13:00:00Z","description":"alert-threshold","type":"timeWindowConstraint"},{"constraintType":"maximum","maximum":{"value":5,"unit":"C"},"type":"temperatureConstraint"},{"or":[{"fuelTypes":["battery"],"type":"fuelTypeConstraint"},{"fuelTypes":["biodiesel"],"type":"fuelTypeConstraint"},{"minimum":"euro5","type":"emissionStandardConstraint"}],"type":"orConstraint"}],"type":"andConstraint"}},"associationType":"inline"}
Response
application/json
{
  "id": "903807df-ee62-47aa-bf8e-7efd747618ce",
  "description": "Box of bananas",
  "remark": "Please deliver in time, we want fresh bananas",
  "barCode": "CSE370",
  "productType": "Fruit",
  "packagingMaterial": "Box",
  "constraint": {
    "entity": { … },
    "associationType": "inline"
  },
  "type": "items"
}

TransportOrder

The TransportOrder is the top-level entity to model a group of related consignments that might be transported separately, but need to be administered together. For consistency, even if there is only one consignment, it is still required to use a transport order.

Operations

Document

In many logistic operations documents are an important part of the data flow. Documents can serve multiple purposes, such as proving some package was delivered with help of a photo, or some scanned document that establishes that the transferred goods are accepted on handover. Documents in OTM come in two flavors, either you provide the content of the document directly as a base64 encoded string, or you provide a link to the document where it can be accessed online.

Operations

Constraint

Constraints can do different things, depending on the context they're used in:

  • In the context of a Location, access to the location is only allowed if the given constraint applies.
  • In the context of a Trip, constraints can be used to define constraints that have to be met during the trip, e.g. if the temperature in a refrigerated trailer has to stay below a given maximum during the trip.
  • In the context of a Shipment, constraints can be used to e.g. define minimum or maximum temperatures for shipments, or date time constraints for delivery.

Since OTM5.2 the timeWindowConstraint is supported which allows you to give (optionally) both the start and end time of the window between which something needs to occur. This replaces the old style where you had to use an and constraint in combination with the startDateTimeConstraint and endDateTimeConstraint. Since the new solution is shorter and simpler the startDateTimeConstraint and endDateTimeConstraint are deprecated.

Note that constraints can be nested and combined using the andConstraint, orConstraint and notConstraint.

Operations