Skip to main content
Table of Contents

TAHMO Server API

Documentation for the ZENTRA Cloud API.

Travis Bates
Updated by Travis Bates

This article details where and how to use the documentation for the TAHMO server API.

TAHMO Server

Swagger https://tahmo.zentracloud.com/api/v4/documentation/

v4 of the ZENTRA Cloud API is now available for production. METER recommends new clients start with v4. Existing clients can switch to using v4 if they encounter issues with pagination in v3. Both v3 and v4 support queries for ATMOS 41W, ZL6, EM60G and EM50G devices. The documentation for v3 and v4 is the same, users can simply change the version number in the endpoint URL from "v3" to "v4".
Call Limits:
Users are limited to a total of 60 calls per minute(60sec), and each device is limited to 1 call per minute(60sec). One user can make 60 calls to 60 different devices in a 60 second period.
Units:
To set the units, log in to your account at zentracloud.com and click the wrench icon from the main menu, and select Measurement Units. Edit your preferred units and click Accept. See the Setting your preferred measurement units article here.

How to start

  • Sign up at tahmo.zentracloud.com if you haven't got your ZENTRA API key yet.
  • Select API from the main menu.
  • On the Keys tab click Copy token.

Run a test

  • Navigate to the API v4 Swagger documentation
  • Select Authorize.
  • Paste your token ID.
  • Click Authorize.

GET

To view an example, press the GET readings button.

Parameters

Experiment with different start_date, end_date, or start_mrid and end_mrid query parameters. Only start_date and end_date or start_mrid and end_mrid parameters need to be defined in the request, not both. MRID stands for "Measurement Record ID" and increases as the number of records on the device increases.

device_sn

string

(query)

The serial number of the device having data requested. z6-12345

start_date

string ($date)

(query)

Start date of time range. Defaults to date of first reading of device. Overrides start_mrid. 2025-07-01 00:00

end_date

string ($date)

(query)

End date of time range. Defaults to date of last reading of device. Overrides end_mrid. 2025-07-31 23:59

start_mrid

integer

(query)

Start mrid of mrid range. Defaults to mrid of first reading from Device. 3500

end_mrid

integer

(query)

End mrid of mrid range. Defaults to mrid of last reading from Device. 3800

output_format

string

(query)

The data structure of the response content. Defaults to json. Other options include pandas dataframe and csv. json, df, csv

page_num

integer

(query)

Page number. Defaults to 1. 2

per_page

integer

(query)

Number of readings per page. Defaults to 500. Max is 2000. 1000

device_depth

boolean

(query)

When set to true, the API will return the sensor depth as part of the device metadata payload. true

sort_by

string

(query)

Sort the readings in ascending or descending order. Defaults to descending. ascending, descending

Examples

View examples in json, csv or pandas Dataframe.

Example Code Snippet

Copy the code snippet below, then edit the token tok, device serial number sn, and start and end dates start_date , end_date .

import requests # pip install requests
import pandas # pip install pandas


def get_with_credentials(tok, uri, **kwargs):
    # just in case we forget to put "Token MyToken"
    token = tok if tok.lower().startswith("token") else f"Token {tok}"
    headers = {"Authorization": token}
    return requests.get(uri, headers=headers, **kwargs)


def get_readings_response(sn, start_date, end_date, **extra_kwargs_for_endpoint):
    server = extra_kwargs_for_endpoint.get("server", "https://zentracloud.com")
    url = f"{server}/api/v4/get_readings/"

    default_args = {
        'output_format': "df",
        'per_page': 1,
        'page_num': 1,
        'sort_by': 'desc',
        'start_date': start_date,
        'end_date': end_date
    }
    data = {**default_args, **extra_kwargs_for_endpoint, "device_sn": sn}
    tok = extra_kwargs_for_endpoint.pop("token", "")
    return get_with_credentials(tok, url, params=data)

def get_readings_dataframe(sn,start_date,end_date,**extra_kwargs_for_endpoint):
    res = get_readings_response(sn,start_date,end_date,**extra_kwargs_for_endpoint)
    if(res.ok):
        data = res.json()
        return pandas.DataFrame(**json.loads(data["data"]))
    return res

#fill in your token, device serial number and start and end dates here.
tok = "Token <Your Token>"
sn="z6-#####"
start_date="2024-04-01 00:00:00"
end_date="2024-04-02 00:00:00"

#specify the server here.
server="https://tahmo.zentracloud.com"
df = get_readings_dataframe(sn, start_date, end_date, token=tok, server=server)
print(df)

How did we do?

EU Server API

Push API

Contact