Usage object gives you usage amount (mWh) for a site, tag, or device. You can specify start (inclusive) and end (exclusive) timestamps to specify the time range, and period (15min, 30min, hour, day, or month) to specify time blocks composing start to end time span. Note that start and end in API response would be rounded up or down to nearest period where actual data exists.

For example, start = 1483228800000 (2017/01/01 UTC) and end = 1485907200000 (2017/02/01 UTC) with period = month would return full monthly usage between given timestamps as is. However if you change to start = 1483315200000 (2017/01/02), no full month fits within start to end timestamps and empty usage would be returned.

The usage object

name type description
start timestamp start timestamp (inclusive)
end timestamp end timestamp (exclusive)
period string time interval for each usage item. Possible values are 15min, 30min, hour, day, and month.
usage number total usage amount (mWh) between start and end time
bill object breakdown of charges as billCharge object
items list list of usageItem objects

The billCharge object

billCharge is composed of base, usage, other charges and charge properties where charge = base.charge + usage.charge + other.charge. Note that children of other property differ for each rate plan (except charge property), and non-charge properties such as tiered are optional.

BillCharge Example

{
  "charge": 35.5,
  "base": {
    "charge": 10.0,
  },
  "usage": {
    "charge": 25.0,
    "tiered": [
      { "cost": 0.5, "amount": 10, "charge": 5.0 }
      { "cost": 1.0, "amount": 20, "charge": 20.0 }
    ]
  },
  "other": {
    "charge": 0.5,
    "tax": { "charge": 3.0 },
    "discount": { "charge": -2.5 }
  }
}

The usageItem object

name type description
timestamp timestamp start timestamp
usage number usage amount (mWh)
bill object breakdown of charges as billCharge object

Note that item’s bill is calculated differently based on itemBill option (more details in billing usages section).

Site, tag, device usage

Each usage API (periodic, billing, and realtime) consists of
1. site usage. It counts devices with site consumption (installPurpose 1) or site generation (installPurpose 3) purpose.
2. tag usage. It counts devices tagged with a specific tag.
3. and device usage for a specific device.

Component or standalone device

By default, devices are components of a site. That is, usage measured by device with appliance consumption purpose (installPurpose 2) contributes to usage measured by device with site consumption purpose (installPurpose 1). On the other hand, device with standalone purpose (installPurpose 4) measures usage data independent from site usage.

Say, a site has three Enertalk devices installed – installPurpose with (a) site consumption (b) appliance consumption (multi-channel) (c) site generation – and one smart meter installed as virtual device with (d) standalone installPurpose. Tags are created for device (b) as ‘heater’, ‘washer’, and ‘refrigerator’ on individual channel, and for device (d) as ‘smart meter’. Under this configuration,

  1. Site usage API returns usage measured by device (a) and (c). Usage measured by (b) or (d) does not have any influence on it.

  2. Tag usage API returns individual tag usage. You can get breakdown usage for ‘heater’ or ‘smart meter’ by its tag id. Difference between two comes from its install purpose. The former contributes to site consumption and its bill is calculated in proportion to site bill; the latter (standalone) measures its own usage and its bill is calculated on its own.

  3. Device usage API returns usage measured by each device. Like tag usage, bill for device usage is calculated in proportion to site bill for device (a), (b), and (c), or on its own for device (d).

Periodic usages

Get periodic usage from start to end time for a site, tag, or a device.

Endpoints

GET /sites/:siteId/usages/periodic
GET /sites/:siteId/tags/:tagId/usages/periodic
GET /devices/:deviceId/usages/periodic
GET /devices/:deviceId/channels/usages/periodic

You need to provide site, tag, or device id per your need.

Parameters

name type description
period string time interval for each usage item. Possible values are 15min, 30min, hour, day, and month
start timestamp start timestamp (inclusive). Start of current month is used if not provided.
end timestamp end timestamp (exclusive). Current timestamp is used if not provided.
usageType string usage type. Default to positiveEnergy. Other possible values are negativeEnergy, positiveEnergyReactive, and negativeEnergyReactive.
timeType string time type. Default to past (past usage). Other possible values are future (forecast usage) and pastToFuture (actual + forecast usage). For non-past type, it always behaves like period and usageType params with hour period and positiveEnergy usageType.

Request Example

curl -X GET
  -H "Authorization: Bearer <access_token>"
  -H "accept-version: 2.0.0"
  "https://api2.enertalk.com/sites/11111111/usages/periodic/?period=day&start=1478789999999&end=1478876400001"

Response

A usage object. Note that bill will always be null. Use billling usage API to get bill as well.

Response Example

{
  "start": 1478790000000,
  "end": 1478876400000,
  "period": "day",
  "usage": 1062683,
  "bill": null,
  "items": [
    {
      "timestamp": 1478790000000,
      "usage": 1062683,
      "bill": null
    }
  ]
}

How should I use it?

Here are common scenarios used for site periodic usage.

Total usage for this month (from day 1 of this month till now)

No parameters needed

GET /sites/:siteId/usages/periodic

Daily usage for this month (from day 1 of this month)

GET /sites/:siteId/usages/periodic?period=day

Hourly usage for today (from 12 AM till now)

Say today is 12/07/2017 (GMT+9)

GET /sites/:siteId/usages/periodic?period=hour&start=1512572400000

Estimated usage for this month (from day 1 to last day of month)

GET /sites/:siteId/usages/periodic?timeType=pastToFuture

Estimated usage for this week (from start to end of week)

Say today is 12/07/2017 (GMT+9) and week starts from Monday. (Only none or hour period allowed.)

GET /sites/:siteId/usages/periodic?timeType=pastToFuture&start=1512313200000&end=1512918000000

Billing Usages

Get billing usage and charge for billing periods from start to end time.

Endpoints

GET /sites/:siteId/usages/billing
GET /sites/:siteId/tags/:tagId/usages/billing
GET /devices/:deviceId/usages/billing
GET /devices/:deviceId/channels/usages/billing

You need to provide site, tag, or device id per your need.

Parameters

name type description
period string time interval for each usage. Possible values are 15min, 30min, hour, day, and month.
start timestamp start timestamp (inclusive). Default to latest metering day.
end timestamp end timestamp (exclusive). Default to current timestamp
itemBill string Default to usageBased but tierBased also available.
usageType string Default to positiveEnergy but negativeEnergy also available.
timeType string time type. Default to past (past usage). Other possible values are future (forecast usage) and pastToFuture (actual + forecast usage). For non-past type, it always behaves like period and usageType params with hour period and positiveEnergy usageType.
billCalculation string onDemand to calculate bill on-demand, or preCalculated to grab it from stored bill

NOTES

  • Regarding itemBill option, each usageItem’s bill can be strictly proportional to its usage (usageBased) from total bill, or correlative to tier cost (tierBased). Latter method (where each usageItem’s bill = cumulative cost for current item – cumulative cost for previous item) is appropriate to show usage in high tier costs more money than usage in lower tier even with the same usage amount.
  • Regarding usageType option, positiveEnergy calculates charged usage amount and negativeEnergy calculates salable usage amount. And for negativeEnergy option, its bill is calculated in the same way as positiveEnergy.

Request Example

curl -X GET
  -H "Authorization: Bearer <access_token>"
  -H "accept-version: 2.0.0"
  "https://api2.enertalk.com/sites/11111111/usages/billing"

Response

A usage object

Response Example

{
  "start": 1477926000000,
  "end": 1479685854000,
  "period": "month",
  "usage": 2062683,
  "bill": {
    "charge": 13000,
    "base": {
      "charge": 2000
    },
    "usage": {
      "charge": 10000,
      "tiered": [
        { "cost": 20, "amount": 200, "charge": 4000},
        { "cost": 30, "amount": 200, "charge": 6000}
      ]
    },
    "other": {
      "charge": 1000,
      "tax": { "charge": 2000 },
      "discount": { "charge": -1000 }
    }
  },
  "items": [
    {
      "timestamp": "1478790000000",
      "usage": 2062683,
      "bill": {
        "charge": 10000,
        "base": {
          "charge": 0
        },
        "usage": {
          "charge": 10000
        },
        "other": {
          "charge": 0
        }
      }
    }
  ]
}

How should I use it?

Here are common scenarios used for site billing usage.

Total usage and charge for this month (from meter date of this month till now)

No parameters needed

GET /sites/:siteId/usages/billing

Daily usage and charge for this month (from meter date of this month till now)

GET /sites/:siteId/usages/billing?period=day

Hourly usage and charge for today (from 12 AM till now)

Say today is 12/07/2017 (GMT+9)

GET /sites/:siteId/usages/billing?period=hour&start=1512572400000

Estimated usage and charge for this month (for this billing cycle)

GET /sites/:siteId/usages/billing?timeType=pastToFuture

Estimated usage and charge for this week (from start to end of week)

Say today is 12/07/2017 (GMT+9) and week starts from Monday. (Only none or hour period allowed.)

GET /sites/:siteId/usages/billing?timeType=pastToFuture&start=1512313200000&end=1512918000000

Realtime Usage

Get realtime usage information for a site, tag, or a device. For a site or tag with multiple devices, all devices usage get merged into one. (Usage from disconnected device would be excluded.)

Endpoints

GET /sites/:siteId/usages/realtime
GET /sites/:siteId/tags/:tagId/usages/realtime
GET /devices/:deviceId/usages/realtime
GET /devices/:deviceId/channels/usages/realtime

Parameters

You need to provide site, tag, or device id per your need.

Request Example

curl -X GET
  -H "Authorization: Bearer <access_token>"
  -H "accept-version: 2.0.0"
  "https://api2.enertalk.com/sites/11111111/usages/realtime"

Response

name type description
timestamp timestamp timestamp when measurement was made (ms)
timestampDiff number diff of timestamp when measurement was made to now (ms)
current number electricity current (mA)
activePower number active power amount (mW)
billingActivePower number active power amount for bill charge (mW)
apparentPower number apparent power amount (mVA)
reactivePower number reactive power amount (mVar)
powerFactor number power factor (= active power / apparent power)
voltage number voltage amount (mV)
positiveEnergy number cumulative positive energy (mWh)
negativeEnergy number cumulative negative energy (mWh)
positiveEnergyReactive number cumulative positive reactive energy (mVarh)
negativeEnergyReactive number cumulative negative reactive energy (mVarh)

Response Example

{
  "timestamp": 1479688673000,
  "timestampDiff": 1000,
  "current": 645,
  "activePower": 63073,
  "billingActivePower": 63073,
  "apparentPower": 139204,
  "reactivePower": -2746,
  "powerFactor": 0.45309761213758226,
  "voltage": 215456,
  "positiveEnergy": 87462885,
  "negativeEnergy": 0,
  "positiveEnergyReactive": 0,
  "negativeEnergyReactive": 2000,
}