REST API Reference

REST API Reference

The Globe Tracker RESTful API provides access to a wide range of IoT and logistics data. This reference covers all available resources, endpoints, request/response formats, and error handling. The API follows REST principles and uses JSON for payloads.

Base URL

https://api.gtsense.globetracker.io/

Authentication

All API requests require authentication using OpenID Connect. You will be provided with the following credentials:

• client-id: An identifier used by the authentication server to ensure that the client is authorized to make a request on behalf of the user.
• client-secret: A secret passphrase used by the authentication server to ensure that the client is authorized to make a request on behalf of the user.
• username: Your unique user ID for authorization.
• password: The password associated with your username.

To obtain a JWT access token, use the following request:

curl --silent \
  https://<client-id>:<client-secret>@keycloak.apps.prod.globetracker.me/auth/realms/gtsense/protocol/openid-connect/token \
  -d "grant_type=password&scope=openid+profile+read&username=<username>&password=<password>"

The response will include an access_token (JWT). Include this token in the Authorization header for all API requests:

Authorization: Bearer $TOKEN

The JWT token expires after 20 minutes (see the exp property in the payload).

Entities

Entity	Description
Asset	An entity being tracked.
Location	A GPS position, may include heading, etc.
Owner	Registered owner of the asset or data record.
Sensor data	Sensor data from an asset.
Reefer data	Reefer data from an asset.
Command	Command sent to a reefer-connected asset.
Zone	Named geographical area, which locations can refer to.
Specification	Operational settings, ranges, and notification settings for assets.
Booking data	Booking data in flexible JSON format.
Notification	Alerts/events raised by settings, ranges, and notifications.

---

HTTP Verbs

Verb	Usage
GET	Retrieve a resource
POST	Create a new resource
PUT	Replace an existing resource
PATCH	Update an existing resource (partial)
DELETE	Delete an existing resource

---

HTTP Status Codes

The API uses standard HTTP status codes:

• 1xx: Informational
• 2xx: Success (e.g., 200 OK, 201 Created)
• 3xx: Redirection
• 4xx: Client Error (e.g., 400 Bad Request, 401 Unauthorized)
• 5xx: Server Error

---

Error Handling

Error responses (status code >= 400) return a JSON object describing the problem. Example:

{
  "error": "Invalid request",
  "message": "The 'name' field is required."
}

---

Rate Limiting

• 1000 requests per hour per API key
• 10 concurrent requests per API key

---

API Resources & Endpoints

Below are the main resources and their entity field definitions. For full endpoint details and example requests, please refer to the Swagger documentation.

Note: All date fields (such as whenCreated, whenUpdated, etc.) are in ISO8601 format.

Asset

An entity being tracked, such as a container, trailer, or other asset managed by Globe Tracker.

Entity Fields

Field	Type	Optional	Description
id	String	false	Unique GT Sense assigned asset identifier, never changes. Size: 36.
name	String	false	Unique owner/customer assigned asset identifier, may change. Size: 255.
disabled	Boolean	true	Should the GT Sense GUI hide this asset.
note	String	true	Optional owner/customer note. Size: 255.
tags	String	true	List of comma separated owner/customer tag words for searching and classification. Size: 255.
ownerId	String	false	Asset owner identifier. Size: 36.
whenCreated	String	false	When created (ISO8601).
whenUpdated	String	false	When last updated (ISO8601).

Example

[{
  "whenCreated" : "2015-01-27T13:27:58.437Z",
  "whenUpdated" : "2015-01-29T12:41:42.830Z",
  "assetTags" : "REEFER,TK,MP4000,MP4000",
  "ownerId" : "c29a854d-b98f-4ecc-ad18-ecfb91025067",
  "id" : "89249552-160e-45c0-91e7-ca0c8eb173c0",
  "name" : "STRU581950-8"
}, {
  "whenCreated" : "2017-06-13T14:38:07.842Z",
  "whenUpdated" : "2017-06-13T14:39:03.751Z",
  "assetTags" : "REEFER,TK",
  "ownerId" : "c29a854d-b98f-4ecc-ad18-ecfb91025067",
  "id" : "3f16d4c6-adeb-45e5-a539-4f989ce612ed",
  "name" : "ASSET-80049"
}, {
  "whenCreated" : "2017-06-13T14:39:52.635Z",
  "whenUpdated" : "2020-08-13T00:10:04.125Z",
  "assetTags" : "REEFER,CARRIER",
  "ownerId" : "c29a854d-b98f-4ecc-ad18-ecfb91025067",
  "id" : "85e5ae99-f722-4633-b40e-48eeff445008",
  "name" : "ASSET-80050"
}]

---

Booking Data

Booking data in a flexible JSON format, representing shipment or booking information associated with an asset.

Entity Fields

Field	Type	Size	Optional	Description
name	String	50	true	The name of the booking data. The name should be unique within the customer.
ownerId	String	36	true	Unique owner string identifier. If not provided, GT API set it to current user.
type	String	enum	false	The type of the booking data. Valid types are as follows: ‘SEABOARD_V1’
jsonData	Object	na	true	The booking data itself. It should be a valid json.

Example

{
  "name": "SPEC-3",
  "type": "CUST_V1",
  "whenCreated": "2015-01-27T13:27:58.437Z",
  "whenUpdated": "2015-01-29T12:41:42.830Z",
  "whoCreated": "arnar3@acme.com",
  "ownerId": "c29a854d-b98f-4ecc-ad18-ecfb91025067",
  "jsonData": {
    "OfficeId": "Torshavn",
    "BookNbr": 6206344
  },
  "id": "da1181d0-c7c9-4d75-974e-7d3923357090"
}

---

Location

A GPS position report, which may include heading, speed, altitude, and associated asset and zone information.

Entity Fields

Field	Type	Optional	Description
id	String	false	Unique GT Sense assigned location identifier, never changes. Size: 20.
ownerId	String	false	Location owner identifier. Size: 36.
latitude	Number	false	Latitude in degrees. Size: -99.999999 to 99.999999
longitude	Number	false	Longitude in degrees. Size: -99.999999 to 99.999999
altitude	Number	true	Altitude in meters. Size: -99999.99 to 99999.99
heading	Number	true	Heading in degrees. Size: -999.9 to 999.9
speed	Number	true	Speed in km/h. -999.999 to 999.999
assetId	String	false	Id of asset generating this location. Size: 36.
whenCreated	String	false	When created. Size: 20.
zoneId	String	true	Comma separated Zone ids. Size: 100.

Example

{
  "whenCreated": "2015-02-09T14:11:46.874Z",
  "whenUpdated": "2015-03-27T15:46:06.454Z",
  "ownerId": "dff711a5-685f-442e-a1ae-a860b541d5e7",
  "id": "79b508eb-072f-4a4a-9fa2-0eb5da960c3d",
  "name": "ECC-RHU706"
}

---

Owner

A registered owner of an asset or data record, representing a customer or organization in the system.

Entity Fields

Field	Type	Optional	Description
id	String	false	Unique GT Sense assigned owner identifier, never changes. Size: 36.
name	String	false	Unique owner name. Size: 255
note	String	true	Owner note. Size: 255.
disabled	Boolean	true	Should the GT Sense GUI hide this owner. When not shown value is false.
whenCreated	String	false	When created. Size: 20.
whenUpdated	String	false	When last updated. Size: 20.
childIds	Array	true	Optional child owners with visible data. Array with Strings.
ownerId	String	true	Optional parent owner with data viewing rights. Size: 36.

Example

{
  "whenCreated": "2018-03-19T15:20:57.017Z",
  "whenUpdated": "2018-03-19T15:37:37.017Z",
  "disabled": true,
  "note": "Acme18 Shipping Line Inc.",
  "name": "Acme18 Inc.",
  "ownerId": "dff711a5-685f-442e-a1ae-a860b541d5e7",
  "id": "f05de594-fc61-44b2-8301-65d873bbcd8f",
  "childIds": ["g05de594-fc61-44b2-8301-65d873bbcd8f"]
}

---

Sensor Data

Sensor data collected from an asset, such as temperature, humidity, acceleration, or other sensor measurements.

Entity Fields

Field	Type	Optional	Description
id	String	false	Unique sensor data identifier.
sensorId	String	false	Id of sensor generating this sensor data. Size: 36.
type	String	false	Type of measurement, one of TEMPERATURE, HUMIDITY, X_ACCELERATION, Y_ACCELERATION, Z_ACCELERATION, FUEL_LEVEL, X_PEAK_ACCELERATION, Y_PEAK_ACCELERATION, Z_PEAK_ACCELERATION, BATTERY_VOLTAGE, EXTERNAL_POWER_VOLTAGE, PRESSURE.
value	Number	false	Measurement value. Depending on sensor data it will return string instead.
assetId	String	false	Id of asset generating this sensor data. Size: 36.
whenCreated	String	false	When created. Size: 20.

Example

[
  {
    "value": 24,
    "id": "4",
    "whenCreated": "2018-09-01T17:15:08Z",
    "sensorId": "ba0e9980-8b2c-4d70-9f9d-baf682d38c5a",
    "sensorType": "GTCM",
    "ownerId": "c29a854d-b98f-4ecc-ad18-ecfb91025067",
    "type": "HUMIDITY",
    "assetId": "ba0e9980-8b2c-4d70-9f9d-baf682d38c5a"
  },
  {
    "value": 29.47,
    "id": "5",
    "whenCreated": "2018-09-01T17:15:08Z",
    "sensorId": "ba0e9980-8b2c-4d70-9f9d-baf682d38c5a",
    "sensorType": "GTCM",
    "ownerId": "c29a854d-b98f-4ecc-ad18-ecfb91025067",
    "type": "TEMPERATURE",
    "assetId": "ba0e9980-8b2c-4d70-9f9d-baf682d38c5a"
  }
]

---

Reefer Data

Data collected from a refrigerated container (reefer), including controller settings, sensor measurements, alerts, and flags.

Entity Fields

Field	Type	Optional	Description
id	String	false	Unique GT Sense assigned reefer data identifier, never changes. Size: 20.
assetId	String	false	Id of asset generating this reefer data. Size: 36.
ownerId	String	false	Reefer data owner identifier. Size: 36.
reeferClass	String	true	Class of reefer controller. Currently one of CR, CR0, CRTT, DK, MH, SC, LD, TK, TKTT
data	Object	false	The reefer data. Size: na
whenCreated	String	false	When created. Size: 20.

Example

{
  "id": "1",
  "whenCreated": "2018-09-01T17:12:24Z",
  "ownerId": "dff711a5-685f-442e-a1ae-a860b541d5e7",
  "data": {},
  "gensetManufacturer": "EMERSON",
  "assetId": "a4c6fa3e-e73b-4f49-b5c0-c5db00af2825"
}

---

Command

A command sent to a reefer-connected asset, such as starting PTI, setting temperature, or other remote actions.

Entity Fields

Field	Type	Optional	Description
id	String	false	Unique command identifier
assetId	String	false	Associated asset identifier
type	String	false	Command type
parameters	Object	true	Command parameters
status	String	true	Command status
whenCreated	String	false	When created

Example

{
  "id": "17",
  "whenCreated": "2024-04-17T14:34:15.600Z",
  "whoCreated": "GT.development",
  "uniqueId": "17",
  "command": "StartPti",
  "ownerId": "86202B41-F7B6-4256-808F-09FF31FD9554",
  "assetId": "79b508eb-072f-4a4a-9fa2-0eb5da960c3d"
}

---

Event

An event triggered by settings, ranges, or notifications within the GT Sense Platform, such as alerts or status changes.

Entity Fields

Field	Type	Optional	Description
subject	String	false	Subject of the event.
assetId	String	false	Id of asset generating this event.
severity	String	false	Severity of event, one of INFO, ALERT.
ownerId	String	false	Event owner identifier.
currentData	String	false	JSON payload containing the current value as a String and whenCreated.
prevData	String	true	JSON payload containing the previous value as a String and whenCreated.

Example

[
  {
    "ownerId": "dff711a5-685f-442e-a1ae-a860b541d5e7",
    "severity": "INFO",
    "subject": "Asset SMLG3648 fuel level has dropped by 23.0000%",
    "currentData": {
      "value": "52",
      "whenCreated": "2022-08-09T14:54:02.000Z"
    },
    "prevData": {
      "value": "75",
      "whenCreated": "2022-08-09T14:44:01.000Z"
    },
    "assetId": "cfd14ab2-a131-r33c-rc9c-ier6bcc9a4f6"
  }
]

---

Zone

A named geographical area, such as a port, country, or custom region, which locations and assets can refer to.

Entity Fields

Field	Type	Optional	Description
id	String	false	Unique GT Sense assigned zone identifier, never changes. Size: 20.
ownerId	String	false	Zone owner identifier. Size: 36.
name	String	false	Customer specified name of zone. Size: 32.
type	String	true	Zone type. Size: 32.
note	String	true	A note for the zone. Size: 254.
whenCreated	String	false	When created. Size: 20.
whenUpdated	String	false	When last updated. Size: 20.

Example

{
  "name": "PL-GDN",
  "id": "z69246196",
  "type": "Port in PL",
  "whenCreated": "2016-09-13T10:42:25.200Z",
  "whenUpdated": "2019-01-18T15:59:07.638Z",
  "note": "Note: Port in PL",
  "ownerId": "dff711a5-685f-442e-a1ae-a860b541d5e7"
}

---

Specification

Operational settings, ranges, and notification settings for an asset, defining how it should be monitored and managed.

Entity Fields

Field	Type	Size	Optional	Description
id	String	36	false	Unique specification string identifier.
name	String	50	true	The name of the specification.
assetId	String	36	false	Unique asset string identifier.
assetName	String	255	false	Unique asset name identifier.
ownerId	String	36	false	Unique owner string identifier.
type	String	enum	false	The type of the specification. Valid specification type are as follows: ‘REEFER’,‘GENSET’
settings	Object	na	true	The set points.
ranges	Object	na	true	Ranges define the minimum and maximum accepted values for sensors, and also when and how often to notify about unacceptable values.
notification	Object	na	true	Notification define when and how often to notify about some specific events.
whoCreated	String	36	false	Who created the specification.
whenCreated	String	20	false	When the specification was created.
whenUpdated	String	20	false	When the specification was updated.

Example

{
  "name": "ACME1351451-20191129-12102",
  "type": "REEFER",
  "whenCreated": "2024-04-17T14:33:54.031Z",
  "whenUpdated": "2024-04-17T14:33:54.031Z",
  "whoCreated": "GT.development",
  "ownerId": "c29a854d-b98f-4ecc-ad18-ecfb91025067",
  "assetName": "STRU581950-8",
  "ranges": {
    "cargo": {
      "sensors": {
        "airExchange": [1, 2, 3, 4],
        "co2": [5, 6, 7, 8],
        "co": [21, 22, 23, 24],
        "o2": [9, 10, 11, 12],
        "ethylene": [21, 22, 23, 24],
        "nitrogen": [4, 5, 10, 20],
        "humidity": [13, 14, 15, 16],
        "ambientTemperature": [17, 18, 19, 20],
        "returnAirTemperature": [2, 18, 23, 24],
        "returnAir2Temperature": [12, 22, 23, 24],
        "supplyAirTemperature": [21, 22, 23, 24],
        "supplyAir2Temperature": [21, 32, 23, 24],
        "usda1Temperature": [20, 22, 23, 24],
        "usda2Temperature": [11, 22, 23, 24],
        "usda3Temperature": [11, 22, 23, 24],
        "usda4Temperature": [1, 22, 23, 24]
      }
    },
    "hardware": {
      "sensors": {
        "batteryVoltage": [90, 100, null, 12],
        "compressorTemperature": [9, 10],
        "compressorFrequency": [1, 3, 7],
        "condenserPressure": [1, 5, null, 7],
        "condenserTemperature": [3, 10, 9],
        "condenserFanLevel": ["ERROR", "LOW"],
        "evaporatorTemperature": [0, 6],
        "evaporatorFanLevel": ["OFF", "HIGH"],
        "currentA": [1, 2],
        "currentB": [1, 2],
        "currentC": [1, 2],
        "currentTotal": [1, 2],
        "defrostTemperature": [55, 78, 5, 10],
        "dischargePressure": [12, 33, 1, 2],
        "dischargeTemperature": [1, 2],
        "engineCoolantTemperature": [1, 2],
        "engineRpm": [1, 2],
        "fuelLevel": [50, 75],
        "heaterValveOpening": [1, 2],
        "lineFrequency": [1, 2],
        "lineVoltage": [1, 2],
        "modemBatteryVoltage": [1, 2],
        "suctionPressure": [1, 2],
        "suctionTemperature": [80, 102],
        "hotGasValveOpening": [50, 75],
        "economizerValveOpening": [50, 75],
        "expansionValveOpening": [50, 75]
      }
    }
  },
  "settings": {
    "cargo": {
      "settings": {
        "co2Setpoint": 5,
        "humiditySetpoint": 75,
        "o2Setpoint": 20,
        "temperatureSetpoint": 260.4
      }
    }
  },
  "id": "d0badd97-8032-4472-939a-45846d640682",
  "notification": {
    "controller": {
      "alarm": {
        "default": {
          "duration": 2,
          "frequency": 4
        }
      },
      "power": {
        "default": {
          "duration": 3,
          "frequency": 5
        }
      },
      "ca": {
        "default": {
          "duration": 0,
          "frequency": 5
        }
      }
    },
    "controlModule": {
      "scheduler": {
        "default": {
          "duration": 6,
          "frequency": 7
        }
      }
    }
  },
  "assetId": "ba0e9980-8b2c-4d70-9f9d-baf682d38c5a"
}

---

Notification

Alerts and events raised by settings, ranges, and notifications in a Specification, pushed to clients as notifications.

Entity Fields

Field	Type	Size	Optional	Description
id	String	20	false	Unique permanent GT Sense assigned notification identifier.
ownerId	String	20	false	Unique owner string identifier.
assetId	String	20	false	Unique asset string identifier.
assetName	String	255	false	Unique asset name identifier.
whenCreated	String	20	false	When the specification was created.
whenReceived	String	20	false	When notification received on server.
type	String	256	false	Name of notification, or triggering “event”.
specificationId	String	256	false	Unique specification string identifier.
specificationName	String	256	true	The name of the specification. Is optional if not sent in customer Specification
location	Location	na	false	Most recent location to “event” generating notification.
reeferData	ReeferData	na	false	Reefer status when notification was generated.
assetState	AssetState	na	true	Asset state.
cmData	cmData	na	true	GT Control Module status when notification was generated.

Example

{
  "id": "1",
  "ownerId": "dff711a5-685f-442e-a1ae-a860b541d5e7",
  "assetId": "a4c6fa3e-e73b-4f49-b5c0-c5db00af2825",
  "assetName": "GZEU450084-3",
  "whenCreated": "2024-04-17T14:33:54.031Z",
  "whenReceived": "2024-04-17T14:33:54.031Z",
  "type": "ALERT",
  "specificationId": "d0badd97-8032-4472-939a-45846d640682",
  "specificationName": "ACME1351451-20191129-12102",
  "location": {
    "id": "z69246196",
    "name": "PL-GDN",
    "type": "Port in PL",
    "whenCreated": "2016-09-13T10:42:25.200Z",
    "whenUpdated": "2019-01-18T15:59:07.638Z",
    "note": "Note: Port in PL",
    "ownerId": "dff711a5-685f-442e-a1ae-a860b541d5e7"
  },
  "reeferData": {
    "id": "1",
    "whenCreated": "2018-09-01T17:12:24Z",
    "ownerId": "dff711a5-685f-442e-a1ae-a860b541d5e7",
    "data": {},
    "gensetManufacturer": "EMERSON",
    "assetId": "a4c6fa3e-e73b-4f49-b5c0-c5db00af2825"
  },
  "assetState": {
    "powerOffSince": null,
    "powerOnSince": "2024-04-17T14:33:54.031Z",
    "lastDefrost": null
  },
  "cmData": {
    "deviceId": "GTCM123456",
    "serial": "SN1234567890",
    "ownerId": "dff711a5-685f-442e-a1ae-a860b541d5e7",
    "firmwareVersion": "1.0.0.0",
    "configuration": "{...}",
    "lastUpdated": "2024-04-17T14:33:54.031Z"
  }
}

---

Next Steps

• Set up Push Services
• CLI Tool Setup
• SDK Integration