Overview

The rest of this document describes the Tive Public API v2.

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
• 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).

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
• 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"
    ],
    "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 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 our Tive Client Support team 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”