Skip to content

Metrics

Metrics are the data that the Scout platform collects from the electrical installations. This data is used to monitor the status of the installations and to detect deviations from the normal operation. Once the data has been processed, it can be visualized and used to generate automated alerts.

Metrics structure

Parameters

Each metric has a code associated with it that serves as an identifier, the table below contains the list of all the codes the platform supports.

  • Name contains a description of the metric
  • Unit contains the unit of the metric (in case it has one)
  • Var type indicates if the metric is a gauge (instant value) or a counter (accumulated value)
  • Var type indicates the data type of the metric, the 2 types supported are
    • FLOAT: contains single float point value, e.g. 230.1
    • JSON: contains nested data, e.g. 
      {
  "HARM_V_AN": {
      "0": 230.1,
      "1": 0.1,
      "2": 0.05
  }
}

Retrieval

The metrics can be retrieved with the raw values, but it is also possible to perform aggregations on the data, depending on the variable type. If the variable is an instant value (gauge) or an accumulated value (counter)

The available aggregations for gauge variables are:

  • avg: Average value of the metric in the selected period.
  • max: Maximum value of the metric in the selected period.
  • min: Minimum value of the metric in the selected period.

The available aggregations for counter variables are:

  • delta: Difference between the last and the first value of the metric in the selected period.

The aggregation periods for the variables are hour, day, week, month.

Metrics list

Code Name Unit Var type Type
V_AN Voltage L1 V gauge FLOAT
V_BN Voltage L2 V gauge FLOAT
V_CN Voltage L3 V gauge FLOAT
V_AB Voltage L1L2 V gauge FLOAT
V_BC Voltage L2L3 V gauge FLOAT
V_CA Voltage L3L1 V gauge FLOAT
V_PP Voltage unknown phase V gauge FLOAT
V_NG Neutral voltage V gauge FLOAT
I_AN Current L1 A gauge FLOAT
I_BN Current L2 A gauge FLOAT
I_CN Current L3 A gauge FLOAT
I_TOT Current total A gauge FLOAT
I_LK Leak current A gauge FLOAT
I_NG Neutral current A gauge FLOAT
FREQ Frequency Hz gauge FLOAT
CF_I_AN Crest factor current L1 gauge FLOAT
CF_I_BN Crest factor current L2 gauge FLOAT
CF_I_CN Crest factor current L3 gauge FLOAT
CF_I_NG Crest factor current neutral gauge FLOAT
CF_V_AN Crest factor voltage L1 gauge FLOAT
CF_V_BN Crest factor voltage L2 gauge FLOAT
CF_V_CN Crest factor voltage L3 gauge FLOAT
CF_V_NG Crest factor voltage neutral gauge FLOAT
DPF_AN Cosphi L1 gauge FLOAT
DPF_BN Cosphi L2 gauge FLOAT
DPF_CN Cosphi L3 gauge FLOAT
DPF_TOT Cosphi total gauge FLOAT
KF_AN K-Factor L1 % gauge FLOAT
KF_BN K-Factor L2 % gauge FLOAT
KF_CN K-Factor L3 % gauge FLOAT
N_AN Non active power L1 var gauge FLOAT
N_BN Non active power L2 var gauge FLOAT
N_CN Non active power L3 var gauge FLOAT
N_TOT Non active power total var gauge FLOAT
OD_V_AN Over deviation L1 % gauge FLOAT
OD_V_BN Over deviation L2 % gauge FLOAT
OD_V_CN Over deviation L3 % gauge FLOAT
OD_V_AB Over deviation L1L2 % gauge FLOAT
OD_V_BC Over deviation L2L3 % gauge FLOAT
OD_V_CA Over deviation L3L1 % gauge FLOAT
UD_V_AN Under deviation L1 % gauge FLOAT
UD_V_BN Under deviation L2 % gauge FLOAT
UD_V_CN Under deviation L3 % gauge FLOAT
VOD_V_AN Voltage over deviation L1 V gauge FLOAT
VOD_V_BN Voltage over deviation L2 V gauge FLOAT
VOD_V_CN Voltage over deviation L3 V gauge FLOAT
VOD_V_AB Voltage over deviation L1L2 V gauge FLOAT
VOD_V_BC Voltage over deviation L2L3 V gauge FLOAT
VOD_V_CA Voltage over deviation L3L1 V gauge FLOAT
VUD_V_AN Voltage under deviation L1 V gauge FLOAT
VUD_V_BN Voltage under deviation L2 V gauge FLOAT
VUD_V_CN Voltage under deviation L3 V gauge FLOAT
VUD_V_AB Voltage under deviation L1L2 V gauge FLOAT
VUD_V_BC Voltage under deviation L2L3 V gauge FLOAT
VUD_V_CA Voltage under deviation L3L1 V gauge FLOAT
P1_AN Fundamental Active Power L1 W gauge FLOAT
P1_BN Fundamental Active Power L2 W gauge FLOAT
P1_CN Fundamental Active Power L3 W gauge FLOAT
P1_TOT Fundamental Active Power III W gauge FLOAT
PF_AN Power Factor L1 gauge FLOAT
PF_BN Power Factor L2 gauge FLOAT
PF_CN Power Factor L3 gauge FLOAT
PF_TOT Power Factor total gauge FLOAT
PHI_AN Angle Voltage - Current L1 ° gauge FLOAT
PHI_BN Angle Voltage - Current L2 ° gauge FLOAT
PHI_CN Angle Voltage - Current L3 ° gauge FLOAT
PST_AN Flicker short period L1 gauge FLOAT
PST_BN Flicker short period L2 gauge FLOAT
PST_CN Flicker short period L3 gauge FLOAT
PST_AB Flicker short period L1L2 gauge FLOAT
PST_BC Flicker short period L2L3 gauge FLOAT
PST_CA Flicker short period L3L2 gauge FLOAT
PLT_AN Flicker short period L1 gauge FLOAT
PLT_BN Flicker long period L2 gauge FLOAT
PLT_CN Flicker long period L3 gauge FLOAT
PLT_AB Flicker long period L1L2 gauge FLOAT
PLT_BC Flicker long period L2L3 gauge FLOAT
PLT_CA Flicker long period L3L1 gauge FLOAT
P_AN Active power L1 W gauge FLOAT
P_BN Active power L2 W gauge FLOAT
P_CN Active power L3 W gauge FLOAT
P_TOT Active power III W gauge FLOAT
Q_AN Reactive Power L1 var gauge FLOAT
Q_BN Reactive Power L2 var gauge FLOAT
Q_CN Reactive Power L3 var gauge FLOAT
Q_TOT Reactive Power III var gauge FLOAT
S1_AN Fundamental Apparent Power L1 VA gauge FLOAT
S1_BN Fundamental Apparent Power L2 VA gauge FLOAT
S1_CN Fundamental Apparent Power L3 VA gauge FLOAT
S1_TOT Fundamental Apparent Power III VA gauge FLOAT
SEQ_NEG_I Unbalance current (decomposed) I gauge FLOAT
SEQ_NEG_V_PN Unbalance voltage (decomposed) V gauge FLOAT
SEQ_NEG_V_PP Unbalance unknown phase (decomposed) V gauge FLOAT
SEQ_POS_I Positive sequence current A gauge FLOAT
SEQ_POS_V_PN Positive sequence voltage total V gauge FLOAT
SEQ_POS_V_PP Positive sequence voltage V gauge FLOAT
SEQ_ZERO_I Zero sequence current A gauge FLOAT
SEQ_ZERO_V_PN Zero sequence voltage total V gauge FLOAT
SEQ_ZERO_V_PP Zero sequence voltage V gauge FLOAT
ASYM_I Asymmetry current % gauge FLOAT
UNBAL_I Unbalance current A gauge FLOAT
UNBAL_V_PN Voltage unbalance factor % gauge FLOAT
ASYM_V_PN Voltage unbalance asymmetry factor % gauge FLOAT
UNBAL_V_PP Unbalance voltage % gauge FLOAT
ASYM_V_PP Asymmetry voltage % gauge FLOAT
SGA_V_AN Signaling current L1 V gauge FLOAT
SGA_V_BN Signaling current L2 V gauge FLOAT
SGA_V_CN Signaling current L3 V gauge FLOAT
S_AN Apparent Power L1 VA gauge FLOAT
S_BN Apparent Power L2 VA gauge FLOAT
S_CN Apparent Power L3 VA gauge FLOAT
S_TOT Apparent Power total VA gauge FLOAT
TDD_AN Total Demand Distortion L1 % gauge FLOAT
TDD_BN Total Demand Distortion L2 % gauge FLOAT
TDD_CN Total Demand Distortion L3 % gauge FLOAT
TDD_NG Total Demand Distortion Neutral % gauge FLOAT
THD_I Total Harmonic Distortion Current % gauge FLOAT
THD_I_AN Total Harmonic Distortion Current L1 % gauge FLOAT
THD_I_BN Total Harmonic Distortion Current L2 % gauge FLOAT
THD_I_CN Total Harmonic Distortion Current L3 % gauge FLOAT
THD_I_NG Total Harmonic Distortion Current Neutral % gauge FLOAT
THD_V_AN Total Harmonic Distortion Voltage L1 % gauge FLOAT
THD_V_BN Total Harmonic Distortion Voltage L2 % gauge FLOAT
THD_V_CN Total Harmonic Distortion Voltage L3 % gauge FLOAT
THD_V_AB Total Harmonic Distortion Voltage L1L2 % gauge FLOAT
THD_V_BC Total Harmonic Distortion Voltage L2L3 % gauge FLOAT
THD_V_CA Total Harmonic Distortion Voltage L3L1 % gauge FLOAT
THD_V_NG Total Harmonic Distortion Voltage Neutral % gauge FLOAT
THD_V_PP Total Harmonic Distortion Current Unknown Phase % gauge FLOAT
THETA_AA Angle between voltage L1L1 ° gauge FLOAT
THETA_AB Angle between voltage L1L2 ° gauge FLOAT
THETA_AC Angle between voltage L1L3 ° gauge FLOAT
TEMPERATURE_INTERNAL Temperature internal °C gauge FLOAT
TEMPERATURE_EXTERNAL Temperature external °C gauge FLOAT
OPERATING_HOURS Operating hours h gauge FLOAT
REPAIR_HOURS Repair hours h gauge FLOAT
OP_COUNT_STEP Operation count step ops counter JSON
P_CON_TOT_ENERGY Active energy total A+ Wh counter FLOAT
P_CON_AN_ENERGY Active energy L1 Wh counter FLOAT
P_CON_BN_ENERGY Active energy L2 Wh counter FLOAT
P_CON_CN_ENERGY Active energy L3 Wh counter FLOAT
P_GEN_TOT_ENERGY Active energy total A- Wh counter FLOAT
P_GEN_AN_ENERGY Active energy L1 - Wh counter FLOAT
P_GEN_BN_ENERGY Active energy L2 - Wh counter FLOAT
P_GEN_CN_ENERGY Active energy L3 - Wh counter FLOAT
Q_Q1_TOT_ENERGY Reactive energy total Q1 varh counter FLOAT
Q_Q1_AN_ENERGY Reactive energy L1 Q1 varh counter FLOAT
Q_Q1_BN_ENERGY Reactive energy L2 Q1 varh counter FLOAT
Q_Q1_CN_ENERGY Reactive energy L3 Q1 varh counter FLOAT
Q_Q2_TOT_ENERGY Reactive energy total Q2 varh counter FLOAT
Q_Q2_AN_ENERGY Reactive energy L1 Q2 varh counter FLOAT
Q_Q2_BN_ENERGY Reactive energy L2 Q2 varh counter FLOAT
Q_Q2_CN_ENERGY Reactive energy L3 Q2 varh counter FLOAT
Q_Q3_TOT_ENERGY Reactive energy total Q3 varh counter FLOAT
Q_Q3_AN_ENERGY Reactive energy L1 Q3 varh counter FLOAT
Q_Q3_BN_ENERGY Reactive energy L2 Q3 varh counter FLOAT
Q_Q3_CN_ENERGY Reactive energy L3 Q3 varh counter FLOAT
Q_Q4_TOT_ENERGY Reactive energy total Q4 varh counter FLOAT
Q_Q4_AN_ENERGY Reactive energy L1 Q4 varh counter FLOAT
Q_Q4_BN_ENERGY Reactive energy L2 Q4 varh counter FLOAT
Q_Q4_CN_ENERGY Reactive energy L3 Q4 varh counter FLOAT
S_TOT_ENERGY Apparent Energy total S+ VAh counter FLOAT
S_AN_ENERGY Apparent Energy L1 S+ VAh counter FLOAT
S_BN_ENERGY Apparent Energy L2 S+ VAh counter FLOAT
S_CN_ENERGY Apparent Energy L3 S+ VAh counter FLOAT
HARM_I_AN Harm. current {X} L1 % json JSON
HARM_I_BN Harm. current {X} L2 % json JSON
HARM_I_CN Harm. current {X} L3 % json JSON
HARM_I_NG Harm. current {X} Neutral % json JSON
HARM_V_AN Harm. voltage {X} L1 % json JSON
HARM_V_BN Harm. voltage {X} L2 % json JSON
HARM_V_CN Harm. voltage {X} L3 % json JSON
HARM_V_AB Harm. voltage {X} L1L2 % json JSON
HARM_V_BC Harm. voltage {X} L2L3 % json JSON
HARM_V_CA Harm. voltage {X} L3L1 % json JSON
HARM_V_NG Harm. voltage {X} Neutral % json JSON
IHARM_I_AN Inter Harm. current {X} L1 % json JSON
IHARM_I_BN Inter Harm. current {X} L2 % json JSON
IHARM_I_CN Inter Harm. current {X} L3 % json JSON
IHARM_I_NG Inter Harm. current {X} Neutral % json JSON
IHARM_V_AN Inter Harm. voltage {X} L1 % json JSON
IHARM_V_BN Inter Harm. voltage {X} L2 % json JSON
IHARM_V_CN Inter Harm. voltage {X} L3 % json JSON
IHARM_V_AB Inter Harm. voltage {X} L1L2 % json JSON
IHARM_V_BC Inter Harm. voltage {X} L2L3 % json JSON
IHARM_V_CA Inter Harm. voltage {X} L3L1 % json JSON
IHARM_V_NG Inter Harm. voltage {X} Neutral % json JSON

Metrics usage with api

Insertion

If you want to insert a metric in the API call, you must use the code of the metric you want to insert. For example, if you want to insert the voltage of phase L1 (V_AN), as it is a gauge you have the following options available:

  • V_AN: represents instant data
  • V_AN_AVG represents the average
  • V_AN_MAX represents the maximum
  • V_AN_MIN represents the minimum

If you want to insert a counter, you must use the _ENERGY suffix, for example, if you want to insert the active energy of phase L1 (P_CON_AN_ENERGY), you must use the code P_CON_AN_ENERGY.

Example of a call to insert the voltage of phase L1 (V_AN) with avg, max, min in the API at 8:00 AM:

endpoint: /api/v2/assets/{assetId}/metricsv3/raw/batch parameters:

  • assetId: the id of the asset where the metric is going to be inserted
  • Authentication header: Bearer JSON Web Token

body: 

{
  "metrics": [
    {
      "data": {
        "V_AN": 231.5,
        "V_AN_AVG": 231.2,
        "V_AN_MAX": 232.3,
        "V_AN_MIN": 229.8
      },
      "ts": "2024-10-22T08:00:00"
    }
  ]
}

Retrieval

If you want to retrieve metrics you have two options, the first one is to retrieve the raw data, and the second one is to retrieve the aggregated data.

In order to retrieve the raw data you must call the /api/v2/assets/{assetId}/metricsv3/raw endpoint with the following configuration:

  • assetID: the id of the asset where the metric is going to be retrieved
  • Authentication header: Bearer JSON Web Token
  • query parameters:
    • vars: the code of the metrics you want to retrieve (you can retrieve multiple metric types)
    • from: the start date of the period you want to retrieve
    • to: the end date of the period you want to retrieve

Example of a response to retrieve the Active energy total A+ (V_AN) in the API from 8:00 AM to 9:00 AM: 

{
  "data": [
    {
      "data": {
        "V_AN": 230.4
      },
      "ts": "2024-10-05T08:05:00+00:00"
    },
    {
      "data": {
        "V_AN": 231.2
      },
      "ts": "2024-10-05T08:55:00+00:00"
    }
  ],
  "status": "OK"
}

In order to retrieve the aggregate data you must call the /api/v2/assets/{assetId}/metricsv3/raw endpoint with the following configuration:

  • assetID: the id of the asset where the metric is going to be retrieved
  • Authentication header: Bearer JSON Web Token
  • query parameters:
    • vars: the code of the metrics you want to retrieve (you can retrieve multiple metric types)
    • from: the start date of the period you want to retrieve
    • to: the end date of the period you want to retrieve
    • agg: the aggregation type you want to retrieve (avg, max, min, delta), note that the delta aggregation is only available for counter variables
    • period: the period of the aggregation (hour, day, week, month)

Example of a response to retrieve the Active energy total A+ (P_CON_TOT_ENERGY) in the API from 8:00 AM to 9:00 AM: 

{
  "data": [
    {
      "data": {
        "P_CON_TOT_ENERGY": 230.4
      },
      "ts": "2024-10-05T08:05:00+00:00"
    },
    {
      "data": {
        "P_CON_TOT_ENERGY": 231.2
      },
      "ts": "2024-10-05T08:55:00+00:00"
    }
  ],
  "status": "OK"
}