Using the insertion API to introduce data in a gateway

Follow

This article is a step by step example to use the insertion API to introduce data in a gateway, using Postman for the HTTP requests.

Content:

What is an insertion API?

API stands for Application Programming Interface. It is a computing interface that allows interactions between multiple software intermediareis, such as websites or webapps interacting with each other.

A data insertion API is an API that allows data to be sent to it, so that it is then processed and accessible in a web application, such as the EM platform.

The insertion API allows other systems to send data over the Internet to the platform using the HTTP/HTTPS protocol.

You can learn about the different ways to send data to the platform here.

You can learn more about APIs here.

Requirements

In order to insert data, you need a few things first:

On the EMS side:

  • To get the token of the gateway under which you want to import the data. If you don't have any gateway configured in the EMS you will need to set up one. To do so, you will need administrator rights.

On your side:

  • You will need an application that can handle HTTP requests. In this tutorial, we will use Postman, which is free to use.
  • You should have a basic understanding on how HTTP requests work.
  • You should have prepared an HTTP POST request as detailed in the HTTPS/JSON API (data insertion) section of this article.

How does it work?

Network requirements

In case your network is protected, you need to make sure to enable/whitelist the following URL/IP and ports.

  • URL: is3.dexcell.com
  • IP: 104.155.73.171
  • HTTP port: 80 / HTTPS port: 443

Get the security information for your gateway

Before configuring the query to send data, you will need some information from the gateway where you want to send data.

Access the gateway where you want to send your data in the Configuration menu (Configuration --> Gateways). If you do not have a gateway on your account yet, follow this article steps to create your first virtual gateway

The gateway configuration should list 2 fields that you should note down, the Key and the Gateway token. (They are greyed out in the following screenshot for security reasons). For this example we will use the following:

  • Key: mac-123456789
  • Gateway token: token123456789

Make a note of these as they will be necessary to construct the query. Do not share this information with third parties.

dexma-api-insert-example-01.png

If the gateway where you want to send data does not list its gateway token, contact support@dexma.com, and we will provide you with it.

With the gateway key and token, we can proceed to build the HTTP request.

For more information about gatways, check this article.

Building the query

In order to send the data with an HTTP query, must be define the URL, the headers and the body of the query.

URL Parameters

The insertion API URL is is3.dexcell.com/readings. Parameters are added after the URL to provide the relevant security information.

URL Example:

https://is3.dexcell.com/readings?source_key=mac-123456789&dexcell_source_token=token123456789


Host: is3.dexcell.com
Path: /readings
Method: HTTPS POST
URL Parameters:

  • source_key: Mandatory parameter. This is the MAC address of the gateway or the unique Key that identifies the datasource which the data belongs to, which we noted down earlier.
  • dexcell_source_token: the authentication token for every gateway. This token is used as an extra safety layer and can be revoked by the platform provider if needed. It is not mandatory as a URL parameter, but can be used.

Request Header

A header with the security information for the gateway must be defined. This is mandatory, and prevents anyone withouth the token from sending data to your gateway.

Header example:

x-dexcell-source-token: token123456789
Content-Type: application/json

x-dexcell-source-token: the authentication token from the gateway that was noted down earlier.

Message structure

​The body of the HTTP message is a JSON file that 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
    • You should add the offset depend the timezone of your location.
  • “values”: Collection/Array // Contains all the readings with its parameter id and its respective value, the structure is the following:
    • “p”: Integer // Parameter ID of the type of data contained; refer to DEXMA Parameters
    • “v”: Float // value of the reading

 

Send your query with Postman

Your query URL should be something similar to this:

http://is3.dexcell.com/readings?source_key=mac-123456789

or this:

https://is3.dexcell.com/readings?source_key=mac-123456789&dexcell_source_token=token123456789

Where "source_key" is the gateway Key you noted down earlier.

Head over to Postman (or the equivalent software that you are using) to prepare the POST HTTP request.

The default screen in Postman should look similar to this:

dexma-api-insert-example-02.png

Change the type of request from GET to POST in the left dropdown menu. In the Enter request URL text box, copy your URL

http://is3.dexcell.com/readings?source_key=mac-123456789

Make sure to change mac-123456789 with your gateway Key. Your screen should look like this:

dexma-api-insert-example-04.png

Click on the Headers tab below the URL bar and introduce the following headers:

  • x-dexcell-source-token: token123456789
  • Content-Type: application/json

Make sure to change token123456789 with your gateway Token. Your screen should look like this:

dexma-api-insert-example-03.png

Click on the Body tab below the URL bar and introduce the body of your request. Your screen should look like this:

dexma-api-insert-example-05.png

Once you have finished this configuration, hit the Send button in order to send your HTTP request and introduce data in the platform. If the configuration was correct, you should get a 200 OK response:

dexma-api-insert-example-06.png

If your query is not successful, go over the configuration steps and make sure that your key and token are correct.

 

Examples

Example 1: Sending cumulative data

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:

https://is3.dexcell.com/readings?source_key=mac-123456789&dexcell_source_token=123456789


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
        }
        ]
  }
]

 

Important Note: For cumulative data, the platform uses the convention of assigning the consumption between two timestamps A and B to A. For instance a reading with a timestamp A of 2020-05-28T15:00:00 and a value of 1000 kWh followed by a reading with a timestamp B of 2020-05-28T15:15:00 and a value of 1100 kWh will result in a consumption of 100 kWh assigned to the timestamp of A (2020-05-28T15:00:00). In the interface. This also means that the platform will not calculate the consumption of an interval until it receives the reading at the end of the interval.

 

Example 2: Sending interval data

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:

https://is3.dexcell.com/readings?source_key=mac-123456789&dexcell_source_token=123456789


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, DEXMA 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

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:

https://is3.dexcell.com/readings?source_key=mac-123456789&dexcell_source_token=123456789


URL and header:

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

x-dexcell-source-token:123456789

 

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.

 

Was this article helpful?