Asset tracking data exchange with third party systems
This article describes the available interfaces between third-party systems and thingsHub Asset Tracking.
Exporting location data from thingsHub to external third party systems
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 third party data into the Asset Inventory
Push-synchronization
For push synchronization, simply POST a full listing of the assets to REST endpoint api/v3/assets-import. The endpoint expects an array of flat JSON objects.
During Asset synchronization, the thingsHub expects two specific fields, the primary_id to be present in all assets. And there’s an optional field name can be provided, from which the name of the asset will be populated if the value is found from the asset data during synchronization. If not provided, the system will look for name or Name keys in the asset data. If none of them are found for name of the asset, primary_id will be used as the name of the assets. These keys are set during installation, so ask your admin for this information. Also refer to the section "Pull-synchronization" above.
All other keys of the JSON objects will be added to the Asset as metadata and can be used in the user interface for searching a matching Asset.
For authentication, generate an API key first and put this in the authorization HTTP header, e.g. Authorization: Bearer <token>.
The POST request will return immediately once it has been fully parsed, while the actual synchronization happens in the background. The current status of the synchronization can be queried for now using the GET verb. This will return a brief summary of everything that happened during synchronization, including the number of successfully imported Assets and the failed ones:
{
metadata: {
"counts": {
"failed": 2,
"imported": 5,
"in_progress": 1,
"total": 8,
"duplicated": 0,
"invalid_id_format": 0,
"without_primary_id": 0,
"without_name": 0
},
"status": "running"
},
"last_import": {
"ended": "2024-03-06T02:02:37.437Z",
"requested": "2024-03-06T02:02:37.437Z",
"started": "2024-03-06T02:02:37.437Z"
},
"ignored": [
{
"entry": {
},
"row_number": 10,
"reasons": [ strings ]
},
{
"entry": {
},
"row_number": 12,
"reasons": [ strings ]
}
]
}We strongly suggest limiting the number of metadata fields to 6-10 fields and not import data more frequently than every 15 minutes.
Pull Synchronization
ThingsHub can also regularly query the asset inventory to be imported from an API of the third-party application. To configure this, please get in touch with your account contact at SmartMakers.