Tive Public API Technical Documentation

  • Updated
Follow

Overview

Security & API Usage

Configuration API
Accounts & Users
Webhooks
Alert Profiles
Devices & Shipments
Tracker Data

Appendix A - Data Structures
Device Data Entry
Alert Data Entry

Appendix B - Data Entry Properties
Device Data Entry Properties
Alert Data Entry Properties

 

Overview

This document describes the Tive Public API (version 2).

The Tive API provides a comprehensive interface for managing all aspects of a Tive account. The API includes direct methods for reading and manipulating the system state as well as receiving push notifications.

The API uses standard REST / HTTP methods.

Access the API at the following URL: https://api2.prod1.tive.co/docs

Code samples are available upon request. Contact us for details.

 

Security & API Usage

The Tive API uses an API key for authentication and authorization. Users of the API need to pass the API key for all methods. The key is passed as an HTTP header item.

  • Header name: “TiveApiKey”
  • Header value: A string key provided by Tive

Common operations include:

  • POST - for creating new objects or invoking state-changing methods
  • GET - for retrieving a single object or a list of objects
  • PUT - for updating the state of an object
  • DELETE - for deleting an object

Tive uses JSON format (content-type - “application/json”) both for input in the request body and for output.

Return values are wrapped in a status object and can be retrieved from the JSON property “result”. Below is an example result of an account GET method.

{
  "status": "OK",
  "result": {
    "id": 12345,
    "name": "Tive",
    "location": {
      "street": "56 Roland Street",
      "locality": "Boston",
      "state": "Massachusetts",
      "country": "US",
      "zipCode": "02129"
    }
  }
}

 

Configuration API

The main objects that can be manipulated through the Tive API are:

  • Accounts
  • Users
  • Webhooks
  • Alert Profiles
  • Devices
  • Shipments

Below, we provide a brief overview of each of these objects. See the Tive online documentation for more details.

 

Accounts & Users

Account API methods provide general information about the account, such as the account name, ID, and location.

User API methods allow the reading and configuring of account users. Contact information such as email addresses and phone numbers, which is stored within the User object, is used for sending Tive alerts to users (see Alert Profiles for details).

 

Webhooks

Webhooks provide a programmatic endpoint for receiving Tive data. Webhooks can be used for receiving Tive device data stream events and Tive alert data stream events.

Webhooks define HTTP endpoints. The API allows you to configure a webhook’s URL, which HTTP method to use, custom headers, and a template.

Message Format

The template is a key concept for webhook definitions. When a template is left empty, the default JSON representation of an event is used as the body of the message. When a template is configured, a user can control the formatting of the message.

The default JSON representation for Tive data stream events and alert events is presented in the Appendix section.

The following code sample shows an example template: 

{
   "text": "*Tive Device Data Entry for Device {DeviceId} / {DeviceName}*",
   "icon_emoji": ":tive:",
   "attachments": [
      {
         "color": "good",
         "text": "Entry Time: {EntryTime.Utc} (UTC), Epoch: {EntryTime.Epoch}"
      },
      {
         "color": "good",
         "text": "Temperature: {Temperature.Celsius} °C"
      }
   ]
 }

 

A Few Notes on Template Variables

  • Template Variables are defined using curly braces: “{MyVariable}”.
  • The Tive system will replace Template Variables with their value or “N/A” if the variable name is unknown or has no value
  • Valid variable names are letter and the ‘.’ (dot) character
  • The complete list of variable names available are provided in the Appendix

 

Alert Profiles

Alert Profiles allow you to track events of interest. For example, you can configure the system to trigger an event when the device experiences high temperature or when it arrives at a specific destination.

Alert Profiles objects contain two main sections:

  • The target for the data
    • Assignees - a set of users to be notified
    • Webhooks - a set of webhooks to be notified
  • Triggers
    • Definition of the conditions that will trigger an event

Once configured, an Alert Profile can be attached to specific devices or shipment objects. It will then monitor these devices and shipments for the specific conditions defined within the Alert Profile.

The API includes a method called “sample” that provides a list of all possible triggers and the details of how they are configured. Below is an example showing an Alert Profile that creates a trigger for shock events. To view all the samples, you can use the /api/v2/alertsprofile/sample endpoint.

{
    "id": 12345,
    "name": "Monitor Shock Alerts",
    "description": "Monitor shocks experienced by the device",
    "profileType": "Device",
    "assignees": [
      "aaaaa-bbb-ccccc-ddddd"
    ],
    "webHooks": [
      12345,
      1123456
    ],
    "triggers": [
      {
        "id": 424,
        "type": "Shock",
        "name": null,
        "description": null,
        "isEnabled": true
      }
  }

 

Devices & Shipments

Devices or “Trackers” are the main element in the Tive system that generates data. The Device API provides methods for:

  • Getting a list of devices and information about them
  • Configuring the device (e.g. enable/disable GPS, set radio transmission frequency, etc.)
  • Getting the latest device status
  • Associating a webhook with a device to receive device data stream events
  • Associating an Alert Profile with a device to get alert notifications.

 Shipment objects provide a mechanism to track real-life shipments by providing the origin, destination, and time of a shipment. Tive uses the shipment information to associate device alert events with specific real-life shipment events, including arrival, departure and other shipment-specific alerts. 

The API provides methods for creating, deleting, starting, and completing shipments.

Shipments GET method

The shipments GET method and the status of the shipment GET method both take a search query that can be used to filter the results.

If empty, the method will return all shipment objects (with limitation on page size).

The shipment search query has the following structure, with all fields optional. 

{ 
    States: [<shipment-state>], 
    ShipmentId: <shipment-id> 
}

 The shipment state value can be Upcoming, Active, or Completed.

For example, to get current active shipments: 

{ States : ["Active"] }

 To get active and completed shipments:

{ States : ["Active", "Completed"] }

Shipments POST and PUT method

The Shipment PUT method can be used for ocean shipments when the following is provided:

  • ContainerId is the ISO 6346 container format
  • Carrier must be specified for the ContainerId - use "OTHERS" if unknown.  Contact support@tive.co for a list of all ocean carriers we support; most are provided in Tive Platform when creating a new shipment.

Tracker Data

The Tracker Data API allows you to get the data for all trackers that belong to your account, filtered by tracker name & time range.

You can specify one of the two following data format types:

  • JSON format object, which will contain two main sections:
    • Columns: Tracker_name, Time, and list of the sensors you specified
    • Data: List of data for the selected sensors
  • CSV format
    • Contains data for the specified filters & selected sensors

Below are examples showing Tracker Data in JSON and CSV format.

JSON Format:

{
    "columns": [
        "Tracker_Name",
        "Time",
        "Location",
        "Lat",
        "Lng",
        "Temperature",
        "Humidity",
        "Pressure",
        "Light",
        "Motion"
   ],
   "data": [
      [
        "VD0001",
        "9/14/2018 2:49:02 PM",
        "56 Roland Street, Boston, Massachusetts 02129, United States",
        42.3983903,
        -71.12880539999999,
        -37.23,
        50.03,
        14.76,
        2.14,
        0
   ]
}

 

CSV Format:

“Tracker_Name,Time,Location,Lat,Lng,Temperature,Humidity,Pressure,Light,Motion\r\nVD0001,9/14/2018 2:49:02 PM,\"56 Roland Street, Boston, Massachusetts 02129, United States\",42.3983903,-71.12880539999999,-37.23,50.03,14.76,2.14,0\r\nVDT003,9/14/2018 2:58:12 PM,\"350 5th Avenue, Manhattan, New York, New York 10118, United States\",40.7485416666667,-73.9857638888889,-37.02,53.23,14.57,2.14,0\r\n”

 

Appendix A - Data Structures

The following two sections provide examples that show the data structures available from the Tive API for device data stream (Device Data Entry) and Alerts data stream (Alert Data Entry).

 

Device Data Entry 

{
  "EntityName": "VD0001",
  "EntryTimeEpoch": 1612465056823,
  "EntryTimeUtc": "2021-02-04T18:57:36.8229403",
  "Cellular": {
    "SignalStrength": "Good",
    "Dbm": -73
  },
  "Temperature": {
    "Celsius": 23,
    "Fahrenheit": 73.4000015258789
  },
  "Pressure": {
    "Psi": 44.0879020690918,
    "Atmospheric": 3.0000040531158447
  },
  "Humidity": {
    "Percentage": 33.29999923706055
  },
  "Weather": {
    "Temperature": {
      "Celsius": 0,
      "Fahrenheit": 32
    },
    "Wind": null
  },
  "Accelerometer": {
    "G": 4.115822958620668,
    "X": 1.100000023841858,
    "Y": 2.200000047683716,
    "Z": 3.299999952316284
  },
  "Light": {
    "Lux": 133.26
  },
  "MinLight": {
    "Lux": 5.22
  },
  "MaxLight": {
    "Lux": 300
  },
  "Battery": {
    "Percentage": 55,
    "IsCharging": false
  },
  "Shock": {
    "G": 10.656894339940518,
    "X": -10.229999542236328,
    "Y": 0.1899999976158142,
    "Z": -2.9800000190734863
  },
  "ShockTime": "1970-01-01T00:00:00Z",
  "Shipment": {
    "Id": "Public Shipment Id",
    "Description": "Shipment Description",
    "WebhookIds": [],
    "DeviceId": "000000000000000000000001",
    "DeviceIds": [
      "000000000000000000000001"
    ],
    "AutoComplete": false,
    "ShipFromDate": "2021-02-04T18:57:36.823043+00:00",
    "ShipFrom": {
      "Name": null,
      "Latitude": null,
      "Longitude": null,
      "FormattedAddress": null,
      "Address": {
        "Street": "56 Roland Street",
        "Sublocality": "",
        "Locality": "Boston",
        "State": "MA",
        "Country": "USA",
        "ZipCode": "02129"
      },
      "LocationMethod": null,
      "Accuracy": null
    },
    "ShipTo": {
      "Name": null,
      "Latitude": null,
      "Longitude": null,
      "FormattedAddress": null,
      "Address": {
        "Street": "56 Roland Street",
        "Sublocality": "",
        "Locality": "Boston",
        "State": "MA",
        "Country": "USA",
        "ZipCode": "02129"
      },
      "LocationMethod": null,
      "Accuracy": null
    },
    "CustomFields": [
      {
        "Label": "Custom Field Label",
        "Value": "Custom Field Value"
      }
    ],
    "CreatedByUserId": null,
    "CreatedDate": null,
    "UpdatedDate": null,
    "UpdatedByUserId": null,
    "AlertProfileIds": [],
    "AutoCompleteHoursDelay": 1,
    "MeanKineticTemperature": null,
    "StandardDeviation": null,
    "DegreeMinutes": null,
    "SharedUrl": null,
    "Carrier": null,
    "ContainerId": null
  },
  "AccountId": 123,
  "DeviceId": "000000000000000000000001",
  "DeviceName": "VD0001",
  "ShipmentId": "Public Shipment Id",
  "PublicShipmentId": null,
  "Location": {
    "Name": null,
    "Latitude": 42.3983903,
    "Longitude": -71.12880539999999,
    "FormattedAddress": "56 Roland Street, Charlestown, Boston, MA 02129, USA",
    "Address": null,
    "LocationMethod": null,
    "Accuracy": {
      "Meters": null,
      "Kilometers": null,
      "Miles": null,
      "Feet": null
    }
  }
}

 

Alert Data Entry 

{
  "EntityName": "VD0001",
  "PlatformAlertUrl": "d/0037002A3734344807353531/alerts/-",
  "PlatformUserPreferencesUrl": "",
  "AlertDate": "2021-02-04T18:54:38Z",
  "RealDate": "2021-02-04T18:54:38Z",
  "AlertName": "Shock",
  "AlertProfileName": "Location Accuracy Test - Webhook",
  "AlertValue": "1",
  "AlertDisplayValue": "1 shock event",
  "RecoveredAlertDisplayValue": null,
  "RecoveredAlertDate": "0001-01-01T00:00:00",
  "AlertType": "ShockEvents",
  "AlertTypeId": 15,
  "TriggerName": "Shock event",
  "TriggerTransition": "",
  "TriggerValue": "YES",
  "TriggerUnit": "",
  "TriggerDetails": "true",
  "Alert": {
    "AccountId": 123,
    "DeviceId": "000000000000000000000001",
    "DeviceName": "VD0001",
    "EntityName": "VD0001",
    "ShipmentId": null,
    "Details": [
      {
        "Value": {
          "ShockCount": 1
        },
        "DateTime": "2021-02-04T18:54:38Z",
        "Reasons": [
          "Created",
          "Closed"
        ],
        "Location": {
          "Name": null,
          "Latitude": 42.380505,
          "Longitude": -71.079871,
          "FormattedAddress": "56 Roland Street, Massachusetts 02129, United States",
          "Address": null,
          "LocationMethod": null,
          "Accuracy": null
        }
      }
    ],
    "AlertType": "ShockEvents",
    "Trigger": {
      "Id": 9638,
      "type": "Shock",
      "Name": "Shock",
      "Description": null,
      "IsEnabled": true,
      "CreatedByUserId": "79a42304-7584-4d9a-866a-bc5107ee40de",
      "CreatedDate": "2021-01-28T21:26:31.34Z",
      "UpdatedDate": "2021-01-29T19:28:04.853Z",
      "UpdatedByUserId": "79a42304-7584-4d9a-866a-bc5107ee40de"
    },
    "AlertProfileId": 5442,
    "AlertTriggerId": 9638,
    "IsClosed": true
  },
  "EntryTimeEpoch": 1612464878000,
  "EntryTimeUtc": "2021-02-04T18:54:38",
  "Cellular": {
    "SignalStrength": "Fair",
    "Dbm": -86
  },
  "Temperature": {
    "Celsius": 23.38445281982422,
    "Fahrenheit": 74.0920181274414
  },
  "Pressure": {
    "Psi": 214.87583923339844,
    "Atmospheric": 14.621435165405273
  },
  "Humidity": {
    "Percentage": 26.359960556030273
  },
  "Weather": {
    "Temperature": {
      "Celsius": 3.3800048828125,
      "Fahrenheit": 38.084007263183594
    },
    "Wind": null
  },
  "Accelerometer": {
    "G": 0.9299999962058119,
    "X": 0,
    "Y": 0,
    "Z": 0.9300000071525574
  },
  "Light": {
    "Lux": 181.15
  },
  "MinLight": {
    "Lux": null
  },
  "MaxLight": {
    "Lux": null
  },
  "Battery": {
    "Percentage": 87,
    "IsCharging": false
  },
  "Shock": {
    "G": 51.48000028834013,
    "X": 51.47999954223633,
    "Y": 0,
    "Z": 0
  },
  "ShockTime": "2021-02-04T18:44:36Z",
  "Shipment": null,
  "AccountId": 123,
  "DeviceId": "000000000000000000000001",
  "DeviceName": "VD0001",
  "ShipmentId": null,
  "PublicShipmentId": null,
  "Location": {
    "Name": null,
    "Latitude": 42.380505,
    "Longitude": -71.079871,
    "FormattedAddress": "56 Roland Street, Massachusetts 02129, United States",
    "Address": null,
    "LocationMethod": "cell",
    "Accuracy": {
      "Meters": 22,
      "Kilometers": 0.022,
      "Miles": 0.01367020020629575,
      "Feet": 72.17847769028872
    }
  }
}

 

Appendix B - Data Entry Properties

Device Data Entry Properties 

Accelerometer.X
Accelerometer.Y
Accelerometer.Z
AccountId
Battery.IsCharging
Battery.Percentage
Cellular.Dbm
Cellular.SignalStrength
DeviceId
DeviceName
EntryTime.Epoch
EntryTime.Utc
EntryTime.FormalUtc
Humidity.Percentage
Light.Lux
Location.Address.Country
Location.Address.Locality
Location.Address.State
Location.Address.Street
Location.Address.Sublocality
Location.Address.ZipCode
Location.FormattedAddress
Location.Latitude
Location.Longitude
Location.Accuracy
Location.Accuracy.Meters
Location.Accuracy.Kilometers
Location.Accuracy.Miles
Location.Accuracy.Feet
Pressure.Atmospheric
Pressure.Psi
ShipmentId
Temperature.Celsius
Temperature.Fahrenheit
Weather.Temperature.Celsius
Weather.Temperature.Fahrenheit
Weather.Wind.Degree
Weather.Wind.Speed

 

Alert Data Entry Properties

Replace <#> with the index of the alert to retrieve. Example Template Variable: {Alert.Details.0.DateTime}

Alert.AccountId
Alert.DeviceId
Alert.DeviceName
Alert.EntityName
Alert.ShipmentId
Alert.AlertType
Alert.AlertProfileId
Alert.AlertTriggerId
Alert.IsClosed
Alert.Trigger.Id
Alert.Trigger.Type
Alert.Trigger.Name
Alert.Trigger.Description
Alert.Trigger.IsEnabled
Alert.Trigger.CreatedByUserId
Alert.Trigger.UpdatedByUserId
Alert.Trigger.CreatedDate
Alert.Trigger.UpdatedDate
# Replace <#> in the following entries with a 0 based index 
# Example: Alert.Details.0.DateTime
Alert.Details.<#>.DateTime
Alert.Details.<#>.Reasons
Alert.Details.<#>.Location.Latitude
Alert.Details.<#>.Location.Longitude
Alert.Details.<#>.Location.FormattedAddress
Alert.Details.<#>.Location.Method
Alert.Details.<#>.Location.Address.Country
Alert.Details.<#>.Location.Address.State
Alert.Details.<#>.Location.Address.Locality
Alert.Details.<#>.Location.Address.Subocality
Alert.Details.<#>.Location.Address.Street
Alert.Details.<#>.Location.Address.ZipCode
Alert.Details.<#>.Location.Accuracy
Alert.Details.<#>.Location.Accuracy.Meters
Alert.Details.<#>.Location.Accuracy.Kilometers
Alert.Details.<#>.Location.Accuracy.Miles
Alert.Details.<#>.Location.Accuracy.Feet
# Depending on alert value
Alert.Details.<#>.Value.Battery.Percentage
Alert.Details.<#>.Value.Battery.IsCharging
Alert.Details.<#>.Value.Connection
Alert.Details.<#>.Value.Humidity.Percentage
Alert.Details.<#>.Value.Light.Lux
Alert.Details.<#>.Value.Pressure.Psi
Alert.Details.<#>.Value.Pressure.Atmospheric
Alert.Details.<#>.Value.MinutesLate
Alert.Details.<#>.Value.HoursStopped
Alert.Details.<#>.Value.ShockCount
Alert.Details.<#>.Value.Temperature.Celsius
Alert.Details.<#>.Value.Temperature.Fahrenheit

Related articles