Skip to main content
Version: 1.1beta1

clarify.selectItems

Require access to Clarify namespace

For an integration to access this method, it must have been granted access to the Clarify namespace in Clarify.

This method retrieves item meta-data and/or associated time series data.

Example

# BASIC_AUTH_USERNAME=<Username from Basic Auth credentials>
# BASIC_AUTH_PASSWORD=<Password from Basic Auth credentials>
# INTEGRATION_ID=${BASIC_AUTH_USERNAME}
curl --request POST \
--url 'https://api.clarify.io/v1/rpc' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer <YOUR ACCESS TOKEN>' \
--header 'X-API-Version: 1.1' \
--data \
'
{
"jsonrpc": "2.0",
"method": "clarify.selectItems",
"id": 10,
"params": {
"integration": "'${INTEGRATION_ID}'",
"signals": {
"include": true,
"filter": {"createdAt":{"$gte": "2022-01-01T00:00:00Z"}},
"limit": 2
},
"items": {
"include": true
}
}
}
'

Method parameters

type: object

NameTypePropertiesDescription
itemsResource querydefault = {}Query which items to select, and configure inclusion or exclusion of meta-data in the response. By default, no meta-data is included.
dataData querydefault = {}Configure which data to include in the response.

Response result

type: object

Properties

NameTypePresenceDescription
itemsmap of Item ID => Item select viewWhen items.included is true.Selected Items meta-data.
dataData Framewhen data.included is true,time series data.

Rates and limits

API:

  • The API is rate-limited to 10 request/sec.

Items query:

  • items.limit can maximum be:

    • 50 if data.include == true.
    • 1000 otherwise.

Data query:

  • Time window data.notBefore -> data.before can maximum be:
    • 40 days when data.rollup < "PT1M" or data.rollup == null.
    • 400 days when data.rollup >= "PT1M" or data.rollup == "window".

Schema references

Data frame

Data frame holds data for one or more time-series.

type: object

Properties

NameTypeRequiredDescription
timesarray of TimestampYesArray of timestamps to insert.
seriesmap of Input ID => array of (number or null)YesArray of data points to insert by Input ID. The length of each array must match that of the times array. To omit a value for a given timestamp in times, use the value null.

The exact format of the keys in the "series" property depend on your query:

  • If data.rollup is configured, the keys will be "<item id>_(sum|min|max|avg|count)".
  • If data.rollup is not configured, the keys will be "<item id>".

Examples

Raw response:

{
"times": [
"2021-03-11T21:49:00Z",
"2021-03-11T21:50:00Z",
"2021-03-11T21:51:00.00123Z",
"2021-04-08T00:00:00Z"
],
"series": {
"c92rtu2sahsul7t74fag": [-10, 10, 20, 55.3, 231, 34],
"c92rujqsahsunml6lo00": [10000000, null, null, null, null, 0]
}
}

Rollup response ("PT1H"):

{
"times": ["2021-03-11T21:00:00Z", "2021-04-08T00:00:00Z"],
"series": {
"c92rtu2sahsul7t74fag_avg": [61, 34],
"c92rtu2sahsul7t74fag_count": [5, 1],
"c92rtu2sahsul7t74fag_max": [-10.0, 34],
"c92rtu2sahsul7t74fag_min": [231, 34],
"c92rtu2sahsul7t74fag_sum": [306, 34],
"c92rujqsahsunml6lo00_avg": [10000000, 0],
"c92rujqsahsunml6lo00_count": [1, 0],
"c92rujqsahsunml6lo00_max": [10000000, null],
"c92rujqsahsunml6lo00_min": [10000000, null],
"c92rujqsahsunml6lo00_sum": [10000000, 0]
}
}

Rollup response ("window"):

{
"times": ["2021-03-11T21:00:00Z"],
"series": {
"c92rtu2sahsul7t74fag_avg": [55.666667],
"c92rtu2sahsul7t74fag_count": [6],
"c92rtu2sahsul7t74fag_max": [-10.0],
"c92rtu2sahsul7t74fag_min": [231],
"c92rtu2sahsul7t74fag_sum": [340],
"c92rujqsahsunml6lo00_avg": [5000000],
"c92rujqsahsunml6lo00_count": [2],
"c92rujqsahsunml6lo00_max": [10000000],
"c92rujqsahsunml6lo00_min": [10000000],
"c92rujqsahsunml6lo00_sum": [10000000]
}
}

Data query

type: object

Properties

NameTypePropertiesDescription
includebooldefault = falseSelected Items meta-data.
notBeforenull or string(RFC 3339 timestamp)default = 7 days agoDo not include data before the specified time
beforenull or string(RFC 3339 timestamp)default = 14 days after notBeforeInclude only data before the specified time

Input ID

Input ID routes data to a signal during insert. The input ID must be unique per integration only.

type: string(regex: ^[a-zA-Z0-9-_:.#+/]{1,128}$)

Item ID

Item ID uniquely identities a item resource entry.

type: string(regex: "^[a-v0-9]{20}$")

Item select view

The item select view lists all exposed item fields.

type: object

Properties

NameTypeDescription
idstring(regex: "^[a-v0-9]{20}$")
metaResource meta
annotationsmap of string(regex: "^[A-Za-z0-9-_/]{1,128}$") => stringArbitrary configuration parameters. Customer-provided annotations should use a relevant prefix, e.g. company-domain/application-name/.
namestringThe default signal display name.
typestring(numeric or enum)The default signal type.
descriptionstringThe default signal description
labelsmap of string(regex: "^[A-Za-z0-9-_/]{1,128}$") => array of stringThe default signal labels.
engUnitstringDefault signal display unit, used in numeric representations.
enumValuesmap of string(integer in range 0-9999) => stringDefault item enum values, used to replace numeric values with text in enumerated representations.
sourceTypestring("measurement" or "aggregation" or "prediction")Default item source type.
sampleIntervalnull or string(RFC 3339 duration)How often the signal is sampled (on average).
gapDetectionnull or string(RFC 3339 duration)The default item gap detection. A gap will be drawn whenever there is no data for a duration longer than the specified value.

Example

{
"name": "Ice Cream Temperature",
"type": "numeric",
"description": "Temperature measurement of the ice cream",
"labels": {
"flavours": ["sweet", "sour"],
"location": ["pier", "banana stand"]
},
"engUnit": "°C",
"sourceType": "measurement",
"sampleInterval": "PT1M",
"gapDetection": "PT5M"
}

Resource meta

type: object

Properties

NameTypeDescription
contentHashstringHash of "relevant" fields in the resource (better definition in expected next API version)
createdAtstring(RFC 3339 timestamp)When the resource was created.
updatedAtstring(RFC 3339 timestamp)When the resource was updated.

Resource query

Query a resource in Clarify.

type: object

Properties

NameTypePropertiesDescription
includebooleandefault = nullSet to true to include matched resources in the response.
filterResource filterdefault = {}Filter which resources to include.
limitintegerdefault = 25Number of resources to include in the result.
skipintegerdefault = 0Skip the first N items.