Retrieve Data Using the Trimble Unity Remote Monitoring Historian API

Historical site data can be retrieved using the Trimble Unity Remote Monitoring Historian API. Once retrieved, this data can be imported into a third party system, used for billing purposes, merged with other data to create comprehensive reports, and for numerous other reasons.

PREREQUISITES:

  • The Trimble Unity Remote Monitoring Historian API license has been enabled for your Trimble Unity tenant. See View Subscriptions for more information.
  • You will need to have a user account to be able to retrieve site data using the Trimble Unity Remote Monitoring Historian API. See Manage User Accounts for more information.
  • You may assign permission policies to the user account to restrict access to specific sites and measurements. See Create and Manage Permission Policies on page 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 Acquire the Authentication Token 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 determine the ID of the measurement you wish to retrieve data from
  • Once you have a measurement ID, you can request the measurement’s data

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 retrieve a site.

You can look up a monitoring site and retrieve its ID using the api/sites endpoint.

  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. In the following example, the Postman placeholder {{telogapi}} contains this URL.

  1. To find an existing site, use sites endpoint and GET command. By including parameters, such as the site name, you can narrow down your search results.

Here is an example of finding an existing site that has a name starting with hpr using Postman and JSON.

Once you have found an existing site, you can retrieve its measurements using the site ID. In this example, the site ID returned is 284.

You can look up a measurement and retrieve its ID using the api/measurements endpoint.

  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. In the following example, the Postman placeholder {{telogapi}} contains this URL.

  1. To find an existing measurement, use measurements endpoint and GET command. By including parameters, such as the measurement name, you can narrow down your search results.

Here is an example of finding an existing measurement that belongs to the site with ID 284 and has the name pressure using Postman and JSON.

Once you have found an existing measurement, you can retrieve its data using the measurement ID. In this example, the measurement ID returned is 947.

  1. Repeat the process for each measurement you want to retrieve data for.

You can retrieve trend data with a measurement ID using the api/measurements/measurementid/data endpoint. The API will limit the amount of data returned in a single call. Refer to the API’s online documentation for details about how paging works.

  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. In the following example, the Postman placeholder {{telogapi}} contains this URL.

  1. To retrieve measurement data, use the TrendData endpoint and GET command. By including parameters, such as start, end, and last, you can limit the amount of data returned.

Here is an example of retrieving data from December 1, 2022 for measurement 947 using Postman and JSON. In this example, the start and end times are expressed in GMT-5 for the U.S. Eastern time zone.

Here is an example of retrieving the most recent or available, hours' worth of data for measurement 947 using Postman and JSON. In this example, we use the last parameter to request the most recent 3,600 seconds or one hour of data.