OTM (v5)

Download OpenAPI specification:Download

Open Trip Model

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

  • 2021-01-15: Add documentation about validation endpoints
  • 2021-01-15: Add reference to the otm5-change-requests github.
  • 2020-12-03: Fix the broken checkbox for actions when choosing the Stop action.
  • 2020-12-03: Document the license plate on a TransportEquipment (i.e. a trailer).

Introduction

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 application and services.

So, why use OTM?

After years of working in the domain of logistics and traffic data we have experienced that various parties represent the same type of data differently. This is not unexpected, since every party optimizes for their own use case, but has as a result that custom translation layers need to be made over and over again when these parties want to communicate with each other. This is a costly and time consuming experience. When parties that use the same type of data actually use the same language, you don't have to make these translations layers anymore. This makes the technological landscape simpler and results in less custom-made software.

Instead, it is better to invest in this specification once, with a one-time cost of implementation and specification, creating a better understanding between various parties.

How does OTM5 differ from OTM4?

OTM4 has existed for quite a few years now and has proven to be useful in various use cases when communicating between various parties. However, there are still areas for improvement. The lack of a clear hierarchy provides a lot of flexibility, but also makes it harder than necessary to deal with data that is inherently hierarchical. Therefore OTM5 allows you to both use a normalized approach with decoupled entities, and means to also provide (parts of) the data in a hierarchy.

Concepts

The fundamental idea behind OTM is splitting data into static data (entities) and dynamic data (actions and events) and decouple their interaction. Entities contain data that changes relatively sparingly. Think for instance about consignments, locations, and vehicles. Though properties of these entities might change, this generally occurs quite rarely and is definitely not reflected in real-time. On the other hand, how these static entities interact is more prone to change. For example, a vehicle itself remains the same height, width, and weight over its lifetime, but it can move multiple different goods every single day. Actions are used to model this interaction between entities, and events allow you to easily update them after exchanging information beforehand.

Overview

It all starts with the TransportOrder that contains a sequence of Consignments. A consignment models the need to get various related Goods from one location to another. Note that goods are actual physical entities, whereas transport orders and consignments are administrative ones. Each consignment can be part of one or multiple [Trips](#tag/Trip], where various Constraints can be put in place to ensure consignments are delivered on time, or always abide to a certain temperature during the trip. The transport orders and consignments can be associated with various Actors. Such as the shipper, the carrier, the consignee, consignor, or any legal party that is involved in the logistic operation.

The earlier mentioned trip is an entity that models visiting various Locations using a single Vehicle. Each location that is visited at a certain time is a Stop action on which multiple other actions can occur, such as Loading and Unloading of various Goods. These goods are then (optionally) HandOver from one party (an actor) to the other. If needed you can use a Move action to model a detailed description of how to travel between two locations and which Route to take, or what other actions to take on that route, such as maintenance or adding fuel to the vehicle.

During a trip a Sensor in a vehicle can give LocationUpdateEvents with coordinates of the vehicle or SensorUpdateEvents with sensor values, for example the temperature of the goods, or the speed of the vehicle. After OTM data has been shared, it can be updated using UpdateEvents with the modified data of the entities that needed to be updates. Also entities can be associated and unassociated using the AssociationCreatedEvent and AssociationRemovedEvent. This can be useful to provide or modify information of which vehicle is going to drive which trip.

Associations

Entities, actions and events are decoupled from one another. It is possible to (loosely) couple them using associations. There are three different types of associations:

  • Inline, by creating an entity within another entity directly.
  • By reference through referencing an existing entity by ID.
  • By attribute restriction through a set of restrictions on external attributes.

Thus note that the following is both correct and mean the same thing:

// A stop that is visiting a location by referencing it
{
  "id": "https://simacan.com/v5/stops/acf8b1c9-f5fa-4f55-9f98-fc1e93cbd8b2",
  "location": {
    "associationType": "reference",
    "uuid": "11c11d75-e114-4b5f-9751-b3a4afa23ecf"
  },
  ... // Many more fields
}

// A stop that is visiting a location by creating it inline
{
  "id": "https://simacan.com/v5/stops/acf8b1c9-f5fa-4f55-9f98-fc1e93cbd8b2",
  "location": {
    "associationType": "inline",
    "entity": {
        "id": "https://simacan.com/v5/locations/11c11d75-e114-4b5f-9751-b3a4afa23ecf",
        "type": "warehouse",
        "geoReference": {
          "type": "latLongPointGeoReference",
          "lat": 52.0838333,
          "lon": 5.8318803
        },
        ... // Many more fields
    }
  },
  ...
}

If no location is known and the association is thus unassociated, you can also remove the reference all together:

// A stop that is visiting a location that is still unknown
{
  "id": "https://simacan.com/v5/stops/acf8b1c9-f5fa-4f55-9f98-fc1e93cbd8b2",
  // location is still unknown, so it is not mentioned yet.
}

If the OTM entity id is unknown but we know enough of the attribute values to select the entity we want, it is possible to use an attribute restriction:

{
  "id": "https://simacan.com/v5/stops/acf8b1c9-f5fa-4f55-9f98-fc1e93cbd8b2",
  "location": {
    "associationType": "attributeRestriction",
    "restriction": {
      "externalAttributes" : {
        "customerKey": "1234"
      }
    }
  },
  ... // Many more fields
}

OTM Profiles

As can be seen from the specification, there is no single top-level element in OTM. Depending on the use case your viewpoint might change and some other entity becomes top-level. For instance, for a 'home delivery' operation the trips are the central piece of the puzzle, which each visit multiple locations to deliver goods. However for a track-and-trace operation, the consignments and its contained goods are the central object, which might be part of multiple trips before arriving at its final destination.

This approach makes OTM flexible while remaining quite simple and small. However it also means that parties using OTM might not be able to actually communicate with each other. To counter this, different use cases in OTM make use of so-called OTM profiles which are a stricter set of rules on top of OTM to ensure that specific messages have a clear intent and are unambiguous. The provided rules in a profile show you the hierarchy of the entities, but also come with a stricter set of which fields are required than the official specification. Before parties communicate in OTM they have to determine which profile they are going to abide to.

The various profiles are currently still being discussed and will be thoroughly documented with examples once finalized. See below the first profile, 'transport orders'.

Validating the 'Transport Order profile'

The first profile provided is the transport order profile. This profile is concerned with modeling goods that need to be transported from one location to potentially multiple others. However, it does not include how these goods are going to be transported (in which vehicles/trips). At the bottom of the hierarchy we have goods, physical units with dimensions, weights, etc. that need to be transported. Goods are part of a consignment, which is an administrative unit that groups the goods together. On the top we have the transport order, that is able to group multiple consignments. For example, because they are part of one assignment given by some shipper.

Below follows a description of the rules on top of the OpenAPI specification to adhere to the 'transport order' profile for each of the involved entities. We start of with the Consignment since it is the entity with the most rules.

Consignments

To check whether your messages abide to the profile you can send a consignment to:

PUT https://otm5-documentation-api.services.simacan.com/api/v5/validate/consignments

For example, if you you send invalid JSON (there is a missing curly bracket after the UUID of goods).

    {
        "id":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54",
        "goods":[
          {
            "associationType":"reference",
            "entityType":"goods",
            "uuid":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54"

        ]

      }

You will get the error message as a 400 Bad Request:

[
    "Encountered an error while parsing JSON: expected } or , got ] (line 10, column 245) at index 244"
]

If you send valid JSON, but an invalid OTM you will be notified as well:

{
    "id":"test",
    "random": "message"
}
[
    "An entity id must end with a UUID"
]

Lastly, its possible that you send valid Consignments, but not those that are expected in this profile:

{
  "id":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54",
  "actions":[
    {
      "associationType":"inline",
      "entity":{
        "id":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54",
        "actionType":"unload"
      }
    }
  ]
}

This will return the list of error messages:

{
    "errors": [
        {
            "field": "goods",
            "message": "consignments are expected to contain at least one goods item",
            "type": "missingField"
        },
        {
            "field": "actions",
            "message": "List actions has size 1 but required at least 2",
            "type": "invalidField"
        }
    ]
}

Here is an example of a valid consignment. You can also see the use of inline and reference associations.

{
  "id":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54",
  "goods":[
    {
      "uuid":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54",
      "entityType":"goods",
      "associationType":"reference"
    }
  ],
  "actions":[
    {
      "entity":{
        "id":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54",
        "location":{
          "uuid":"47bd36fa-9f15-4f5d-ab07-6eff4f11b846",
          "entityType":"location",
          "associationType":"reference"
        },
        "actionType":"load"
      },
      "associationType":"inline"
    },
    {
      "entity":{
        "id":"049ffbc8-b561-4b50-b82f-49854c4148da",
        "location":{
          "entity":{
            "id":"1662d54f-2031-4a55-b790-2b7715701640",
            "geoReference":{
              "lat":52.092995,
              "lon":5.1237933,
              "type":"latLonPointGeoReference"
            }
          },
          "associationType":"inline"
        },
        "startTime":"2021-01-17T10:00:00Z",
        "endTime":"2021-01-17T10:15:00Z",
        "actionType":"unload"
      },
      "associationType":"inline"
    }
  ]
}

The rules for consignments are as follows:

  • A consignment needs to have at least one goods to be transported.
  • A consignment should at least have one load action and one unload action.
  • Every load and unload actions needs to have a location.

TransportOrders

To check whether your messages abide to the profile you can send a transport order to:

PUT https://otm5-documentation-api.services.simacan.com/api/v5/validate/transportOrders

The error message systems works the same as for the consignments. There is only on rule for transport orders, which is that there needs to be at least one consignment.

Goods

Goods have many optional fields, and there none that are required for the transport order profile. So, as long as you send a valid Goods according to the specification below it will be accepted.

PUT https://otm5-documentation-api.services.simacan.com/api/v5/validate/goods

External attributes

ExternalAttributes are a data type that can be used to communicate data between parties that is not inherently part of OTM. This allows you to extend the data present in OTM without the need to change the specification. This usually will be administrative, or company-specific data. Note though, that if something can be modeled using just OTM entities it should be done that way.

External attributes are nothing more than a list of key-values. This is an example of what it could look like:

{
  "billedKilometers": "30km",
  "pricePerKilometer": "€0.50"
  "tags": [ "you", "can", "also", "provide", "a", "list", "of", "strings" ]
}

Lifecycles

In logistic operations it is quite common that data changes over time based on new information. This information can either be historic, in the present or model expected future events. To model this OTM introduced lifecycle phases. Lifecycle phases stay in OTM5 and can be used on actions and events. A lifecycle indicates in what phase the data was provided. It can either be:

  • requested: this pre-execution phase can be used to indicate that something is requested, but not yet confirmed by the authorizing party. This is a new lifecyle that did not exist in OTM before.

  • planned: this pre-execution phase is all about planning. Actions and events in this phase represent planned relationships, i.e. it is planned that a certain stop will be visited at 10:00. Planned actions/events typically originate from a planning system. For organizations which do not rely on planning systems this phase can be omitted.

  • projected: this phase models projected (or estimated) lifecyles. Given a series of "planned" events and some associated real-time data (i.e. traffic jams) projected actions/events can be calculated. E.g. when an event is planned to happen at 8:00, but the "actual" event happens at 8:30, all events that are planned after that delayed event can be projected 30 minutes later. Projections can also take into consideration other factors, such as traffic and weather conditions.

  • actual: this during-execution phase models the reality that is happening at present time. As opposed to planned events, actual actions/events typically originate from GPS tracking devices or traffic information systems.

  • realized: this post-execution phase can be used to view and analyze a logistic operation in retrospect. Actions and events in this phase are recorded and archived events from the actual phase.

Lifecycles can be added to both actions and events. If no lifecycle is given it will default to planned. If you want to enrich an existing action (or event) by providing data in another lifecycle you should create an action with the same UUID, since it represents the same action. Just with data in another lifecycle. If you retrieve an action or event by its UUID, it should return the action/event with the latest lifecycle, unless specified otherwise using path-parameters.

Authentication

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.

Deletes a Goods

path Parameters
UUID
required
string <uuid>

The unique ID of this Goods

Responses

Response samples

Content type
application/json
Example
{
  • "id": "e3af6932-cf6e-483d-ad58-acf947de01a5",
  • "description": "Box of bananas",
  • "remark": "Please deliver in time, we want fresh bananas",
  • "barCode": "CSE370",
  • "productType": "Fruit",
  • "packagingMaterial": "Box",
  • "constraint": {
    },
  • "type": "items"
}

Get a specific Goods by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Goods

Responses

Response samples

Content type
application/json
Example
{
  • "id": "e3af6932-cf6e-483d-ad58-acf947de01a5",
  • "description": "Box of bananas",
  • "remark": "Please deliver in time, we want fresh bananas",
  • "barCode": "CSE370",
  • "productType": "Fruit",
  • "packagingMaterial": "Box",
  • "constraint": {
    },
  • "type": "items"
}

Adds a new Goods

Request Body schema: application/json
type
required
string
id
required
string

Uniquely identifies this entity. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it. Once assigned, the URI can't be changed. See Unique Identifiers for more information.

name
string

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

externalAttributes
object

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.

creationDate
string

The creation date of this entity

description
string

A free text description of these goods.

remark
string

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

barCode
string

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

quantity
integer <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.

object

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

object

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

object

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

object

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

object

Information about the potentially dangerous properties of these goods.

productType
string

The product type of goods, for instance bananas.

packagingMaterial
string

Description of the package type f.e. pallet, europallet, drum, carton etc.

Array of any

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

Array of any (associations-actions)

Actions associated with goods, for example loading and unloading them at various locations.

any

The constraints put on these goods, for example the required temperature range or size of the vehicle.

Responses

Request samples

Content type
application/json
Example
{
  • "id": "e3af6932-cf6e-483d-ad58-acf947de01a5",
  • "description": "Box of bananas",
  • "remark": "Please deliver in time, we want fresh bananas",
  • "barCode": "CSE370",
  • "productType": "Fruit",
  • "packagingMaterial": "Box",
  • "constraint": {
    },
  • "type": "items"
}

Response samples

Content type
application/json
Example
{
  • "id": "e3af6932-cf6e-483d-ad58-acf947de01a5",
  • "description": "Box of bananas",
  • "remark": "Please deliver in time, we want fresh bananas",
  • "barCode": "CSE370",
  • "productType": "Fruit",
  • "packagingMaterial": "Box",
  • "constraint": {
    },
  • "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.

Adds a new TransportOrder

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it. Once assigned, the URI can't be changed. See Unique Identifiers for more information.

name
string

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

externalAttributes
object

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.

creationDate
string

The creation date of this entity

description
string

Actions related to this transport order, for example all loading and unloading actions of the consignments.

Array of any

All consignments belonging to this transport order.

Array of any

The actors associated with this transport order, for instance the consignor, consignee.

any

Constraints this transport order has to abide to, such as the expected delivery time windows.

Responses

Request samples

Content type
application/json
{
  • "id": "baa507c2-1d81-4092-a5c2-e80820ee4fd1",
  • "externalAttributes": {
    },
  • "description": "Transport order containing all consignments to be shipped.",
  • "consignments": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "baa507c2-1d81-4092-a5c2-e80820ee4fd1",
  • "externalAttributes": {
    },
  • "description": "Transport order containing all consignments to be shipped.",
  • "consignments": [
    ]
}

Get a specific TransportOrder by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this TransportOrder

Responses

Response samples

Content type
application/json
{
  • "id": "baa507c2-1d81-4092-a5c2-e80820ee4fd1",
  • "externalAttributes": {
    },
  • "description": "Transport order containing all consignments to be shipped.",
  • "consignments": [
    ]
}

Deletes a TransportOrder

path Parameters
UUID
required
string <uuid>

The unique ID of this TransportOrder

Responses

Response samples

Content type
application/json
{
  • "id": "baa507c2-1d81-4092-a5c2-e80820ee4fd1",
  • "externalAttributes": {
    },
  • "description": "Transport order containing all consignments to be shipped.",
  • "consignments": [
    ]
}

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.

Get a specific Trip by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Trip

Responses

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "Daily supply trip",
  • "vehicle": {
    },
  • "actions": [
    ]
}

Deletes a Trip

path Parameters
UUID
required
string <uuid>

The unique ID of this Trip

Responses

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "Daily supply trip",
  • "vehicle": {
    },
  • "actions": [
    ]
}

Adds a new Trip

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it. Once assigned, the URI can't be changed. See Unique Identifiers for more information.

name
string

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

externalAttributes
object

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.

creationDate
string

The creation date of this entity

status
string
Enum: "requested" "accepted" "modified" "cancelled"

Whether this trip is requested, accepted, modified or cancelled.

any

The Vehicle that is driving this trip.

Array of any

The actors associated with this trip, for instance the client or the executing party

Array of any (associations-actions)

All actions that are/were happening on this trip, such as stopping at certain locations and loading and unloading of consignments.

any

Constraints this trip has to abide to, such as the start and end date times in which it has to be completed.

Responses

Request samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "Daily supply trip",
  • "vehicle": {
    },
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "Daily supply trip",
  • "vehicle": {
    },
  • "actions": [
    ]
}

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).

Adds a new Vehicle

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it. Once assigned, the URI can't be changed. See Unique Identifiers for more information.

name
string

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

externalAttributes
object

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.

creationDate
string

The creation date of this entity

vehicleType
string

The type of vehicle

fuel
string

The type of fuel the vehicle runs on. For vehicle without an engine of their own, such as a trailer, you may choose not-applicable. For trailers with cooling capabilities, choose the fuel type of the cooling engine.

maxLinks
integer <int32>

Maximum number of links to other Vehicle s. Typical values are 0, 1 or 2.

Array of objects

The load capacities of the Vehicle. This can be an array of values, for several reasons:

  • The Vehicle might be split up in multiple compartments.
  • You might want to express the load capacities in different quantities. E.g. in square meters or litres as well as in number of pallets.
object

The length of the Vehicle.

object

The height of the Vehicle.

object

The width of the Vehicle.

licensePlate
string

The license plate of the vehicle.

object

The weight of the Vehicle when empty.

Array of any

There are multiple roles in which actors can be associated with a vehicle, such as the owner or the driver of the vehicle.

Responses

Request samples

Content type
application/json
{
  • "id": "0000704f-b6d0-e702-5c33-003ee53ec29b",
  • "name": "Bob's Boxtruck",
  • "vehicleType": "boxtruck",
  • "fuel": "battery",
  • "length": {
    },
  • "height": {
    },
  • "width": {
    },
  • "licensePlate": "AB-12-CD",
  • "emptyWeight": {
    }
}

Response samples

Content type
application/json
{
  • "id": "0000704f-b6d0-e702-5c33-003ee53ec29b",
  • "name": "Bob's Boxtruck",
  • "vehicleType": "boxtruck",
  • "fuel": "battery",
  • "length": {
    },
  • "height": {
    },
  • "width": {
    },
  • "licensePlate": "AB-12-CD",
  • "emptyWeight": {
    }
}

Get a specific Vehicle by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Vehicle

Responses

Response samples

Content type
application/json
{
  • "id": "0000704f-b6d0-e702-5c33-003ee53ec29b",
  • "name": "Bob's Boxtruck",
  • "vehicleType": "boxtruck",
  • "fuel": "battery",
  • "length": {
    },
  • "height": {
    },
  • "width": {
    },
  • "licensePlate": "AB-12-CD",
  • "emptyWeight": {
    }
}

Deletes a Vehicle

path Parameters
UUID
required
string <uuid>

The unique ID of this Vehicle

Responses

Response samples

Content type
application/json
{
  • "id": "0000704f-b6d0-e702-5c33-003ee53ec29b",
  • "name": "Bob's Boxtruck",
  • "vehicleType": "boxtruck",
  • "fuel": "battery",
  • "length": {
    },
  • "height": {
    },
  • "width": {
    },
  • "licensePlate": "AB-12-CD",
  • "emptyWeight": {
    }
}

Location

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

Deletes a Location

path Parameters
UUID
required
string <uuid>

The unique ID of this Location

Responses

Response samples

Content type
application/json
{
  • "id": "00000014-69a6-9702-0000-0021dca4629b",
  • "name": "Main warehouse",
  • "type": "warehouse",
  • "geoReference": {
    },
  • "administrativeReference": {
    },
  • "remark": "The cafe around the corner has the best coffee in town."
}

Adds a new Location

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it. Once assigned, the URI can't be changed. See Unique Identifiers for more information.

name
string

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

externalAttributes
object

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.

creationDate
string

The creation date of this entity

type
string
Enum: "warehouse" "store" "environmentalZone" "restrictedArea" "customer"

The type of location.

required
any

Describes a geographic reference, this is the primary way to link a Location entity to a physical, geographic location.

object (Address)
Array of any

Contact details for this Location.

remark
string

Remark about the location. Please don't misuse this field for external references, use the externalAttributes field instead.

Array of any

Locations can be associated with actors in multiple ways, though the most common one is the owner of the location, either a person or a legal entity.

Array of any (associations-actions)

Multiple actions can be associated with a location, such as a Last-Mile guidance that should be followed to reach that location.

any

In the context of a Location, access to the location is only allowed if the given constraint applies.

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

Responses

Request samples

Content type
application/json
{
  • "id": "00000014-69a6-9702-0000-0021dca4629b",
  • "name": "Main warehouse",
  • "type": "warehouse",
  • "geoReference": {
    },
  • "administrativeReference": {
    },
  • "remark": "The cafe around the corner has the best coffee in town."
}

Response samples

Content type
application/json
{
  • "id": "00000014-69a6-9702-0000-0021dca4629b",
  • "name": "Main warehouse",
  • "type": "warehouse",
  • "geoReference": {
    },
  • "administrativeReference": {
    },
  • "remark": "The cafe around the corner has the best coffee in town."
}

Get a specific Location by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Location

Responses

Response samples

Content type
application/json
{
  • "id": "00000014-69a6-9702-0000-0021dca4629b",
  • "name": "Main warehouse",
  • "type": "warehouse",
  • "geoReference": {
    },
  • "administrativeReference": {
    },
  • "remark": "The cafe around the corner has the best coffee in town."
}

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.

Adds a new Sensor

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it. Once assigned, the URI can't be changed. See Unique Identifiers for more information.

name
string

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

externalAttributes
object

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.

creationDate
string

The creation date of this entity

placement
string

Sometimes more than one sensor can be associated with a single entity. This is the case e.g. in cooled trailers that are divided into compartments with different temperatures, where each compartment has its own sensor. The placement member can be used to identify where a sensor is placed. Parties using OpenTripModel to exchange sensor data may wish to agree on a standardized naming, but this is too specific to describe in the standard.

sensorType
string

The type of sensor.

Array of any

The actors associated with this sensor, for instance the owners, the producers or the users of this sensor.

any

In the context of a Sensor, only sensorValueConstraints really make sense. You can use such a constraint to model a sensor of which the measured value must be within certain bounds at all times.

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

Responses

Request samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "My temperature sensor",
  • "placement": "Trailer main compartment",
  • "sensorType": "temperature"
}

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "My temperature sensor",
  • "placement": "Trailer main compartment",
  • "sensorType": "temperature"
}

Get a specific Sensor by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Sensor

Responses

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "My temperature sensor",
  • "placement": "Trailer main compartment",
  • "sensorType": "temperature"
}

Deletes a Sensor

path Parameters
UUID
required
string <uuid>

The unique ID of this Sensor

Responses

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "My temperature sensor",
  • "placement": "Trailer main compartment",
  • "sensorType": "temperature"
}

Route

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

Get a specific Route by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Route

Responses

Response samples

Content type
application/json
{
  • "id": "4a8061fb-b89a-44d5-97c9-cf4887c75e85",
  • "name": "An example route using coordinates to indicate how to drive.",
  • "geoReferences": {
    }
}

Adds a new Route

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it. Once assigned, the URI can't be changed. See Unique Identifiers for more information.

name
string

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

externalAttributes
object

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.

creationDate
string

The creation date of this entity

required
any

Geographic representation of this route.

Array of any

Actors associated with this route, for instance the Company that requires this route as a Last-Mile guidance.

Array of any (associations-actions)

All the actions that need to be executed on this route.

any

Constraints of using this route, for instance it might only be used by vehicles with below a certain weight.

Responses

Request samples

Content type
application/json
{
  • "id": "fbe42081-1058-47c3-a43d-5135971fabff",
  • "name": "An example route using coordinates to indicate how to drive.",
  • "geoReferences": {
    }
}

Response samples

Content type
application/json
{
  • "id": "fbe42081-1058-47c3-a43d-5135971fabff",
  • "name": "An example route using coordinates to indicate how to drive.",
  • "geoReferences": {
    }
}

Deletes a Route

path Parameters
UUID
required
string <uuid>

The unique ID of this Route

Responses

Response samples

Content type
application/json
{
  • "id": "0670d5e6-707c-4c35-b9b2-5a6d925f8fc0",
  • "name": "An example route using coordinates to indicate how to drive.",
  • "geoReferences": {
    }
}

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.

Adds a new Actor

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it. Once assigned, the URI can't be changed. See Unique Identifiers for more information.

name
string

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

externalAttributes
object

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.

creationDate
string

The creation date of this entity

Array of any

Contact details for this Actor.

Array of any

Locations for this Actor.

Responses

Request samples

Content type
application/json
{
  • "id": "00031877-2307-3103-000f-9794dd120862",
  • "name": "Logistics manager",
  • "contactDetails": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "00031877-2307-3103-000f-9794dd120862",
  • "name": "Logistics manager",
  • "contactDetails": [
    ]
}

Deletes a Actor

path Parameters
UUID
required
string <uuid>

The unique ID of this Actor

Responses

Response samples

Content type
application/json
{
  • "id": "00031877-2307-3103-000f-9794dd120862",
  • "name": "Logistics manager",
  • "contactDetails": [
    ]
}

Get a specific Actor by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Actor

Responses

Response samples

Content type
application/json
{
  • "id": "00031877-2307-3103-000f-9794dd120862",
  • "name": "Logistics manager",
  • "contactDetails": [
    ]
}

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.

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

Get a specific Constraint by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Constraint

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "value": {
    }
}

Adds a new Constraint

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it. Once assigned, the URI can't be changed. See Unique Identifiers for more information.

name
string

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

externalAttributes
object

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.

creationDate
string

The creation date of this entity

required
any (constraintValue)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "value": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "value": {
    }
}

Deletes a Constraint

path Parameters
UUID
required
string <uuid>

The unique ID of this Constraint

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "value": {
    }
}

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.

Get a specific Consignment by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Consignment

Responses

Response samples

Content type
application/json
{
  • "id": "047cfa4d-fd8b-47ba-b8e9-87067294d2fa",
  • "externalAttributes": {
    },
  • "description": "Shipment for mr. X",
  • "status": "requested",
  • "type": "HumanFood",
  • "goods": [
    ],
  • "remark": "Please step 1.5m away after ringing the door bell",
  • "actors": [
    ],
  • "actions": [
    ],
  • "constraint": {
    }
}

Adds a new Consignment

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it. Once assigned, the URI can't be changed. See Unique Identifiers for more information.

name
string

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

externalAttributes
object

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.

creationDate
string

The creation date of this entity

description
string

General description of consignment in Free text. e.g 20 europallets fruit.

status
string
Enum: "requested" "accepted" "modified" "cancelled"

Whether this consignment is requested, accepted, modified or cancelled.

type
string

Free text to describe type of consignment e.g. FTL, Full Truck Load, LTL Less than Truck Load, bulk, reverse logistics orders, pick up order, delivery order.

Array of any

The various goods that need to be transported, together they are part of this consignment.

remark
string

Remark concerning the complete consignment, to be printed on the transport document.

Array of any

The actors associated with this consignment, for instance the shipper and carrier.

Array of any (associations-actions)

General description of actions related to the consignment f.e. loading, unloading, hand over, drop of.

any

Constraints this consignment has to abide to, such special equipment (tail lift, truck mounted forklift), special vehicle, special instructions related to consignor and consignee.

Responses

Request samples

Content type
application/json
{
  • "id": "047cfa4d-fd8b-47ba-b8e9-87067294d2fa",
  • "externalAttributes": {
    },
  • "description": "Shipment for mr. X",
  • "status": "requested",
  • "type": "HumanFood",
  • "goods": [
    ],
  • "remark": "Please step 1.5m away after ringing the door bell",
  • "actors": [
    ],
  • "actions": [
    ],
  • "constraint": {
    }
}

Response samples

Content type
application/json
{
  • "id": "047cfa4d-fd8b-47ba-b8e9-87067294d2fa",
  • "externalAttributes": {
    },
  • "description": "Shipment for mr. X",
  • "status": "requested",
  • "type": "HumanFood",
  • "goods": [
    ],
  • "remark": "Please step 1.5m away after ringing the door bell",
  • "actors": [
    ],
  • "actions": [
    ],
  • "constraint": {
    }
}

Deletes a Consignment

path Parameters
UUID
required
string <uuid>

The unique ID of this Consignment

Responses

Response samples

Content type
application/json
{
  • "id": "047cfa4d-fd8b-47ba-b8e9-87067294d2fa",
  • "externalAttributes": {
    },
  • "description": "Shipment for mr. X",
  • "status": "requested",
  • "type": "HumanFood",
  • "goods": [
    ],
  • "remark": "Please step 1.5m away after ringing the door bell",
  • "actors": [
    ],
  • "actions": [
    ],
  • "constraint": {
    }
}

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.

  • 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.

Deletes a Event

path Parameters
UUID
required
string <uuid>

The unique ID of this Event

Responses

Response samples

Content type
application/json
Example
{
  • "entityType": "associationCreatedEvent",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "eventType": "string",
  • "entity1": {
    },
  • "entity2": {
    }
}

Adds a new Event

Request Body schema: application/json
entityType
required
string
id
required
string

Uniquely identifies this entity. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it. Once assigned, the URI can't be changed. See Unique Identifiers for more information.

name
string

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

externalAttributes
object

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.

creationDate
string

The creation date of this entity

lifecycle
string
Enum: "requested" "planned" "projected" "actual" "realized"

A lifecycle models when the data in the action is taking place. You can provide the same action in multiple lifecycles to model how it changes over time. For example the planned and realized time of an action taking place can differ because of unforseen circumstances (such as traffic jams).

eventType
required
string
required
any (entity1)
required
any (entity2)

Responses

Request samples

Content type
application/json
Example
{
  • "entityType": "associationCreatedEvent",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "eventType": "string",
  • "entity1": {
    },
  • "entity2": {
    }
}

Response samples

Content type
application/json
Example
{
  • "entityType": "associationCreatedEvent",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "eventType": "string",
  • "entity1": {
    },
  • "entity2": {
    }
}

Get a specific Event by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Event

Responses

Response samples

Content type
application/json
Example
{
  • "entityType": "associationCreatedEvent",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "eventType": "string",
  • "entity1": {
    },
  • "entity2": {
    }
}

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 GenericAction for whenever any of the above actions cannot model the situation appropriately.

Deletes a Action

path Parameters
UUID
required
string <uuid>

The unique ID of this Action

Responses

Response samples

Content type
application/json
Example
{
  • "actionType": "load",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "remark": "string",
  • "stop": {
    },
  • "consignment": {
    },
  • "location": {
    },
  • "startTime": "string",
  • "endTime": "string",
  • "actions": [
    ],
  • "constraint": {
    }
}

Adds a new Action

Request Body schema: application/json
actionType
required
string
id
required
string

Uniquely identifies this entity. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it. Once assigned, the URI can't be changed. See Unique Identifiers for more information.

name
string

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

externalAttributes
object

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.

creationDate
string

The creation date of this entity

lifecycle
string
Enum: "requested" "planned" "projected" "actual" "realized"

A lifecycle models when the data in the action is taking place. You can provide the same action in multiple lifecycles to model how it changes over time. For example the planned and realized time of an action taking place can differ because of unforseen circumstances (such as traffic jams).

remark
string

Free text field for adding an on remark on this action.

any

The stop that is associated with this action.

any

The consignment that is the subject of this action.

any

The location at which this action is taking place.

startTime
string

The time at which the actions starts in ISO format.

endTime
string

The time at which the action is completed in ISO format.

Array of any (associations-actions)
any

The constraints this action abides to, such as start and end time windows.

Responses

Request samples

Content type
application/json
Example
{
  • "actionType": "load",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "remark": "string",
  • "stop": {
    },
  • "consignment": {
    },
  • "location": {
    },
  • "startTime": "string",
  • "endTime": "string",
  • "actions": [
    ],
  • "constraint": {
    }
}

Response samples

Content type
application/json
Example
{
  • "actionType": "load",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "remark": "string",
  • "stop": {
    },
  • "consignment": {