1. 75F Renatus
  2. Integrations
  3. API's for Integrations

HisReadMany API

Abhishek Deb
  • Updated

browse

2 Minute Read

| hisReadMany  

The hisReadMany API is used to read time-series data from a specific historized point. 

The /hisReadMany operation reads multiple haystack-based data, a mere read operation but allows for multiple IDs to be passed in the request, to read data over a range of days.

 

| Request

A grid with a single row and the following columns: 

  • id: Ref identifier of historized point 
  • range: Str encoding of a date-time range 

The request Parameters:

Parameter Name In Required Type
ids query true String array
range query true String

 

| Response

Rows of the result grid represent timestamp/value pairs with a DateTime ts column and a value column for each scalar value that it represents. In addition to this, the grid metadata includes:

  • id: Ref of the point we read 
  • hisStart: DateTime timestamp for inclusive range start in point's time zone 
  • hisEnd: DateTime timestamp for exclusive range end in point's time zone 

Format the range Str as one of the following options: 

  • "today" 
  • "yesterday" 
  • "{date}" 
  • "{date},{date}" 
  • "{dateTime},{dateTime}" 
  • "{dateTime}" // anything after the given timestamp 

Note: The range includes the start timestamp and excludes the end timestamp.

The  {date} and {dateTime} options must be correctly encoded. Date-based ranges, always range from midnight of the start date to midnight of the day after the end date, using the timezone of the point being queried. 

Query the range using the configured timezone of the point. Although, if a different timezone is specified in the range, then the servers must convert to the point's configured timezone, before executing the query. Let us consider an example below:

// request 
 ids, range 
@someTemp,"2012-10-01" 

@somePoint,"2012-10-01" 

Response: 200 OK 

| Example

 hisStart:2020-01-01T00:00:00Z hisEnd:2020-01-02T00:00:00Z id,data,his,point,tz,unit  

@example-point-a,[ 

{ts:2020-01-01T12:00:00-04:00 New_York val:67.0%}, 

{ts:2020-01-01T12:01:00-04:00 New_York val:67.1%}], 

M,M,"New_York","%"  

@example-point-b,[ 

{ts:2020-01-01T12:00:00-04:00 Chicago val:71.5°F}, 

{ts:2020-01-01T12:01:00-04:00 Chicago val:71.2°F}], 

M,M,"Chicago","°F" 

| Procedure to Execute a HisReadMany API request

Note: Only as a Secondary Manager of a site, one can sample points data or write to points data of the sites. 

 From the Developer portal home page

  • Click the Profile option.

mceclip0.png

The user profile screen displays the user and subscription details.

Under the products subscribed for,

  • Locate the subscription key for the relevant product.

For this example, we use the product Staging Readwrite subscription.

  • Click the option shown to view the subscription keys, or simply copy the subscription key to be used to generate the Bearer token.

mceclip10.png

  • Click the API's option on the top.

The API's screen displays the list of Authorized API's.

For this demo, we use the Haystack (Staging) API.

  • Click the API Haystack (Staging).

mceclip12.png

The Haystack (Staging) API screen displays the API details.

Note: To start sampling data using this Haystack (Staging) API, the user needs to generate a bearer token using the API 75Auth {Staging) as shown above using the information shown in Oauth API

  • Click Try it to access the API.

mceclip9.png

The Try it window to try the API displays.

  • Select the Primary: Staging Readwrite under the subscription key field.

mceclip8.png

  • Access the site explorer in the Facilisight to locate a point with the historized values.

From the site explorer in Facilisight:

  • Locate a point ID for which you would like to retrieve the historized values, as below.

mceclip7.png

For this example, we use the current temperature and humidity points to retrieve the historized values.

  • Enter the point IDs into the ID field and enter the point Id with @ as a prefix, multiple Ids can be added to fetch data, separated with commas(,).
  • Enter a date range or today or yesterday in the range field  
  • Scroll further to locate the Header section.

The header section should have the following headers.

mceclip5.png

  • Paste the subscription key copied from the profile screen into the header option  Ocp-Apim-Subscription-Key.
  • Paste the bearer token generated into the header option  Authorization  in the format shown above, with a "Bearer" and  followed by the token generated

 "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyRGF0YSI6eyJ1c2VySWQiOiI0M2JjNGRlZC01YWQxLTRkZTUtOGU1OC1mYTg1YTM4ODRhNzIiLCJlbWFpbElkIjoibWNoYW5kcmFzZWthckA3NWYuaW8iLCJzdHJhdGVneSI6InBhc3MiLCJpc1N1cHBvcnQiOjF9LCJhY2Nlc3NBbGxvd2VkIjp0cnVlLCJyb2xlIjoiYXBwIiwiZ2xvYmFsU2Vzc2lvbklEIjoicm5iTlpiMUZIelI0RXd4eHJuOFNrT3Z6MkFIX19zbVQiLCJhcHBOYW1lIjoiZ2F0ZWtlZXBlcjc1ZiIsImVudiI6InN0YWdpbmciLCJpYXQiOjE2NTE3MzYzMTQsImV4cCI6MTY1MTgyMjcxNCwiaXNzIjoiNzVmIn0.dLZIMK2R6B0JgFjDjkfR3GY1dDEzuiB82Wrvwha8bcaLH4_sUxM4Pe_cWNGES3Jth7xP4ug8_cKe-8lpNezXD-B43KxbXy9t8ng9RXkUfvrPvDAua_xEKaw3eep1MdzGtZCwau2gCJp12zq33JM8oi8RqAd-3u6b6u5DwEO6pz1HlHn1JMKcUkLXAlo61WtTcePmBR1SDky0vWQnh-clHORjKFrpJB2a-jewB7raYBrMOFUNperC-dPZViqX3dC6SdGPSgAOD14e-XfrGHj6a1jSYOh4wtsG89mz5h03VC78QJ7JcPoyqgNVKP30QlmqO0tyCrKhwkzNnS39z-xTNA"

With the below request format:

mceclip6.png

  • Click Send to sample the data.

The portal generates the response, with the Historized data points information as below, as in this case for Humidity values,

| HTTP Response

HTTP/1.1 200 OK

content-encoding: gzip
content-type: application/json
date: Thu, 05 May 2022 07:43:01 GMT
transfer-encoding: chunked
vary: origin,access-control-request-method,access-control-request-headers,accept-encoding

{
    "metadata": {
        "ver": "3.0",
        "hisStart": "t:2022-05-05T00:00:00+05:30 Colombo",
        "hisEnd": "t:2022-05-05T13:13:01.365859+05:30 Colombo"
    },
    "cols": [{
        "name": "id"
    }, {
        "name": "air"
    }, {
        "name": "cpu"
    }, {
        "name": "cur"
    }, {
        "name": "current"
    }, {
        "name": "data"
    }, {
        "name": "dis"
    }, {
        "name": "equipRef"
    }, {
        "name": "floorRef"
    }, {
        "name": "group"
    }, {
        "name": "his"
    }, {
        "name": "hisInterpolate"
    }, {
        "name": "humidity"
    }, {
        "name": "HyperStat"
    }, {
        "name": "kind"
    }, {
        "name": "logical"
    }, {
        "name": "point"
    }, {
        "name": "roomRef"
    }, {
        "name": "sensor"
    }, {
        "name": "siteRef"
    }, {
        "name": "temp"
    }, {
        "name": "tz"
    }, {
        "name": "unit"
    }, {
        "name": "zone"
    }],
    "rows": [{
        "id": "r:73651d0f-f0d9-4740-99c3-37b713fc90f5",
        "air": "m:",
        "cpu": "m:",
        "cur": "m:",
        "current": "m:",
        "data": [{
            "ts": "t:2022-05-05T00:00:00+05:30 Colombo",
            "val": "n:57 %"
        }, {
            "ts": "t:2022-05-05T00:01:00+05:30 Colombo",
            "val": "n:57 %"
        }, {
            "ts": "t:2022-05-05T00:02:00+05:30 Colombo",
            "val": "n:57.1 %"
        }, {
            "ts": "t:2022-05-05T00:03:00+05:30 Colombo",
            "val": "n:57.1 %"
        }, {
            "ts": "t:2022-05-05T00:04:00+05:30 Colombo",
            "val": "n:57 %"
        }, {
            "ts": "t:2022-05-05T00:05:00+05:30 Colombo",
            "val": "n:57.1 %"
        }, {
            "ts": "t:2022-05-05T00:06:00+05:30 Colombo",
            "val": "n:57 %"

And as below for the parts of Temperature

{
        "id": "r:8797285e-7414-48ce-9907-c703ff232b31",
        "air": "m:",
        "cpu": "m:",
        "cur": "m:",
        "current": "m:",
        "data": [{
            "ts": "t:2022-05-05T00:00:00+05:30 Colombo",
            "val": null
        }, {
            "ts": "t:2022-05-05T00:01:00+05:30 Colombo",
            "val": null
        }, {
            "ts": "t:2022-05-05T00:02:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:03:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:04:00+05:30 Colombo",
            "val": "n:84.9 °F"
        }, {
            "ts": "t:2022-05-05T00:05:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:06:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:07:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:08:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:09:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:10:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:11:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:12:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:13:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:14:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:15:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:16:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:17:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:18:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:19:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:20:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:21:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:22:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:23:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:24:00+05:30 Colombo",
            "val": "n:85 °F"

And similarly, an application can be connected to start reading the data using the bearer token generated and using the point ID from the sites assigned to the user

 

Previous
Next

Comments

0 comments

Please sign in to leave a comment.

Was this article helpful?

0 out of 0 found this helpful
Powered by Zendesk