This can be used to get the 300 most recent readings of current readings graph data from compatible devices that are being managed with T&D WebStorage Service.
https://api.webstorage-service.com/v1/devices/latest-data-rtr500
Read-Only ID is also possible.
* This API cannot be used when transferring data via FTP from RTR500B Series Base Units.
* This API cannot be used if the Base Unit is an RTR500BC.
60 requests per allotted 1-minute span
We set this rate limit to allow for the retrieval of the most recent few minutes of recorded data every minute from around ten devices recording and uploading data to T&D WebStorage Service at 1-minute intervals.
The rate limit itself is designed to avoid concentrated access during a short period of time and balance out the load. Please be aware of this before using.
| Item Name | Value |
|---|---|
| HTTP Method | POST |
| X-HTTP-Method-Override | GET |
| Host | api.webstorage-service.com:443 |
| Content-Type | application/json |
| Parameter Name | Format | Required | Default Value | Details |
|---|---|---|---|---|
| api-key | string(45 characters) | Yes | --- | Already acquired API Key |
| login-id | string(8 characters) | Yes | --- | User ID Read-Only ID is also possible. |
| login-pass | string(4-16 characters) | Yes | --- | The password for the above User ID. |
| remote-serial | string(8 characters) | Yes | --- | Device Serial Number of the device from which graph data will be extracted. Not possible to select more than one unit at a time. (*1) |
| base-serial | string(8 characters) | Yes | --- | Serial Number of the Base Unit to which the above Remote Unit is registered. Not possible to select more than one unit at a time.(*2) |
| type | string( json/csv/csv2 ) | json | These are the formats in which graph data can be received. Select either json format or csv format.(*3) | |
| temperature-unit | string(device/C/F) | device | This can be used to specify the temperature units used when retrieving recorded data. [device] : Values will be returned as per the units set in the device. (default) [C] : Values will be returned in Celsius. [F] : Values will be returned in Fahrenheit. |
(*1) Remote Units in the RTR-500 series and RTR500B series can be specified.
(*2) Only RTR500BW/RTR500BM can be specified. (This API cannot be used if the Base Unit is an RTR500BC.)
(*3) If type=csv is set, json_encoded values will be returned in CSV format. Set type=csv2 to get the response in the same format as the Response Example (CSV format). Note that "type=csv" will be deprecated on Nov. 1, 2024.
Request Header
POST /v1/devices/latest-data-rtr500 HTTP/1.1 Host: api.webstorage-service.com:443 Content-Type: application/json X-HTTP-Method-Override: GET
Request Body
{
"api-key":"73pfobnche8d1p6laqnemsbnpkght3bjv047oid6p2sg3",
"login-id":"tbzz9999",
"login-pass":"ppaasswwoorrdd",
"remote-serial":"52BA0001",
"base-serial":"58580001"
}
*In this example, the most recent 300 readings of current readings graph data from the RTR-502(sn:52BA0001) which was registered to the RTR500BW(sn:58580001) was retrieved in json format.
This is an example of request using the curl command, which is available from the command line on Windows and Mac devices.
The example command includes request header and request body.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-HTTP-Method-Override: GET" \
-d '{"api-key":"73pfobnche8d1p6laqnemsbnpkght3bjv047oid6p2sg3","login-id":"tbzz9999","login-pass":"ppaasswwoorrdd","remote-serial":"52BA0001","base-serial":"58580001"}' \
https://api.webstorage-service.com:443/v1/devices/latest-data-rtr500
| Item Name | Value | Details |
|---|---|---|
| HTTP status code | (**) | HTTP Status Code |
| Content-Type | application/json; charset=utf-8 text/csv; charset=utf-8 | The format will be changed according to the specified format, either JSON or CSV. (Character code is UTF-8) |
| X-RateLimit-Limit | (integer) | Maximum number of requests per allotted time span |
| X-RateLimit-Reset | (integer) | Number of seconds in the allotted time span |
| X-RateLimit-Remaining | (integer) | Remaining number of requests per allotted time span |
(**) If the HTTP status code is “200”, then the process has been completed successfully. If any other HTTP status code is returned, then an error has occurred and processing was not completed. As shown below, if an error does occur, JSON data with the error info included will be returned.
HTTP/1.1 400 Bad Request
Server: api.webstorage-service.com
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 60
X-RateLimit-Reset: 60
X-RateLimit-Remaining: 57
{
"error":{
"code": error code,
"message": "error details"
}
}
In the following, when an item name includes a period (.) as in “channel.name”, this indicates that the elements of the array are included in the item, in this case “channel”.
| Item Name | Format | Details |
|---|---|---|
| remote-serial | string | Serial Number of Selected Remote Unit |
| remote-model | string | Model Name of Selected Remote Unit |
| remote-name | string | Device Name of Selected Remote Unit |
| base-serial | string | Serial Number of Selected Base Unit |
| base-model | string | Model Name of Selected Base Unit |
| base-name | string | Device Name of Selected Base Unit |
| time-diff | string(*1) | Device Time Difference Info [in units of minutes] shown here. If it is a Remote Unit, then the time difference info will be that set in Base Unit to which it is registered. |
| std-bias | string(*1) | Device Time Difference from Standard [in units of minutes] shown here. If it is a Remote Unit, then the time difference from standard info will be that set in Base Unit to which it is registered. |
| dst-bias | string(*1) | Device Time Difference during Daylight Savings Time [in units of minutes] shown here. If it is a Remote Unit, then the time difference during daylight savings time info will be that set in Base Unit to which it is registered. |
| channel | Array | Measurement Channel Info shown here. If the device selected does not include sufficient data, it may result in an empty array. |
| channel.name | string | Channel Name (*2) |
| channel.num | string(*1) | Channel Number (1~4) (*3) |
| channel.unit | string | Unit of Measurement for Channel (*4) |
| data | Array | If the number of data readings is "0”, then the array is blank. |
| data.unixtime | string(*1) | unixtime of graph data |
| data.data-id | string(*1) | data-id of graph data (*5) |
| data.ch1 | string(*1)(*6) | The value for ch1(*7) for the above unixtime. |
| data.ch2 | string(*1)(*6) | The value for ch2(*7) for the above unixtime. This will not exist, if the device has no ch2 measurement. |
| data.ch3 | string(*1)(*6) | The value for ch3(*7) for the above unixtime. This will not exist, if the device has no ch3 measurement. |
| data.ch4 | string(*1)(*6) | The value for ch4(*7) for the above unixtime. This will not exist, if the device has no ch4 measurement. |
(*1) The value is a number, but the type is character-based.
(*2) The channel name cannot be set for the RTR500B Series and RTR-500 Series Remote Units, and "ch + channel number" will be entered here.
(*3) For RTR-574, there are ch5 (cumulative illuminance) and ch6 (cumulative UV) data, but they cannot be retrieved by this API.
(*4) When Celsius or Fahrenheit is specified in "temperature-unit" in Request Parameter, the specified unit will be used instead of the unit set in the device.
(*5) The data-id will increment from 0 to 65535 and then return to 0. The continuity of data can be confirmed by looking at the continuity of this value and unixtime. If there is a period during which current readings data could not be received, the data-id for that period may be missing. Also, in the case of the RTR500B series, the TRZ format data sent as recorded data also contains the data-id, but please note that it is different and not linked to the data-id that can be retrieved using this API.
(*6) If the measured value is obtained, a numeric value of character type is returned, but if an error occurs, an error value starting with E is returned.
(*7) This value will reflect the data value, or an error code if no valid data is available. Refer to the "Error Code List (Recorded Data)" below to see the error code list.
*Please note that actual responses may not be in such clear understandable form as shown in the example below.
HTTP/1.1 200 OK
Server: api.webstorage-service.com
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 60
X-RateLimit-Reset: 60
X-RateLimit-Remaining: 57
{
"remote-serial": "52BA0001",
"remote-model": "RTR-502",
"remote-name": "outside",
"base-serial": "58580001",
"base-model": "RTR500BW",
"base-name": "at-west",
"time-diff": 540,
"std-bias": 0,
"dst-bias": 0,
"channel":[
{
"name": "ch1",
"num": 1,
"unit": "C"
}],
"data":[
{
"unixtime": 1234500000,
"data-id": 101,
"ch1": 23.5
},{
"unixtime": 1234500030,
"data-id": 102,
"ch1": 25.5
}, ... ,{
"unixtime": 1234508970,
"data-id": 400,
"ch1": 21.5
}
]
}
*In this example, the most recent 300 readings of current readings graph data from the RTR-502(sn:52BA0001) which was registered to the RTR500BW(sn:58580001) was retrieved in json format.
The following explains data formatting for when data is received in CSV format.
This is the same format as when data is output in CSV format in T&D Graph.
| Line 1 (Header row) | Date/Time (Fixed value) | Date/Time (Fixed value) | No.1 (Fixed value) | No.2 (Fixed value) (*6) | No.3 (Fixed value) (*6) | No.4 (Fixed value) (*6) |
|---|---|---|---|---|---|---|
| Line 2 (Header row) | Time Difference:GMT**:**/Daylight Savings Time:on/off (*1) (Device Time Difference Settings) | Serial Value for Date (Excel) (fixed value) | Channel Name of channel 1 | Channel Name of channel 2 (*6) | Channel Name of channel 3 (*6) | Channel Name of channel 4 (*6) |
| Line 3 (Header row) | (fixed value of blank data) | (fixed value of blank data) | Ch1 Unit of Measurement(*4) | Ch2 Unit of Measurement(*4)(*6) | Ch3 Unit of Measurement(*4)(*6) | Ch4 Unit of Measurement(*4)(*6) |
| Line 4 and after (data rows) | Time at Measurement (*2) | Serial value in Excel for Time at Measurement (*3) | Ch1 Measurement Reading(*5) | Ch2 Measurement Reading(*5) (*6) | Ch3 Measurement Reading(*5) (*6) | Ch4 Measurement Reading(*5) (*6) |
(*1) Both the time difference info set in the device and the “On/Off” for the daylight savings time setting in the WebStorage management screen will be displayed here.
(*2) The time at measurement will be calculated using the time difference info of the device and the time adjustment, if any, for daylight savings time and will be displayed in the following format: "yyyy-mm-dd HH:mm:ss".
(*3) This is will be the date and time after adjustments carried out in (*2) and converted into a serial value for use in Excel.
(*4) When Celsius or Fahrenheit is specified in "temperature-unit" in Request Parameter, the specified unit will be used instead of the unit set in the device.
(*5) This value will reflect the data value, or an error code if no valid data is available. Refer to the "Error Code List (Recorded Data)" below to see the error code list.
(*6) Increases or decreases depending on number of channels.
HTTP/1.1 200 OK Server: api.webstorage-service.com Content-Type: text/csv; charset=utf-8 X-RateLimit-Limit: 60 X-RateLimit-Reset: 60 X-RateLimit-Remaining: 57 "Date/Time","Date/Time","No.1" "time difference:GMT+9:00/daylight savings time:off","date as serial value(Excel)","Temp" "","","C" "2016-12-14 15:46:14","42718.657106481","24.1" "2016-12-14 15:46:24","42718.657222222","24.0" "2016-12-14 15:46:34","42718.657337963","24.0" "2016-12-14 15:46:44","42718.657453704","24.1" "2016-12-14 15:46:54","42718.657569444","24.1" "2016-12-14 15:47:04","42718.657685185","24.0" "2016-12-14 15:47:14","42718.657800926","24.0" "2016-12-14 15:47:24","42718.657916667","24.0" "2016-12-14 15:47:34","42718.658032407","24.0" "2016-12-14 15:47:44","42718.658148148","24.1" "2016-12-14 15:47:54","42718.658263889","24.2" "2016-12-14 15:48:04","42718.65837963","24.2" .....