Tag is used for tagging a device or its channels for grouping. For instance, you can group couple of devices to view its aggregated usage, or you can tag a single channel to separate it out from other channels on the same device and view its own usage only.

Use Tags API for tagging or untagging a device or channels, and managing tag itself for creating, getting, updating, or deleting.

The tag object

name type description
id string unique tag identifier within a site
name string tag name
type string tag type
mainPower
solarGeneration
ecoCute
inductionRange
lighting
refrigerator
freezer
airConditioning
cookingFacility
waterHeating
elevator
motor
pump
aircon
commercialGenerator
emergencyGenerator
essBattery
eneFarm
tagged array array of tagged objects

The tagged object

name type description
deviceId string device identifier
channels array array of channel id and tagged state
channels.id string channel identifier
channels.tagged boolean true if tagged, false otherwise

Note that channels would be empty for single-channel devices.

Tag object example

{
  "id": "1111",
  "name": "some tag name",
  "type": "mainPower",
  "tagged": [
    {
      "deviceId": "11111111",
      "channels": [
        {
          "id": "1",
          "tagged": true
        },
        {
          "id": "2",
          "tagged": true
        },
        {
          "id": "3",
          "tagged": true
        },
      ]
    },
    {
      "deviceId": "22222222",
      "channels": []
    }
  ]
}

Create tag

Create a tag for the site. You can optionally provide device id (and channel ids for multi-channel device) to tag them with the newly created tag.

Endpoints

POST /sites/:siteId/tags

Parameters

name type description
siteId string (required) site identifier
deviceId string device id to be tagged
channelId string comma separated channel ids to be tagged
name string tag name to be set
type string tag type

Request Example

  • For single-channel device
curl -X POST
  -H "Authorization: Bearer <access_token>"
  -H "accept-version: 2.0.0"
  -H "Content-Type: application/json"
  -d '{
    "name": "single-channel",
    "type": "mainPower",
    "deviceId": "22222222"
  }'
  "https://api2.enertalk.com/sites/a1b2c3d4/tags"
  • For multi-channel device
curl -X POST
  -H "Authorization: Bearer <access_token>"
  -H "accept-version: 2.0.0"
  -H "Content-Type: application/json"
  -d '{
    "name": "multi-channel",
    "deviceId": "11111111"
    "channelId": "1,2,3"
  }'
  "https://api2.enertalk.com/sites/a1b2c3d4/tags"

Response

A newly created tag object on success, or error on failure.

Response Example

  • For single-channel device
{
  "id": "2222",
  "name": "single-channel",
  "type": "mainPower",
  "tagged": [
    {
      "deviceId": "22222222",
      "channels": []
    }
  ]
}
  • For multi-channel device
{
  "id": "1111",
  "name": "multi-channel",
  "type": "normal",
  "tagged": [
    {
      "deviceId": "11111111",
      "channels": [
        {
          "id": "1",
          "tagged": true
        },
        {
          "id": "2",
          "tagged": true
        },
        {
          "id": "3",
          "tagged": true
        },
      ]
    }
  ]
}

List tags

List all tags of the site.

Endpoints

GET /sites/:siteId/tags

Parameters

name type description
siteId string (required) site identifier

Request Example

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

Response

List of tag objects

Response Example

[
  {
    "id": "1111",
    "name": "multi-channel",
    "type": "mainPower",
    "tagged": [
      {
        "deviceId": "11111111",
        "channels": [
          {
            "id": 1,
            "tagged": true
          },
          {
            "id": 2,
            "tagged": true
          },
          {
            "id": 3,
            "tagged": true
          },
        ]
      }
    ]
  },
  {
    "id": "2222",
    "name": "single-channel",
    "type": "mainPower",
    "tagged": [
      {

        "deviceId": "22222222",
        "channels": []
      }
    ]
  }
]

Get tag

Get a tag information.

Endpoints

GET /sites/:siteId/tags/:tagId

Parameters

name type description
siteId string (required) site identifier
tagId string (required) tag identifier within the site

Request Example

curl -X GET
  -H "Authorization: Bearer <access_token>"
  -H "accept-version: 2.0.0"
  "https://api2.enertalk.com/sites/a1b2c3d4/tags/1111"

Response

A tag object on success, or error on failure.

Response Example

{
  "id": "1111",
  "name": "single-channel",
  "type": "mainPower",
  "tagged": [
    {
      "deviceId": "11111111",
      "channels": [
        {
          "id": 1,
          "tagged": true
        },
        {
          "id": 2,
          "tagged": true
        },
        {
          "id": 3,
          "tagged": true
        },
      ]
    }
  ]
}

Update tag

Update tag information.

Endpoints

PATCH /sites/:siteId/tags/:tagId

Parameters

name type description
siteId string (required) site identifier
tagId string (required) tag identifier
name string tag name to be set
type string tag type

Request Example

curl -X PATCH
  -H "Authorization: Bearer <access_token>"
  -H "accept-version: 2.0.0"
  -H "Content-Type: application/json"
  -d '{
    "name": "updated tag name", "type": "solarGeneration"
  }'
  "https://api2.enertalk.com/sites/a1b2c3d4/tags/1111"

Response

Updated tag object with just id and name properties.

Response Example

{
  "id": "1111",
  "name": "updated tag name",
  "type": "solarGeneration"
}

Delete tag

Delete a tag and untag its devices and channels.

Endpoints

DELETE /sites/:siteId/tags/:tagId

Parameters

name type description
siteId string (required) site identifier
tagId string (required) tag identifier within the site

Request Example

curl -X DELETE
  -H "Authorization: Bearer <access_token>"
  -H "accept-version: 2.0.0"
  "https://api2.enertalk.com/sites/a1b2c3d4/tags/1111"

Response

Deleted tag id.

Response Example

{
  "id": "1111"
}

Tag Device/Channels

Tag or untag a device or channels.

Endpoints

PATCH /tags/:tagId/devices/:deviceId

Parameters

name type description
tagId string (required) tag identifier within the site
deviceId string (required) device identifier
tagged boolean true to tag the device, false to untag it
channels array array of channel id and tagged state to be set

Either tagged (for single-channel device type) or channels array (for multi-channel device type) need to be provided.

Request Example

  • For single-channel device
curl -X PATCH
  -H "Authorization: Bearer <access_token>"
  -H "Content-Type: application/json"
  -d '{
    "tagged": false
  }'
  "https://api2.enertalk.com/tags/2222/devices/22222222"
  • For multi-channel device
curl -X PATCH
  -H "Authorization: Bearer <access_token>"
  -H "Content-Type: application/json"
  -d '{
    "channels": [
      {
        "id": "1",
        "tagged": false
      },
      {
        "id": "2",
        "tagged": true
      }
    ]
  }'
  "https://api2.enertalk.com/tags/1111/devices/11111111"

Response

Tag object with updated tagged dictionary

Response Example

{
  "id": "1111",
  "name": "some tag name",
  "type": "solarGeneration",
  "tagged": [
    {
      "deviceId": "11111111",
      "channels": [
        {
          "id": "1",
          "tagged": false
        },
        {
          "id": "2",
          "tagged": true
        },
        {
          "id": "3",
          "tagged": true
        },
      ]
    }
  ]
}