DEXMA API - Documentation

Follow

This article includes the following sections:

  1. API v3 | Documentation
  2. HTTPS/JSON API (data insertion)
  3. API Webservices (SOAP/XML)

 

1. API v3 | Documentation

In this section, the following topics will be covered:

  1. Introduction
  2. Using the API v3
  3. Creating an Application
  4. Calls examples

1.1 Introduction

An app is defined by a set of views that can be embedded into DEXCell Energy Manager using an Iframe. Apps are configured in DEXCell Developer Portal (access should be requested) inside "Account Management" in DEXCell Energy Manager. For each App, and idclient and a secret are provided.

 

1.2 Using the API v3


To start using the DEXMA API, click here: DEXCell API v3
 

1.3 Creating an Application

To create an Application just log in your developer or superadmin account into DEXCell Energy Manager and go to "Market Apps". There is a list of all your applications. You can create, modify and publish applications.

To create an application just click on "New Market App" and fill the form:
18a0980926665711d60fb8dd067710696a2599df63a5a9e0066be74b2c196819.png
 
Name: A name for your application.
Description: A description of your application.
Image: You can upload a 200px x 200px image that will be shown in the Market.
Price: Select a price. 0 for free.
Contact: Your email address.
Software by: The name of your company.
Visibility: Public apps will be available for all DEXCell Energy Manager customers. Private apps will be available only for your customers.
Terms of service: A link to your terms of service.
Install URL: The url that will perform the install of the application (see developers.dexcell.com)
Views: You can define as many views as you want. For every view, an icon (optional), a name and a url (the url that will be embedded inside the iframe) need to be defined. You need also to define where the view will appear: Location Dashboards, Zone Dashboards, Analysis, Configuration.
Permissions: The app needs to define each kind of information wants to access from the customer account.

 

1.4 Calls examples

1.4.1  Obtain a list of all my locations

url: https://api.dexcell.com/v3/locations

ae0297a62d7dc329423a6102fa876126ce49b6d75c7a60890ec31b9dd66b8df0.png

 

1.4.2 Obtain the specific information of one account

url: https://api.dexcell.com/v3/locations/XXX (where XXX is one of the IDs obtained in the previous call)

51df1b07e83cb95d52eca1d3186ed9c5c6c38a4503d7c85807cb75afa5a86023.png


 

1.4.3 Obtain electrical consumption data

url: http://api.dexcell.com/v3/readings?device_id=XXXXX&operation=DELTA&parameter_key=EACTIVE&resolution=D&from=2015-05-08T00:00:00&to=2015-05-09T23:59:59​

4c24fdc2426fd0e89c57a414e958a855549b1e9a8a5f64e065a295051de946e2.png


How do I create the call?

http://api.dexcell.com/v3/readings + “?” + all the parameters joint by “&”
- device_id: 3473 (id of the device)
- Operation: DELTA (delta readings) 
- Parameter_key: EACTIVE (key of the Active Energy parameter)
- Resolution: D (daily). Others: FM, TM, QH, HH, H, D, M
- From: 2016-05-08T00:00:00  (from date with the format YYYY-MM-DDT00:00:00)
- To: 2016-05-10T23:59:59 (to date with the format YYYY-MM-DDT00:00:00)
 

1.4.4 Obtain electricity cost for a specific device

url: http://api.dexcell.com/v3/cost/electrical/consumption?device_id=XXXX&from=2016-04-01T00:00:00&to=2015-12-31T23:59:59&resolution=M

2a97fc1c3b18e3e296146719ddda56b9c1993006faf86d806775f0303a2cbc07.png

How I create the call?

http://api.dexcell.com/v3/cost/electrical/consumption + “?” + all the parameters joint by “&”
- device_id: 3473 (id of the device)
- Resolution: M (monthly). Others: FM, TM, QH, HH, H, D, M
- From: 2016-05-08T00:00:00  (from date with the format YYYY-MM-DDT00:00:00)
- To: 2016-05-10T23:59:59 (to date with the format YYYY-MM-DDT00:00:00)

 

2. HTTPS/JSON API (data insertion)

DEXCell Energy Manager offers an API to insert data from external applications. This API is based in HTTPS and JSON.

This article explains how to insert data into your DEXCell Energy Manager account through the HTTPS/JSON API. 
 

So, how do you get started?

  1. First, you will create a gateway. A Gateway is an object inside DEXCell Energy Manager where you can introduce data, so you need to have at least one in your account if you want to upload some energy readings. 
  1. Now it's time to get the Gateway MAC and the Gateway token to use them into the insertion query. Both strings are located in the gateway configuration page. 


 

Sending data to DEXCell Energy Manager

 

URL Parameters

 

URL Example:


Host: is3.dexcell.com

Path: /readings
Method: HTTPS POST
URL Params:

  • source_key: Mandatory param. Is the MAC address of the gateway or the unique key that identifies the datasource which the data belongs to.
  • dexcell_source_token: the authentication token for every gateway. Token is used as an extra safety layer and can be revoked by DEXMA if needed. It can be used as a URL parameter or in the request header.

 

Request Header

 

Header example:

x-dexcell-source-token: 123456789
Content-Type: application/json;charset=utf-8​
  • x-dexcell-source-token: the authentication token, mentioned before in the URL params.
  • Content-Type: application/json;charset=utf-8​


Message structure

​The body of the https message should contain the collection(array) of the message that you want to insert.

[{
     "did":"3a",
     "sqn":1,
     "ts":"2014-10-02T10:30:00+02:00",
     "values":[
        {
           "p":401,
           "v":3505
        },
        {
           "p":402,
           "v":5600012
        },
        {
           "p":404,
           "v":123504
        }
     ]
  },
{ ... },
{ ... }
]

​​
The message structure is the following:

  • “did” : String // max 25 chars; local ID of the device
  • “sqn”: Integer // Number of the message; → Used internally as readings control. It should be incremental starting from one. If you can't send it, set it to "1".
  • “ts”: String // Date format based on the Standard ISO 8601, the available formats are:
    • YYYY-MM-DDTHH:MM:SSZ → 2014-11-28T17:14:00Z
    • YYYY-MM-DDTHH:MM:SS+HH:MM  2014-11-28T17:14:00+02:00
    • YYYY-MM-DDTHH:MM:SS-HH:MM 2014-11-28T17:14:00-02:00
    • If you want to put local time you should add the offset depend the timezone of your location.
    • Also, if you send the data in the date format : YYYY-MM-DDTHH:MM:SS → 2014-11-28T17:14:00 then the time saved will be the one selected in the gateway settings (which should be the local time)
  • “values”: Collection/Array // Contains all the readings with its parameterid and its respective value, the structure is the following:


Example 1: Sending cumulative data to DEXCell Energy Manager


This example shows how to insert active energy cumulated data to the device "3" of the gateway "123456789".   
According to the parameters list, the data needs to be introduced in the 402 parameter. 

URL only:


URL and header:

https://is3.dexcell.com/readings?source_key=mac-123456789
x-dexcell-source-token:123456789


Body message: 

[{
     "did":"3",
     "sqn":1,
     "ts":"2014-10-02T10:30:00+00:00",
     "values":[
        {
           "p":402,
           "v":1250.0
        }
        ]
  },
  {
     "did":"3",
     "sqn":2,
     "ts":"2014-10-02T10:45:00+00:00",
     "values":[
        {
           "p":402,
           "v":1280
        }
        ]
  },
  {
     "did":"3",
     "sqn":3,
     "ts":"2014-10-02T11:00:00+00:00",
     "values":[
        {
           "p":402,
           "v":1298.3
        }
        ]
  }
]

 


Example 2: Sending interval data to DEXCell Energy Manager

 

This example shows how to insert half hourly active energy data to the device "5" of the gateway "123456789".
According to the 
parameters list, the data needs to be introduced in the 40261 parameter. 

​URL only:


URL and header:

https://is3.dexcell.com/readings?source_key=mac-123456789
x-dexcell-source-token:123456789

 

Body message:

[{
     "did":"5",
     "sqn":1,
     "ts":"2014-10-02T10:30:00+00:00",
     "values":[
        {
           "p":40261,
           "v":30.0
        }
        ]
  },
  {
     "did":"5",
     "sqn":2,
     "ts":"2014-10-02T10:45:00+00:00",
     "values":[
        {
           "p":40261,
           "v":18.3
        }
        ]
  }
]


Important Note: For interval data, DEXCell Energy Manager uses the convention of plotting the energy consumed during the interval in the first time stamp. For example, from 20:00h to 20:30h the energy consumed is 52 kWh, the data should be introduced in the 20:00h time stamp. 


Example 3: Sending instantaneous data to DEXCell Energy Manager

 

This example shows how to insert instantaneous data such as temperature (301) or power (401) to the device "7" of the gateway "123456789".

​URL only:


URL and header:

 

Body message:

[{
     "did":"7",
     "sqn":1,
     "ts":"2014-10-02T10:30:00+00:00",
     "values":[
        {
           "p":301,
           "v":25.2
        },
        {
           "p":401,
           "v":2540
        }
        ]
  },
  {
     "did":"7",
     "sqn":2,
     "ts":"2014-10-02T10:45:00+00:00",
     "values":[
        {
           "p":301,
           "v":25.8
        },
        {
           "p":401,
           "v":1890
        }
        ]
  }
]

 

For any further assistance, please contact support@dexma.com


3. API Webservices (SOAP/XML)

3.1 Introduction

DEXCell offers access to any data stored in the system using a SOAP based Webservices API. For the most common programming languages are there code generators to create the communication files with the server based on the description service file (WDSL).

Some examples of code generators:

You can find our WDSL file here:http://www.dexcell.com/services/dataService?wsdl

Here is a list with all the methods available to extract data from the platform.

Readings methods:

Reading getLastReading(String gatewayId, String nodeId, Integer
sensorId);
Reading[] getReadings(String gatewayId, String nodeId, Integer
sensorId, Date start, Date end);

Methods for device and parameter relations and lists:

Node[] getNodeList(String gatewayId);
Sensor[] getSensorList(String gatewayId);
Sensor[] getSensorsByNode(String gatewayId, String nodeId);
NodeSensorPair[] getNodeSensorMatchingMap(String gatewayId);

Methods for alerts and notifications:

Notification[] getNotificationsByNodeFromDate(String gatewayId, String nodeId, Date fromDate);
Notification[] getNotificationsByNodeSinceId(String gatewayId, String nodeId, Long fromNotificationId);
Notification[] getNotificationsFromDate(String gatewayId, Date fromDate);
Notification[] getNotificationsSinceId(String gatewayId, Long fromNotificationId);

 

3.2 Webservices response data structures

Reading {
Float value; // value
Integer seqNum; // sequence number
String units; // units
Date timeStamp; // date and hour
}

Node {
String nodeId; // device ID 
String name; // device name
String description; // device description
}

Sensor {
Integer sensorId; // parameter id
String name; // parameter name
String units; // default units
}

NodeSensorPair {
String nodeId; //device ID
Integer sensorId; //parameter ID
}

Notification {
Long id; // notification ID (unique)
String nodeId; // device ID related to the notification
String message; // Message
Date timestamp; // Time stamp
String status; // Status (read or not)
}

3.3 Python example

Python webservices wrapper to work with API dexcellapi.py

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.