Trimble Unity Remote Monitoring Historian API Help Page

All data requests require a valid access token to authenticate the user. A token can be requested by making a request to the http://api.telogdhs.net/Token endpoint. The example below shows the request necessary to authenticate as "SampleUser" with a password of "pass$123". The user and password values must be url-encoded as shown in the password value where the '$' character is replaced with '%24'.

The expected response to the example request is as follows:

{
    "access_token": "{alphanumeric token}",
    "token_type": "bearer",
    "expires_in": 1209600,
    "userName": "SampleUser",
    ".issued": "2024-11-21T06:41:09+00:00",
    ".expires": "2024-12-05T06:41:09+00:00"
}

The rest of the API is available to be used by specifying the recived access_token in all subsequent request headers as follows:

Authorization: Bearer {alphanumeric token}

The includes format changes the response format of the API and allows multiple related requests to be combined into a single request to reduce the chattiness of the API. It is enabled by appending ";format=include" to the "Accept" http header of each request.

Accept: application/json;format=include

For example, if one wanted to request information for a site and each of its measurements the request would be:

http://api.telogdhs.net/api/sites/1?include=measurements

The structure of each response from the API will change when using this format to accommodate the new functionality. Instead of just an array or single item response, there are four new sections:

Data Sample

{
    "data": {
        "id": 1,
        "name": "Site 1",
        "userField1": "",
        "userField2": "",
        "userField3": "",
        "userField4": "",
        "userField5": "",
        "notes": "",
        "timeZoneId": 16,
        "x": "",
        "y": "",
        "z": "",
        "status": "Active",
        "typeName": "Default",
        "isInactive": false,
        "alarmActive": false
    }
}

This section contains the default response format information.

Linked Sample

{
    "linked": {
        "measurements": {
            "relationKeys": [
                "id"
            ],
            "relations": {
                "1": [
                    "1",
                    "2",
                    "3",
                ]
            },
            "models": {
                "1": {
                    "id": 1,
                    "siteId": 1,
                    "name": "Flow",
                    "unitId": 28,
                    "typeId": 16,
                    "compressionMethod": 2,
                    "notes": "test",
                    "eventOnIndicator": 0,
                    "isHidden": null,
                    "isAutoCalculated": null,
                    "isRaw": true,
                    "isAsync": false,
                    "color": "#FFFFFF"
                },
                "2": {
                    "id": 2,
                    "siteId": 1,
                    "name": "Level",
                    "unitId": 2,
                    "typeId": 18,
                    "compressionMethod": 2,
                    "notes": "",
                    "eventOnIndicator": 0,
                    "isHidden": null,
                    "isAutoCalculated": null,
                    "isRaw": true,
                    "isAsync": false,
                    "color": "#FFFFFF"
                },
                "3": {
                    "id": 3,
                    "siteId": 1,
                    "name": "Velocity",
                    "unitId": 16,
                    "typeId": 17,
                    "compressionMethod": 2,
                    "notes": "",
                    "eventOnIndicator": 0,
                    "isHidden": null,
                    "isAutoCalculated": null,
                    "isRaw": true,
                    "isAsync": false,
                    "color": "#FFFFFF"
                }
            }
        }
    }
}

This section contains all requested related objects in a hierarchical dictionary structure. The first level of this structure is keyed on the keywords specified in the "include" url parameter ("measurements" in the above example). For each keyword there are three sections:

• relationKeys - An array of field names from the original object that are used to uniquely identify the object
• relations - A dictionary that provides the relationship of original objects to related objects
• Each of the original objects will only appear as keys here if they have related objects specified in the models section
• If the relationKeys section has multiple keys specified, the key will be built as a '|' separated list of field values in the order specified (i.e. "1|2")
• The array of values for each original object key directly represents the keys to use when reading from the models section
• models - A distinct dictionary of each related object keyed based on their unique identifier fields

Links Sample

{
    "links": [
        {
            "href": "api/sitetypes/{siteTypeName}",
            "method": "GET",
            "rel": "sitetypes"
        },
        {
            "href": "api/measurements/{measId:int:min(1)}",
            "method": "GET",
            "rel": "measurements"
        },
        {
            "href": "api/groups/{groupId:int:min(1)}",
            "method": "GET",
            "rel": "groups"
        },
        {
            "href": "api/timezones/{timeZoneId:int:min(1)}",
            "method": "GET",
            "rel": "timezones"
        }
    ]
}

This section contains a list of all potential object types that can be included with the root request. Each link section consists of the following:

• href - A link model to the object source
• method - The HTTP method used when requesting the object source
• ref - The keyword to be used as part of the include url parameter

Paging Sample

http://api.telogdhs.net/api/sites?pageSize=5&page=3

{
    "paging": {
        "totalCount": 1078,
        "pageCount": 216,
        "currentPage": 3,
        "pageSize": 5,
        "firstPage": {
            "href": "/TWA/api/sites?pagesize=5&page=1",
            "method": "GET",
            "rel": "first"
        },
        "prevPage": {
            "href": "/TWA/api/sites?pagesize=5&page=2",
            "method": "GET",
            "rel": "prev"
        },
        "nextPage": {
            "href": "/TWA/api/sites?pagesize=5&page=4",
            "method": "GET",
            "rel": "next"
        },
        "lastPage": {
            "href": "/TWA/api/sites?pagesize=5&page=216",
            "method": "GET",
            "rel": "last"
        }
    }
}

This section is optional and will only appear if there are too many objects in the data section to be provided in a single response. The contents are as follows:

• totalCount - The total number of objects across all pages
• pageCount - The total number of pages
• currentPage - The page number of the current response
• pageSize - The maximum number of items that can appear in a single page
• firstPage/prevPage/nextPage/lastPage - The link information for the first, previous, next, and last pages (not all links will be shown depending on the current page)

Appending the "sortby" url parameter to any GET request that returns a list of items will allow one to sort the result set. The sortby parameter supports multiple fields specified as a comma-delimited list and will sort in the order in which the fields are specified. Additionally, the direction of sorting can be reversed on any field by prefixing the field name with a "-" character.

For example, the following query requests all sites sorted first by descending typeName and then by name:

http://api.telogdhs.net/api/sites?sortby=-typeName,name

Each field in an object can be specified as a url parameter to filter the result set of the endpoint that provides that object. For example, if one wanted to find all sites with names that contained "rain" the following query could be used:

http://api.telogdhs.net/api/sites?name=rain

Additionally, multiple fields can also be specified to filter a result set further. The following request finds all site with names that contain "rain" and have a timeZoneId of "16":

http://api.telogdhs.net/api/sites?name=rain&timeZoneId=16

The default comparison for a non-text fields is the equality check. This behavior can be modified by specifying a tag for any field like so:

• gt - Greater Than
• lt - Less Than
• gte - Greater Than or Equal
• lte - Less Than or Equal
• ne - Not Equal

For text fields, the default comparison is 'contains'. This can be modified using similar tags as follows (all comparisons are case insensitive):

• eq - Equals
• neq - Not Equals
• nc - Not Contains ([ne] is synonymous with this)
• sw - Starts With
• ew - Ends With

String fields are handled differently than other fields as the default is a contains check and the only alternative comparison is "ne" which behaves as a does not contain.

The following are some examples of utilizing the alternate filter parameters:

All sites that do not have "rain" in the name field

http://api.telogdhs.net/api/sites?name[ne]=rain

All sites whose id is greater than 5 and less than or equal to 20

http://api.telogdhs.net/api/sites?id[gt]=5&id[lte]=20

The following url parameters are available for paging control:

• page - Specifies which page to load
• pageSize - Overrides the default page size