Asset Export Interface: how to retrieve tracking data in your IT systems

This document provides comprehensive information and technical specifications for querying and utilizing operational data from your thingsHub Track & Trace Cloud. It is intended for users seeking to integrate this data with external master data systems, such as SAP or Microsoft Dynamics, to support various business processes and data analysis requirements.

Retrieving tracking & location data from thingsHub for your IT system(s)

An Asset’s localization information can be retrieved via the thingsHub’s REST API by querying the api/v3/tracked-assets endpoint (or just a single Asset with api/v3/tracked-assets/:id). This will return a structure such as the following:

{
  "collection": [
    {
      "active_journey_id": "fe2a502c-85d0-1980-e080-c8a553103302",
      "created_at": "2024-12-19T09:16:35.519Z",
      "entered_site_at": "2025-01-06T14:57:40.000Z",
      "geolocation": {
        "address": {
          "city": "St. Gallen",
          "country": "Switzerland",
          "house_number": "17",
          "label": "Schuppisstrasse 17, 9016 St. Gallen, Switzerland",
          "postcode": "9016",
          "region": "Sankt Gallen",
          "street": "Schuppisstrasse"
        },
        "latitude": 47.44257,
        "longitude": 9.41983,
        "margin": 41.7,
        "moved_at": "2025-01-29T15:56:25.000Z",
        "site": "Headquarter St. Gallen",
        "speaking_location": "Headquarter St. Gallen"
      },
      "id": "353785726410409",
      "name": "Load Carrier #8063",
      "site_id": "headquarter-st-gallen",
      "site_name": "Headquarter St. Gallen",
      "tracker_id": "353785726410409",
      "type": "digital-matter-algo-complete-journey",
      "updated_at": "2025-01-29T15:56:26.081Z",
      "zone_id": ""
    },
    {
      "active_journey_id": "65bd81e4-504b-7c68-35ac-6ad6ea96a1fb",
      "created_at": "2024-11-21T14:41:42.943Z",
      "exited_site_at": "2024-12-04T11:37:49.000Z",
      "geolocation": {
        "address": {
          "city": "Hanau",
          "country": "Germany",
          "label": "Hauptbahnhofbrücke, Willy-Brandt-Straße, 63450 Hanau, Germany",
          "postcode": "63450",
          "region": "Hessen",
          "street": "Willy-Brandt-Straße"
        },
        "latitude": 50.12321,
        "longitude": 8.92466,
        "margin": 20.7,
        "moved_at": "2025-01-29T15:56:23.000Z",
        "speaking_location": "Willy-Brandt-Straße, Hanau"
      },
      "id": "353785725665763",
      "name": "Load Carrier #318-1133",
      "site_id": "",
      "tracker_id": "353785725665763",
      "type": "digital-matter-algo-complete-journey",
      "updated_at": "2025-01-29T15:56:25.540Z",
      "zone_id": ""
    },
    ...
  }
}

The ‘Speaking Location’: preserve the location of an asset as a single field

In many master data systems (ERP, SAP, TMS, ...), the location of an asset can and should be mapped as a single field. In addition, master data systems often do not support any map display in their user interface.

The product development team at thingsHub has therefore developed a concept that we call the speaking_location of an asset. This is generated with every location update from the information available in thingsHub (sites, zones, addresses...) and should contain the location of the asset in a location name that is easy for your company's employees to understand.

For example, if an asset is located in a ‘Car Park 2’ zone on the ‘Munich Headquarters’ site, the speaking_location would contain the following value: ‘Car Park 2, Munich Headquarters’.

If, on the other hand, the asset is located at the customer ‘Customer ABC’, the value ‘Customer ABC’ would appear in the speaking_location.

If the location of an asset is neither on your own premises nor at customer locations, thingsHub generates an address for the location with the help of Google Maps services. In this case, the speaking_location could then contain the value ‘Hauptstraße am Randhaus 14, Berlin’.

Asset location other detailed information explained

The location of the tracked asset is stored in the geolocation.latitude and geolocation.longitude fields and as a human readable “address” in geolocation.zone and geolocation.site fields. The margin (if available) provides a rough estimate of the localization’s error margin in meters. Metadata added during importing shows up as metadata here, too, while the field id can be used to identify the Asset and the field external_id can be used to identify the Asset Tag.

Importing asset data from your IT system to thingsHub

Please read Asset Import Interface: how to import assets to thingsHub