Token｜資料分析

API Domain

https://ioe-api.nextdrive.io

Data Analysis｜Knowledge Discovery Service

① Create data aggregation group

Summary

① Create data aggregation group

Path

POST /knowledge-discovery/v1/aggregation-groups

Description

Through this API, you can create a data aggregation group to execute KDS by defining the following settings:

  • model
    Refers to the device model that performs data aggregation.
    Please note that currently only the ECHONET Lite model can be processed.

  • dsns
    Refers to the target device for data aggregation. Multiple devices can be specified at one time.
    Please note that if you don't specify any device dsn, all device of the specified model of your business will be processed.

  • scope
    Refers to the data scope of the device for which data aggregation is to be performed.
    Currently, only cumulative values ​​in units of kWh/Wh can be processed.

  • interval
    Refers to the data aggregation conditions, including the following settings:

    1. value : data aggregation granularity, which only support 15 and 30 minutes, 1 hour, 1 day, and 1 month.
      Please note that the value you specified cannot be smaller than the polling interval of “model“.

    2. timezone : data aggregation time zone, formatted as "Asia/Tokyo" instead of "GMT+8" (Link).

Request Body

Content Type

application/json

Example Value
JSON
{
  "device": {
    "model": "<MODEL>",
    "dsns": ["DSN1", "DSN2"], // optional
    "scope": "SCOPE1",
    "interval": {
      "value": "15m", // or "30m", "1h", "1d", "1M"
      "timezone": "Asia/Tokyo" // "UTC", "Asia/Taipei"...etc
    }
  }
}

Schema
JSON
{
  "device": {
    "model": string,
    "dsns": string[],
    "scope": string,
    "interval": {
      "value": string,
      "timezone": string
    }
  }
}

Note

Please note that the status of KDS group is "inactivate" after being created. Manage the group through the "Activate Group" API according to your needs.
After activating the data aggregation group, KDS will start to calculate the difference between two consecutive accumulated values ​​at the specified time interval.
200

Response

Status Code

200

Description

Success

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful request"
  "data": {
    "groupUuid":"00215a89-db8a-45ee-bfa1-c7de6db13fb5"
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "groupUuid": string
  }
}
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40001,
  "message": "Invalid parameter: XXXXXX"
}

Schema
JSON
{
  "requestId": string,
  "code": integer,
  "message": string"
}

Note

  • Required field is missing

  • Value type error

  • interval value is not "15 mins", "30 mins", "1 hour", "1 day", or "1 month"

  • Model or scope is not supported

  • Using upload interval 30 mins (model="smartMeter", scope="normalUsage" or "reverseUsage") interval is set to "15 mins"

  • The same setting already exists

  • Model sopes with an upload interval of 30 mins (model="smartMeter", scope="normalUsage" or "reverseUsage") is specified, but the interval is set to "15 mins"
② Get KDS group detail

Summary

② Get KDS group detail

Path

GET /knowledge-discovery/v1/groups/{groupUuid}

Description

Through this API, you can get detail of a specific KDS group.

Request Params

Example Value
JSON
groupUuid= 02215a89-db8a-45ee-bfa1-c7de6db13fb1

Schema
JSON
groupUuid= string
200

Response

Status Code

200

Description

Success

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful request"
  "data": {
    "groupUuid":"00215a89-db8a-45ee-bfa1-c7de6db13fb5",
    "type": "aggregation",
    "createdAt": "2023-01-01T03:00:22Z",
    "isActive": true,
    "device": {
      "model": "<MODEL>",
      "dsns": ["DSN1", "DSN2"], // optional
      "scope": "SCOPE1",
      "interval": {
        "value": "15m", // or "30m", "1h", "1d", "1M"
        "timezone": "Asia/Tokyo" "UTC", "Asia/Taipei"...etc
      }
    }
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "groupUuid": string,
    "type": string,
    "createdAt": string,
    "isActive": boolean,
    "device": {
      "model": string,
      "dsns": string[],
      "scope": string,
      "interval": {
        "value": string,
        "timezone": string
      }
    }
  }
}
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40001,
  "message": "Invalid parameter: XXXXXX"
}

Schema
JSON
{
  "requestId": string,
  "code": integer,
  "message": string"
}

Note

Missing groupUuid
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40400,
  "message": "Not found"
}

Schema
JSON
{
  "requestId": string,
  "code": integer,
  "message": string"
}

Note

Not found
③ Get KDS group list

Summary

③ Get KDS group list

Path

GET /knowledge-discovery/v1/groups

Description

Through this API, you can get the list of KDS groups.

Request Params

Content Type

N/A

Example Value

QUERY-STRING PARAMETERS

JSON
model=<MODEL NAME1> //optional
scope=<SCOPE NAME> //optional
page=<POSITIVE INTEGER> //optional, default 1

Schema

QUERY-STRING PARAMETERS

JSON
model=string //optional
scope=string //optional
page=string //optional, default 1
200

Response

Status Code

200

Description

Success

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful request"
  "data": {
    "page": 1,
    "totalPage": 10,
    "results": [
      {
        "groupUuid": "00215a89-db8a-45ee-bfa1-c7de6db13fb5",
        "type": "aggregation",
        "createdAt": "2023-01-01T03:00:22Z",
        "isActive": true
      }
    ]
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "page": integer,
    "totalPage": integer,
    "results": [
      {
        "groupUuid": string,
        "type": string,
        "createdAt": string,
        "isActive": boolean
      }
    ]
  }
}

Note

  1. Results are sorted by createdAt from oldest to newest.

  2. Maximum 100 results per page.
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40001,
  "message": "Invalid parameter: XXXXXX"
}

Schema
JSON
{
  "requestId": string,
  "code": integer,
  "message": string"
}

Note

Invalid Parameter Error
④ Update data aggregation group

Summary

④ Update data aggregation group

Path

PUT /knowledge-discovery/v1/aggregation-groups/{groupUuid}

Description

Through this API, you can update the settings of the data aggregation group.

Request Body

Content Type

application/json

Example Value
JSON
{
  "device": {
    "dsns": ["DSN1", "DSN2"], // optional
    "scope": "SCOPE1",
    "interval": {
      "value": "15m", // or "30m", "1h", "1d", "1M"
      "timezone": "Asia/Tokyo" // "UTC", "Asia/Taipei"...etc
    }
  }
}

Schema
JSON
{
  "device": {
    "dsns": string[],
    "scope": string,
    "interval": {
      "value": string,
      "timezone": string
    }
  }
}

Request Params

Example Value
JSON
groupUuid= 02215a89-db8a-45ee-bfa1-c7de6db13fb1

Schema
JSON
groupUuid= string

Note

Please note that model cannot be updated. If you want to perform data aggregation on other models, please create another data aggregation group.
200

Response

Status Code

200

Description

Success

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful request"
  "data": {
    "groupUuid":"00215a89-db8a-45ee-bfa1-c7de6db13fb5"
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "groupUuid": string
  }
}
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40001,
  "message": "Invalid parameter: XXXXXX"
}

Schema
JSON
{
  "requestId": string,
  "code": integer,
  "message": string"
}

Note

  • Required field is missing

  • Value type error

  • interval value is not "15 mins", "30 mins", "1 hour", "1 day", or "1 month"

  • Model or scope is not supported

  • Using upload interval 30 mins (model="smartMeter", scope="normalUsage" or "reverseUsage") interval is set to "15 mins"

  • The same setting already exists
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40400,
  "message": "Not found"
}

Schema
JSON
{
  "requestId": string,
  "code": integer,
  "message": string"
}

Note

groupUuid does not exist
⑤ Delete KDS group

Summary

⑤ Delete KDS group

Path

DELETE /knowledge-discovery/v1/groups/{groupUuid}

Description

Through this API, you can delete a specific KDS group.

Request Params

Example Value
JSON
groupUuid= 02215a89-db8a-45ee-bfa1-c7de6db13fb1

Schema
JSON
groupUuid= string
200

Response

Status Code

200

Description

Success

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful request"
  "data": {
    "groupUuid":"00215a89-db8a-45ee-bfa1-c7de6db13fb5"
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "groupUuid": string
  }
}
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40001,
  "message": "Invalid parameter: XXXXXX"
}

Schema
JSON
{
  "requestId": string,
  "code": integer,
  "message": string"
}

Note

Missing groupUuid parameter
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40400,
  "message": "Not found"
}

Schema
JSON
{
  "requestId": string,
  "code": integer,
  "message": string
}

Note

  • groupUuid does not exist
⑥ Activate/Inactivate KDS group

Summary

⑥ Activate/Inactivate KDS group

Path

PATCH /knowledge-discovery/v1/groups

Description

Through this API, you can activate/inavtivate the KDS groups.
The KDS service will start data processing after activating the specified group, or stop data processing after deactivating it.

Request body

Content Type

application/json

Example Value
JSON
{
  "groupUuids": [
    "00215a89-db8a-45ee-bfa1-c7de6db13fb5"
  ],
  "isActive": true
}

Schema
JSON
{
  "groupUuids": string[],
  "isActive": boolean
}

Note

If you want to use this API, please contact NextDrive to enable ADS service.
200

Response

Status Code

200

Description

Success

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful request"
  "data": {}
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {}
}
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40001,
  "message": "Invalid parameter: XXXXXX"
}

Schema
JSON
{
  "requestId": string,
  "code": integer,
  "message": string
}

Note

Invalid parameter
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40400,
  "message": "Not found"
}

Schema
JSON
{
  "requestId": string,
  "code": integer,
  "message": string
}

Note

groupUuid does not exist


⑦ Get aggregation data

Summary

⑦ Get aggregation data

Path

GET /knowledge-discovery/v1/aggregation/dsns/{dsn}/scopes

Description

Through this API, you can query data which has been caculated by KDS service.

Request parameters

Content Type

N/A

Example Value

Path parameter

JSON
dsn=VLBI2N0086390

Query string parameter

JSON
scopes=normalUsage
from=1652227200
to=1652227201
interval=15m // or "30m", "1h", "1d", "1M"

Schema

Path parameter

JSON
dsn= string

Query string parameter

JSON
scopes= string
from= string
to= string
interval= string // "15m" , "30m", "1h", "1d", "1M"

Note

  1. Only one scope and interval can be entered

  2. Query length from from to to:

    • 15/30/60 minutes granularity: up to 3 days

    • 1 day granularity: up to 92 days (31+30+31)

    • 1 month granularity: up to 731 days (365+366)

  3. “from“ cannot be earlier than the activation time or the earliest retention time of data (2 years back from the current time))

  4. Tmiestamp definition

    • The timestamp (intervalStartTime) of the aggregated data is the start time of the granular interval.
      [Example]
      For 15-minute granularity, the intervalStartTime for aggregated data from 00:00 to 00:15 will be 00:00.

    • If the query range includes the boundary value of the granularity interval, the data will be obtained
      [Example]
      For 15-minute granularity,

      • if from is 5/2 00:00 and to is 5/3 00:00, 96 aggregated data will be returned.

      • if from is 5/2 00:00 and to is 5/3 00:15, 97 aggregated data will be returned.

      • if from is 5/1 23:45 and to is 5/3 00:00, 97 record of data will be returned.

      • if from is 5/1 23:46 and to is 5/3 00:14, 96 record of data will be returned.

  5. Missing value handling

    • For the granular interval that has ended and the aggregated data cannot be calculated, the aggregated data will not be provided.

    • For the granular interval that has not yet finished, the value of the aggregated data = the latest cumulative data for this interval - the first data for this interval
200

Response

Status Code

200

Description

Success

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful request"
  "data": {
    "results": [
      {
        "intervalStartTime": 1703203200,
        "value": "15" // represents the difference between 2023-12-22 00:00~00:30
      },
      {
        "intervalStartTime": 1703205000, 
        "value": "20" // represents the difference between 2023-12-22 00:30~01:00
      },
      {
        "intervalStartTime": 1703206800,
        "value": "25" // represents the difference between 2023-12-22 01:00~01:30
      }
    ]
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "results": [
      {
        "intervalStartTime": integer,
        "value": string
      }
    ]
  }
}
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40001,
  "message": "Invalid parameter: XXXXXX"
}

Schema
JSON
{
  "requestId": string,
  "code": integer,
  "message": string
}

Note

Invalid Parameter
403

Response

Status Code

403

Description

Forbidden

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40300,
  "message": "Forbidden"
}

Schema
JSON
{
  "requestId": string,
  "code": integer,
  "message": string
}

Note

  • The relative relationship of from and to parameters is incorrect

  • from is more than two years ago

  • Query length from from to to exceeds the legal range

    • 15/30/60 minutes granularity: up to 3 days

    • 1 day granularity: up to 92 days (31+30+31)

    • 1 month granularity: up to 731 days (365+366)