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.
- What is an insertion API?
- How does it work?
- Using Zulu Time
What is an insertion API?
API stands for Application Programming Interface. It is a computing interface that allows interactions between multiple software intermediaries, 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.
In order to insert data, you need a few things first:
On the EMS side
- Have administrator or superadministrator role.
On your side
- You will need an application that can handle HTTP requests. In this tutorial, Postman will be used, which is free to use.
- You should have a basic understanding of how HTTP requests work.
- You will need to prepare an HTTP POST request as detailed later on in this article.
On your network side
In case your network is protected, you need to make sure to enable/whitelist the following URL/IP and ports.
- URL: insert.dexma.com
- IP: 22.214.171.124
- HTTP port: 80 / HTTPS port: 443
It should be taken into account that the messages that have to be inserted to the API should have less than 5.000 readings each message.
In addition, it should be noted that there is no rate-limit for insert.dexma.com, however to obtain a better throughput we recommend:
How does it work?
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 (check out this article for more information about gateways).
Access the gateway where you want to send your data in 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. 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.
If the gateway where you want to send data does not list its gateway token, contact your support provider.
With the gateway key and token, you can proceed to build the HTTP request.
Building the query
In order to send the data with an HTTP query, you should define the URL, the headers and the body of the query.
The insertion API URL is insert.dexma.com/readings. Parameters are added after the URL to provide the relevant security information. URL Example:
Method: HTTPS POST
- 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.
A header with the security information for the gateway must be defined. This is mandatory, and prevents anyone without the token from sending data to your gateway. Header example:
x-dexcell-source-token: the authentication token from the gateway that was noted down earlier.
The body of the HTTP message is a JSON file that should contain the collection (array) of the message that you want to insert.
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→ 2021-07-28T22:00:00Z. Check this section if you plan to use Zulu time.
- YYYY-MM-DDTHH:MM:SS+HH:MM → 2021-07-28T00:00:00+02:00
- YYYY-MM-DDTHH:MM:SS-HH:MM → 2021-07-28T00:00:00-02:00
- You should add the offset depending on the timezone of your location.
- “values”: Collection/Array // Contains all the readings with their parameter id and their respective value. The structure is the following:
- “p”: Integer // Parameter ID of the type of data contained; refer to Parameters
- “v”: Float // value of the reading
Send your query with Postman
Your query URL should be something similar to this:
Where "source_key" is the gateway Key you noted down earlier.
1. 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:
2. Change the type of request from GET to POST in the left dropdown menu. In the Enter request URL text box, copy your URL
Make sure to change mac-123456789 with your gateway Key. Your screen should look like this:
3. 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:
4. Click on the Body tab below the URL bar and introduce the body of your request. Your screen should look like this:
5. Once you have finished this configuration, hit the Send button in order to send your HTTP request and introduce data to the platform. If the configuration was correct, you should get a 200 OK response:
If your query is not successful, go over the configuration steps and make sure that your key and token are correct.
- Example 1: Sending cumulative data
- Example 2: Sending interval data
- Example 3: Sending instantaneous data
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:
- URL and header:
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:
- URL and header:
- For interval data, DEXMA uses the convention of plotting the energy consumed during the interval in the first timestamp. For example, from 20:00h to 20:30h the energy consumed is 52 kWh, the data should be introduced in the 20:00h timestamp.
- For interval data, you must send the timestamp of the begining of the interval according to the frequency of the data. For instance if you send daily consumption, you always need to specify the first hour of the day, according to the notation you are using. For instance a daily reading corresponding to the daily active energy consumption (parameter 40221) on the 28th of July 2021 in a time zone with +02:00 offset should be specified in any of the following ways:
If you send a message with a timestamp that does not correspond to the begining of the interval, (for instance 2021-07-28T22:15:00Z, or 2021-07-28T00:15:00+02:00) you will get an ok status response (200) but the reading will be discarded by the insertion system.
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:
- URL and header:
For any further assistance, please contact your support provider.
Using Zulu time
When using Zulu time, please bear in mind to add the offset of the timezone of the gateway where you are inserting data. For example a gateway located in the zone "Europe/Madrid" will have a +02:00 offset in the summer, and the corresponding zulu time for a midnight reading is as follows: 2021-07-28T22:00:00Z. If you do not take this into account, and send a reading at 00:00:00Z timestamp, such as 2021-07-28T00:00:00Z it will be processed by the API with an OK message (200) but it will be discarded by the insertion system.