Skip to main content

MQTT API

Version 2.0

The MQTT integration publishes data related to an organization. While the HTTP API is good for fetching historical data and current state, the MQTT API is more suited if you want to immediately act on a piece of information as it happens.

Connection information​

  • MQTT Version: 3.1.1
  • Host: mqtt.bintel.se
  • Port: 8883
  • SSL/TLS: Yes, TLS v1.2 or TLS v1.3
  • Certificate: CA signed server certificate

Your application should be implemented to handle short disruptions in the service. The broker might restart without prior notice for short periods to apply updates or to reload certificates. To handle this it is recommended that your application has an auto-reconnect feature.

If you have clean session set to false the broker will persist your session and store queued messages on your QoS 1 and 2 subscriptions for up to 24h.

Authentication​

  • Username: [Organization ID]
  • Password: [API Key]
  • Client ID: [Organization ID]:*

Your Organization ID can be found at insights.bintel.se/settings, this is also where you manage your API Keys.

The MQTT client ID must begin with the Organization ID followed by :. This prevents different users from interfering with each other by using the same MQTT client id.

Subscribing​

Messages will be sent on a topic with the following base format:

v2/[Organization ID]/

If you want to subscribe to all data for your organization you can subscribe to

v2/[Organization ID]/#

This is the most generic topic a client is allowed to subscribe to. However, we do not recommend using this topic as new message types may be added in the future.

Message Types​

Following is a list of the different message types published by the service. The payload will always be in JSON format and follows the schema referenced in each type below.

All messages are published with QoS 2 but you can chose to subscribe with whatever quality of service that fits your use case.

Container Events​

Sent By: Server
Topic: v2/[Organization ID]/container/event/[Container ID]/
Schema: container-event.schema.json

Detailed description of events from a container can be found here.

Example:

v2/5d7a0b958086466694f5be0e/container/event/5d5575d638817e246cef4d0b
{
  "time": "2021-12-24T08:00:00.000Z",
  "container": {
    "id": "5d5575d638817e246cef4d0b",
    "name": "Example Container",
    "externalId": "CON123",
    "coordinates": { "latitude": 55.716994, "longitude": 13.225053, "altitude": 0 },
    "devices": [
      { "id": "5d7a0b958086466694f5be78", "bintelId": "123456" }
    ],    
  },
  "event": {
    "eventType": "pickup-requested"
  }
}

Container Updates​

Sent By: Server
Topic: v2/[Organization ID]/container/update/[Container ID]
Schema: container-update.schema.json

Detailed description of data from a object can be found here. Even if several data updates occur at the same time they are still sent as separate messages.

Example:

v2/5d7a0b958086466694f5be0e/container/update/5d5575d638817e246cef4d0b
{
  "time": "2021-12-24T08:00:00.000Z",
  "container": {
    "id": "5d5575d638817e246cef4d0b",
    "name": "Example Container",
    "externalId": "CON123",
    "coordinates": { "latitude": 55.716994, "longitude": 13.225053, "altitude": 0 },
    "devices": [
      { "id": "5d7a0b958086466694f5be78", "bintelId": "123456" }
    ],   
  },
  "update": {
    "tag": "fill-percent",
    "value": 0.6
  }
}

Container Report​

Sent By: Client
Topic: v2/[Organization ID]/container/report
Schema: container-report.schema.json

Either id or externalId needs to be present to identify the container.

Available report types can be found here.

The time field should indicate the moment the report was originally generated.

The source field is optional but recommended. It is used to indicate the source of the report. Like in this example the report was generated from a system in the truck making a pickup. There are no hard constraints on this field but it should be kept consistent, i.e. as long as the source is the same this value should not change.

The weight field is also optional and can be used to supply weight information to the system when available. The unit is kilograms. If no weight data is available this field should be omitted.

The list of discrepancies field is also optional and can be used to supply discrepancies associated with the pickup ,this information can be supplied together with any of the report types. The strings supplied should be consistent for the same discrepancy type but do not need to adhere to a predefined set.

Example:

v2/5d7a0b958086466694f5be0e/container/report
{
  "id": "5d5575d638817e246cef4d0b",
  "time": "2019-12-24T08:00:00.000Z",
  "reportType": "pickup-performed",
  "source": "in-truck-computer",
  "weight": 42.0,
  "discrepancies": ["littering"]
}

or

v2/5d7a0b958086466694f5be0e/container/report
{
  "externalId": "CON123",
  "time": "2019-12-24T08:00:00.000Z",
  "reportType": "pickup-performed",
  "source": "in-truck-computer",
  "weight": 42.0,
  "discrepancies": ["overfilled"]
}