Import Site Data Using the Trimble Unity Remote Monitoring Historian API

Site data can be imported using the Trimble Unity Remote Monitoring Historian API. When data is imported, it is treated as RAW data and is replaced during each import when any data overlaps. Each imported site can contain up to 20 measurements.

PREREQUISITES:

  • You will need to have the RM - Trend Data Import role assigned to a dedicated user account to be able to import site data using the Trimble Unity Remote Monitoring Historian API. See Manage User Accounts for more information.
  • It is recommended that you also have the All Measurement Types and Groups role assigned to a dedicated user account in order to access any newly created sites and/or measurements. See Manage User Accounts for more information.
  • You will need to acquire the Unity JWT authentication token (also known as the "Authorization" or "Bearer" token) to utilize the Trimble Unity Remote Monitoring Historian API. See Import Site Data Using the Trimble Unity Remote Monitoring Historian API for more information.

NOTE: This topic does not go in-depth with how to perform every API call, but covers the basics. However, see the Telog Web API Help Page for more information and details on the Trimble Unity Remote Monitoring Historian API.

Before you can import or retrieve data using the API, you must complete a few things first, such as:

  • Acquiring or requesting the authentication token
  • You'll need to create a new site or find an existing site
  • Once you have site information, you must create or find existing measurements
  • Once you have measurements, you can add or import trend data information using the API

To request the Unity JWT authentication token, utilize the following information. Please note that this is a short-lived token and expires within 20 minutes. You will need to acquire a new authentication token anytime your existing one expires.

Unity Authentication Token Endpoint
POST https://us.trimbleunity.com/unity/tokens
Copy
Body of Request
{
    "tenant": "SampleTenantId",
    "username": "SampleUsername",
    "password": "SamplePassword"
}

The expected response is only the bearer token will be used in the Authorization header in later requests.

NOTE: The tenant identifier is not the organization for the user but will be viewable at the bottom of the menu and near the version numbers.

Once the authentication token is configured, you can create a new site.

You can create a new site by using a sequence of commands. There is some information that is required, such as the name of the site, but other information can be added as desired.

  1. Use the following URL to call the API from: https://api.telogdhs.net.

NOTE: If you have an on-premise installation and Telog Enterprise, you will need to use your local API instance as the URL instead of the public-shared Trimble Unity site URL.

  1. When creating a new site, you must give the site a name.

Here is an example of a new site being created using Postman and JSON, and the default fields and values returned when the API call is made.

See Retrieve Data Using the Trimble Unity Remote Monitoring Historian API for more information on finding an existing site. Once a site is created or you have found an existing site, you can create new or find existing measurements.

You can create a new measurement by using a sequence of commands. There is some information that is required, such as the site the measurement will be added to, the name of the measurement, and the unit ID. However, other information can be added as desired.

  1. Use the following URL to call the API from: https://api.telogdhs.net.

NOTE: If you have an on-premise installation and Telog Enterprise, you will need to use your local API instance as the URL instead of the public-shared Trimble Unity site URL.

  1. Use the site where you want the new measurement created. This is required because when the API call is made to create the site and retrieve data, it needs to know which site to write and read the information from.
  2. When creating a new measurement, you must include the following information:
  • a name
  • unit ID

Here is an example of a new measurement being created using Postman and JSON, and the default fields and values returned when the API call is made.

  1. Repeat the process for each new measurement you want to create.

NOTE: Once you've created new measurements, you'll need to edit the measurement in Trimble Unity to define fields, such as the Units field, to use the values you want. See Create and Manage Measurement Types for more information.

See Retrieve Data Using the Trimble Unity Remote Monitoring Historian API for more information on finding existing measurements.

You can add information, such as trend data, to measurements.

  1. Use the following URL to call the API from: https://api.telogdhs.net.

NOTE: If you have an on-premise installation and Telog Enterprise, you will need to use your local API instance as the URL instead of the public-shared Trimble Unity site URL.

  1. Use the site where you want the new measurement created. This is required because when the API cal is made to create the site and retrieve data, it needs to know which site to write and read the information from.
  2. Use the measurement name you want to add trend data to.
  3. Add data, such as a time stamp, interval length, and the average duration. You can also add a minimum and maximum duration if you want.

Here is an example of trend data being added to a measurement using Postman and JSON, and the fields and values returned when the API call is made.