API Reference Edit
ControlTec’s API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Authentication Edit
The API uses JSON Web Tokens (JWT) for authentication. Each request to the API must include a valid JWT in the Authorization header. The token should be prefixed with Bearer followed by a space.
Obtaining a JWT
To obtain a JWT, go to www.AS20z.com and login to user account. Navigate to the “User” page from the breadcrumbs at the top of the page and find your username. Click the 3-dot dropdown icon left of your name and select “Token”. On the popup, click create to obtain your token or copy an existing token if one has already been created for your user.
If you do not have an account on www.AS20z.com, contact ControlTec directly to have an account or JWT created.
Using the JWT
Once you have obtained a JWT, you should include it in the Authorization header of all subsequent requests to the API.
For example, to get a list of sites, you would send a GET request to the /sites endpoint with the following headers:
Authorization: Bearer YOUR_JWT_TOKEN
Token expiration
JWT tokens are valid for a limited time. If a token expires, the API will return a 401 Unauthorized response. In this case, you will need to obtain a new JWT, repeat the steps above and create a new token.
Nothing will work unless you include this JWT
Errors Edit
The API uses standard HTTP status codes to indicate success or failure of a request. In addition to the HTTP status code, the API may return additional error information in the response body.
Error Responses
Error responses will be returned in JSON format with a specific format that includes a code and message field. The code field will be a unique identifier for the error, and the message field will provide a short description of the error.
| Code | Name | Description |
|---|---|---|
| 200 | OK | Success |
| 400 | Bad Request | We could not process that action |
| 403 | Forbidden | You do not have proper access for this request |
| 500 | Internal Server Error | Cannot parse argument of type None |
{
"detail": "403 Forbidden: You dont have access to the requested resource",
"status": 403,
"title": "Forbidden"
}
/regions Edit
Retrieves a list of all regions assigned to sites within an account.
Parameters
- account_oid
- The account_oid to filter the results by. This parameter is optional.
This call will return all regions for an account. If regions have not been assigned it will return one region labelled “None”.
curl -X 'GET' \
'https://www.as20z.com:9900/api/v1.0/regions?account_oid=YOUR ACCOUNT_OID' \
-H 'accept: application/json' \
-H 'Authorization: Bearer YOUR JWT TOKEN'
[
{
"account_oid": "5c814c135b11884e70e8643c",
"region_desc": "Example Description 1",
"region_info": "Example Info 1",
"region_name": "Example Name 1",
"region_oid": "6g814c159doe884e70e8643c ",
"site_count": 100
},
{
"account_oid": "5c814c135b11884e70e8643c",
"region_desc": "Example Description 2",
"region_info": "Example Info 2",
"region_name": "Example Name 2",
"region_oid": "6g814c159doe884e70e8643c ",
"site_count": 60
},
...
]
/sites Edit
Retrieve a list of sites
Parameters
- account_oid
- The account_oid to filter the results by. This parameter is optional.
- region_oid
- The region_oid to filter the results by. This parameter is optional.
If account_oid or region_oid parameters are not provided, all sites will be returned.
curl -X 'GET' \
'https://www.as20z.com:9900/api/v1.0/sites?account_oid=YOUR_ACCOUNT_OID' \
-H 'accept: application/json' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'
[
{
"_id": "5c814c135b11884e70e8643c",
"site_location": "Example Address 1",
"site_name": "Example Name 1"
},
{
"_id": "5c814c135b54584e70e8643c",
"site_location": "Example Address 2",
"site_name": "Example Name 2"
},
...
]
/device_data Edit
Retrieve all data by device for a specified site and timeframe
Parameters
- site_oid
- String. The site_oid to filter the results by. This parameter is REQUIRED.
- time_period
- String. Must be "days_ago", "weeks_ago", or "months_ago". This parameter is optional
- time_period_length
- Integer. Corresponds with time_period specified. Example: If time_period = days_ago and time_period_length = 1, data for 1 day ago will be returned
- start_timestamp
- String. Desired start time in ISO date format.
- end_timestamp
- String. Desired end time in ISO date format.
Receive timestamped data for every device in the specified site. The request will return the following data points for each individual device/controller:
- case_temp: internal case temperature (optional sensor)
- dew_point: dew point reading from humidity sensor, typically mounted directly above doors
- door_temp: temperature sensor; typically mounted to mullion or bottom rail of case (also called frame temperature)
- humidity: humidity directly outside of case
- room_temp: temperature directly outside of case
- htr_relay_on: relay state for AS-20z controller
If neither timeframe parameter is included, it will return the last hour of data for the specified site
dev_type “F1” specifies an AS-20z controller
case_type specifies the type of case. “Freezer” is a low temp case, “Cooler” is a medium/normal temp case
If case_temp is not returned, no case temp sensor is installed on that case
Data can only be pulled for time periods of 24 hours or less
curl -X 'GET' \
'https://www.as20z.com:9900/api/v1.0/sites/YOUR_SITE_OID/device_data?start_timestamp=2022-10-10T10&end_timestamp=2022-10-10T11' \
-H 'accept: application/json' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'
{
"device_count": 46,
"devices": [
"case_type": "freezer",
"dev_type": "F1",
"device_data": {
"case_temp": [
{
"timestamp": "2022-10-10T10:00:00-06:00",
"value": 38.0
},
{
"timestamp": "2022-10-10T10:15:00-06:00",
"value": 38.0
},
{
"timestamp": "2022-10-10T10:30:00-06:00",
"value": 38.0
},
{
"timestamp": "2022-10-10T10:45:00-06:00",
"value": 38.0
}
],
"dew_point": [
{
"timestamp": "2022-10-10T10:00:00-06:00",
"value": 34.0
},
{
"timestamp": "2022-10-10T10:15:00-06:00",
"value": 34.0
},
{
"timestamp": "2022-10-10T10:30:00-06:00",
"value": 34.0
},
{
"timestamp": "2022-10-10T10:45:00-06:00",
"value": 33.0
}
],
"door_temp": [
{
"timestamp": "2022-10-10T10:00:00-06:00",
"value": 50.0
},
{
"timestamp": "2022-10-10T10:15:00-06:00",
"value": 50.0
},
{
"timestamp": "2022-10-10T10:30:00-06:00",
"value": 50.0
},
{
"timestamp": "2022-10-10T10:45:00-06:00",
"value": 50.0
}
],
"htr_relay_on": [
{
"timestamp": "2022-10-10T10:00:00-06:00",
"value": 0.3
},
{
"timestamp": "2022-10-10T10:15:00-06:00",
"value": 0.5
},
{
"timestamp": "2022-10-10T10:30:00-06:00",
"value": 0.4
},
{
"timestamp": "2022-10-10T10:45:00-06:00",
"value": 0.2
}
],
"humidity": [
{
"timestamp": "2022-10-10T10:00:00-06:00",
"value": 40.0
},
{
"timestamp": "2022-10-10T10:15:00-06:00",
"value": 40.0
},
{
"timestamp": "2022-10-10T10:30:00-06:00",
"value": 40.0
},
{
"timestamp": "2022-10-10T10:45:00-06:00",
"value": 40.0
}
],
"room_temp": [
{
"timestamp": "2022-10-10T10:00:00-06:00",
"value": 58.0
},
{
"timestamp": "2022-10-10T10:15:00-06:00",
"value": 58.0
},
{
"timestamp": "2022-10-10T10:30:00-06:00",
"value": 58.0
},
{
"timestamp": "2022-10-10T10:45:00-06:00",
"value": 58.0
}
]
},
"loc_uuid": "EXAMPLE loc_uuid",
"location": "Physical Location of Device",
"mac_addr": "DEVICE MAC ID"
},
...
}
],
"end_date": "2022-10-10T11:00:00-06:00",
"site_location": "Example Site Address",
"site_name": "Example Site Name",
"site_oid": "YOUR_SITE_OID",
"site_timezone": "MST7MDT",
"start_date": "2022-10-10T10:00:00-06:00"
}
/last_device_data Edit
Retrieve the last reading for every device of the specified site
Parameters
- site_oid
- String. The site_oid to filter the results by. This parameter is REQUIRED.
Receive timestamped data for every device in the specified site. The request will return the following data points for each individual device/controller:
- case_temp: Internal Case Temperature (Optional Sensor)
- dew_point: dew point reading from sensor typically mounted directly above doors
- door_temp: temperature sensor typically mounted to mullion or bottom rail of case (also called frame temperature)
- humidity: humidity directly outside of case
- room_temp: temperature directly outside of case
- htr_relay_on: relay state for AS-20z controller
dev_type “F1” specifies an AS-20z controller
case_type specifies the type of case. “Freezer” is a low temp case, “Cooler” is a medium/normal temp case
If case_temp is not returned, no case temp sensor is installed on that case
If the device has never reported data, device_data and device_metadata will be empty
curl -X 'GET' \
'https://www.as20z.com:9900/api/v1.0/sites/YOUR_SITE_OID/last_device_data' \
-H 'accept: application/json' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'
{
"site_timezone": "PST8PDT",
"site_oid": "YOUR SITE_OID",
"device_count": # of Devices in Store,
"site_location": "EXAMPLE SITE ADDRESS",
"devices": [
{
"device_data": {
"door_temp": [
{
"value": 49,
"timestamp": "2021-01-01T00:59:00-08:00"
}
],
"clq": [
{
"value": 25,
"timestamp": "2021-01-01T00:59:00-08:00"
}
],
"room_temp": [
{
"value": 69,
"timestamp": "2021-01-01T00:59:00-08:00"
}
],
"dew_point": [
{
"value": 43,
"timestamp": "2021-01-01T00:59:00-08:00"
}
],
"nlq": [
{
"value": 30,
"timestamp": "2021-01-01T00:59:00-08:00"
}
],
"humidity": [
{
"value": 40,
"timestamp": "2021-01-01T00:59:00-08:00"
}
],
"htr_relay_on": [
{
"value": 0,
"timestamp": "2021-01-01T00:59:00-08:00"
}
]
},
"loc_uuid": "801593dd-a20e-5300-98d6-82136614238b",
"mac_addr": "00158D0000993D54",
"case_type": "freezer",
"dev_type": "F1",
"location": "EXAMPLE LOCATION 1",
"device_metadata": {}
},
{
"device_data": {},
"loc_uuid": "2160d221-34cf-50d6-a139-1862ares93c2",
"mac_addr": "00158D00004579B1",
"case_type": "freezer",
"dev_type": "F1",
"location": "EXAMPLE LOCATION 2",
"device_metadata": {}
},
{
"device_data": {
"door_temp": [
{
"value": 44,
"timestamp": "2021-01-01T00:59:00-08:00"
}
],
"clq": [
{
"value": 28,
"timestamp": "2021-01-01T00:59:00-08:00"
}
],
"dew_point": [
{
"value": 43,
"timestamp": "2021-01-01T00:59:00-08:00"
}
],
"room_temp": [
{
"value": 67,
"timestamp": "2021-01-01T00:59:00-08:00"
}
],
"nlq": [
{
"value": 28,
"timestamp": "2021-01-01T00:59:00-08:00"
}
],
"humidity": [
{
"value": 42,
"timestamp": "2021-01-01T00:59:00-08:00"
}
],
"htr_relay_on": [
{
"value": 1,
"timestamp": "2021-01-01T00:59:00-08:00"
}
]
},
"loc_uuid": "d7c3ed69-177a-5391-b33d-7bd64fds25aa",
"mac_addr": "00158D000014598F",
"case_type": "freezer",
"dev_type": "F1",
"location": "EXAMPLE LOCATION 3",
"device_metadata": {}
}
],
"site_name": "EXAMPLE SITE NAME"
}
/efficiency_data Edit
Retrieve efficiency and savings data for each device and total for a specified site
Parameters
- site_oid
- String. The site_oid to filter the results by. This parameter is REQUIRED.
- time_period
- String. Must be "days_ago", "weeks_ago", or "months_ago". This parameter is optional
- time_period_length
- Integer. Corresponds with time_period specified. Example: If time_period = days_ago and time_period_length = 1, data for 1 day ago will be returned
- start_timestamp
- String. Desired start time in ISO date format.
- end_timestamp
- String. Desired end time in ISO date format.
Receive timestamped efficiency and savings data for every device in the specified site and the total site efficiency and savings. The request will return the following efficiency data points for each individual device/controller plus the total site efficiency for the specified timeframe:
- time_off: the amount of time (seconds) the heaters were off
- time_on: the amount of time (seconds) the heaters were on
- efficiency: the % of time heaters were turned off
- kwh_saved: the number of kwh saved
- room_temp: temperature directly outside of case
- savings: the dollar amount saved
If neither timeframe parameter is included, you will receive a 500 error. One timeframe parameter must be specified
If only start_timestamp is specified, 1 day of data will be returned starting at the specified time
If only end_timestamp is specified, 1 day of data prior to the specified time will be returned
dev_type “F1” specifies an AS-20z controller
case_type specifies the type of case. “Freezer” is a low temp case, “Cooler” is a medium/normal temp case
curl -X 'GET' \
'https://www.as20z.com:9900/api/v1.0/sites/YOUR_SITE_OID/efficiency_data?start_timestamp=2020-07-07' \
-H 'accept: application/json' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'
{
"account_name": "EXAMPLE ACCOUNT NAME",
"devices": [
{
"case_type": "freezer",
"dev_type": "F1",
"door_count": 5,
"door_rating": 1.25,
"efficiency": 0.512,
"time_off": 44208.8,
"time_on": 42191.2,
"kwh_saved": 11.208772833333335,
"loc_uuid": "03b487e0-0b47-5cb5-b147-54aec91e2746",
"location": "EXAMPLE LOCATION 1",
"mac_addr": "00158D0000997WE5",
"off_time": 38928.3,
"savings": 1.23
},
{
"case_type": "freezer",
"dev_type": "F1",
"door_count": 3,
"door_rating": 1.25,
"efficiency": 0.43,
"time_off": 37141.9,
"time_on": 49258.1,
"kwh_saved": 5.650211537500001,
"loc_uuid": "0e48er8f-c7d5-5c43-9058-0f96130d59c5",
"location": "EXAMPLE LOCATION 2",
"mac_addr": "00158D0000999V8A",
"savings": 0.62
},
...
}
]
"end_date": "2020-07-08T00:00:00+00:00",
"time_on": 847644.7,
"generated_date": "2021-01-15T17:52:25.741600+00:00",
"site": {
"efficiency": 0.5540589751683502,
"time_off": 1053155.3,
"kwh_saved": 290.0800957866667,
"period_seconds": 86400,
"savings": 31.9
},
"site_elec_cost": 0.11,
"site_location": "EXAMPLE SITE ADDRESS",
"site_name": "EXAMPLE SITE NAME",
"site_oid": "5e5d25b05b11884r80e8648a",
"start_date": "2020-07-07T00:00:00+00:00"
}