Get Data by Specific Period and Number [RTR500BW/RTR500BM]

Overview

This can be used to get the current readings graph data from compatible devices that are being managed with T&D WebStorage Service.
By specifying the number of data readings or the time period it is possible to get only the specific data that you request.

Request

URI

https://api.webstorage-service.com/v1/devices/data-rtr500

Access Restrictions

Read-Only ID is also possible

Compatible Models for this API

RTR500B series (via HTTPS)

* 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.

Rate Limit

20 requests per allotted 1-minute span, or 160,000 readings per 60 minutes per device

This interval for this API has been designed to be relatively long so as to allow for retrieval of data on a set regular interval. Since the number of retrieved data readings is large and the load is intense, an upper limit for the number of data readings per device has been included.
This will help alleviate duplicate data acquisition for the same device. Further, to reduce short-term load the maximum number of accesses has been limited. Please be aware of this before using.

If you wish to get the latest current readings at a shorter interval, use the following API.

Request Header

Item NameMeasurement Value
HTTP MethodPOST
X-HTTP-Method-OverrideGET
Hostapi.webstorage-service.com:443
Content-Type:application/json

Request Parameter

Parameter NameFormatRequiredDefault ValueDetails
api-keystring(45 characters)Yes---Already acquired API Key
login-idstring(8 characters)Yes---User ID Read-Only ID is also possible
login-passstring(4-16 characters)Yes---The password for the above User ID.
remote-serialstring(8 characters)Yes---Serial Number of the device from which graph data will be retrieved. Not possible to select more than one unit at a time. (*1)
base-serialstring(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)
unixtime-fromnumber---unixtime at the start time of retrieving graph data (*3)
Only newer data that comes after the specified time will be retrieved.
unixtime-tonumberTime at which API was accessedunixtime at the finish time of retrieving graph data (*3)
Only older data that comes before the specified time will be retrieved.
numbernumber16000This can be used when you wish to specify the number of graph data readings to be retrieved.
The default is 16,000 readings and the upper limit is 65,535. (*3)
typestring( json/csv )jsonThese are format types for the received graph data. Select either json format or csv format.
temperature-unitstring(device/C/F)deviceThis 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) About Settings for unixtime-from / unixtime-to / number
・Even if the set number is larger than 65,535, it will be limited to 65,535.
・“unixtime-from/unixtime-to” is designed with an AND condition included whereby the number of readings can be specified. If specified, then that number of data readings will be retrieved in sequence from the data at the latest time specified.
・If no specifications are made for unixtime-from, unixtime-to or number then the most recent 16,000 reading will be retrieved.

・If the number of data readings in the period specified by “unixtime-from” and “unixtime-to” is more than that specified by “number”, then not all data in the time period will be retrieved, but only the the number of data readings specified by “number” will be retrieved with the most recent data first.
(EX: If in the period specified by “unixtime-from” and ”unixtime-to” there are 20,000 data readings, but 16,000 readings was specified by “number”, then only the most recent 16,000 readings from the time specified in “unixtime-to” as a starting point. The oldest 4,000 readings will not be retrieved. )

・If the number of data readings in the period specified by “unixtime-from” and “unixtime-to” is less than that specified by “number”, then all of the data in the specified time period (from “unixtime-from” to “unixtime-to”) will be retrieved.
(EX: If in the period specified by “unixtime-from” and ”unixtime-to” there are 10,000 data readings, but 16,000 readings was specified by “number”, then all 10,000 readings included in the specified period will be retrieved. )

Request Example

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

例1:
{
"api-key":"73pfobnche8d1p6laqnemsbnpkght3bjv047oid6p2sg3",
"login-id":"tbzz9999",
"login-pass":"ppaasswwoorrdd",
"remote-serial":"52BA0001",
"base-serial":"58580001"
}

*In this example, the most recent 16,000 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.


例2:
{
"api-key":"73pfobnche8d1p6laqnemsbnpkght3bjv047oid6p2sg3",
"login-id":"tbzz9999",
"login-pass":"ppaasswwoorrdd",
"remote-serial":"52BA0001",
"base-serial":"58580001",
"unixtime-from":1504191600,
"unixtime-to":1504191600
}

*In this example, the most recent 16,000 readings (number of readings depends on time period specified) of current readings graph data from the RTR-502(sn:52BA0001) which was registered to the RTR500BW(sn:58580001), for the period of Aug. 1, 2017 00:00:00 to Sept.1, 2017 00:00:00, in other words the data for the month of Aug. 2017 was retrieved in json format.

Response

Response Header

Item NameValueDetails
HTTP status code(**)HTTP Status Code
Content-Typeapplication/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
X-RateLimit-Remaining-DataCount(integer)Remaining number of accessible data readings

(**) 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
X-RateLimit-Remaining-DataCount: 0

{
	"error":{
		"code": error code,
		"message": "error details"
	}
}

Response Parameter (JSON format)

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 Required Details
remote-serial string Yes Serial Number of Selected Remote Unit
remote-model string Yes Model Name of Selected Remote Unit
remote-name string Yes Device Name of Selected Remote Unit
base-serial string Yes Serial Number of Selected Base Unit
base-model string Yes Model Name of Selected Base Unit
base-name string Yes Device Name of Selected Base Unit
time-diff number Yes 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 number Yes 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 number Yes 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 Yes Channel Name (*1)
  channel.num number Yes Channel Number (1~4) (*2)
  channel.unit string Yes Unit of Measurement for Channel(*3)
data Array If the number of data readings is "0”, then the array is blank.
  data.unixtime number Yes unixtime of graph data
  data.data-id number Yes data-id(*4) of graph data
  data.ch1 number Yes The value for ch1(*5) for the above unixtime.
  data.ch2 number The value for ch2(*5) for the above unixtime. This will not exist, if the device has no ch2 measurement.
  data.ch3 number The value for ch3(*5) for the above unixtime. This will not exist, if the device has no ch3 measurement.
  data.ch4 number The value for ch4(*5) for the above unixtime. This will not exist, if the device has no ch4 measurement.

(*1) The channel name cannot be set for the RTR500B Series and RTR-500 Series Remote Units, and "ch + channel number" will be entered here.
(*2) For RTR-574, there are ch5 (cumulative illuminance) and ch6 (cumulative UV) data, but they cannot be retrieved by this API.
(*3) 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.
(*4) 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.
(*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.

Response Example (JSON format)

*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
X-RateLimit-Remaining-DataCount: 87654

{
	"remote-serial": "52BC0001",
	"remote-model": "RTR-503",
	"remote-name": "outside",
	"base-serial": "58580001",
	"base-model": "RTR500BW",
	"base-name": "west",
	"time-diff": 540,
	"std-bias": 0,
	"dst-bias": 0,
	"channel":[
		{
			"name":"ch1",
			"num":1,
			"unit":"C"
		},{
			"name":"ch2",
			"num":2,
			"unit":"%"
		}],
	"data":[
		{
			"unixtime": 1234560000,
			"data-id":101,
			"ch1":23.5,
			"ch2":65
		},{
			"unixtime": 1234560030,
			"data-id":102,
			"ch1":25.5,
			"ch2":68
		}, ... ,{
			"unixtime": 1235040000,
			"data-id":16100,
			"ch1":21.5,
			"ch2":60
		}
	]
}

Response Parameter (CSV 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 for 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) Ch 1 Unit of Measurement (*4) Ch 2 Unit of Measurement (*4)(*6) Ch 3 Unit of Measurement (*4)(*6) Ch 4 Unit of Measurement (*4)(*6)
Line 4 and after (data rows) Time at Measurement (*2) Serial value in Excel for Time at Measurement (*3) Ch 1 Measurement Reading (*5) Ch 2 Measurement Reading (*5) (*6) Ch 3 Measurement Reading (*5) (*6) Ch 4 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.

Response Example (CSV format)

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
X-RateLimit-Remaining-DataCount: 87654

"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"
.....

MENU