How to send readings

This guide will help you to start sending readings from your registers in the Switch platform using the Switch API.

Many features supported by the Switch platform require readings to be sent to the platform on regular basis or when it is needed.

1. Getting Started

First of all, you'll need to be set up and accustomed to working with the Switch API. Next you need to create an Organization Client and note the client ID and secret since you will need them further on.

2. Get Access Token

In order to be able to send your readings you first need a valid access token that will be used to authorize your request to the Switch API.

To accomplish this you will need the previously noted client ID and client secret and use them to retrieve valid access token by following the client credentials flow as described in Client Credentials Flow page. Please note the endpoint for retriving the token as stated in Token Endpoint page depending on which environment you want to send readings.

When you have your access token ready, proceed with the next step.

3. Send Readings Endpoint

The API endpoint used for sending readings is called Save readings and can be seen in the Readings page under API Reference.

4. Payload Model

As described in the Concepts page, the Switch platform has defined hierarchy where on top we have the meter, then the meter can contain one or multiple registers and each register can have one or multiple readings.

Therefore, the request payload model for sending readings is defined as follows:

{
  "meters": [
    {
      "id": "string",
      "registers": [
        {
          "id": "string",
          "values": [
            {
              "timestamp": "2024-09-02T08:00:00.000Z",
              "value": 0,
              "resolution": 0
            }
          ]
        }
      ]
    }
  ]
}

This same model can be seen under the API Reference as well. It supports sending readings from multiple meters and registers at once.

The attributes in the payload model above map to the following attributes for the meter, register and reading:

Payload	Maps to
meters -> meter -> id	Meter External ID
meters -> registers	Collection of registers defined under the given meter
registers -> register -> id	Register External ID
register -> values	Register readings (measurements)

There is an additional restricition when sending readings to the Switch API, beside the Rate Limiting limitations which states that the maximum number of readings allowed to be sent in one request, from all defined meters and registers in the sent request payload, can't be more than 5000.

5. Send Readings Request

To make the send readings request, you send an authenticated request to the Save readings endpoint.

HTTP

POST /api/readings HTTP/1.1
Host: api.switchmarket.se
Content-Type: application/json
Authorization: Bearer $YOUR_ACCESS_TOKEN
Content-Length: 301

{
  "meters": [
    {
      "id": "my-meter-1",
      "registers": [
        {
          "id": "my-register-1",
          "values": [
            {
              "timestamp": "2024-01-01T02:00:00.000Z",
              "value": 20
            }
          ]
        }
      ]
    }
  ]
}

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.switchmarket.se/api/readings");
request.Headers.Add("Authorization", "$YOUR_ACCESS_TOKEN");
var content = new StringContent("{\r\n\"meters\":[\r\n{\r\n\"id\":\"my-meter-1\",\r\n\"registers\":[{\"id\":\"my-register-1\",\"values\":[{\"timestamp\":\"2024-01-01T02:00:00.000Z\",\"value\":20}]}]}]}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

NodeJS

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': 'api.switchmarket.se',
  'path': '/api/readings',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': '$YOUR_ACCESS_TOKEN'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({
  "meters": [
    {
      "id": "my-meter-1",
      "registers": [
        {
          "id": "my-register-1",
          "values": [
            {
              "timestamp": "2024-01-01T02:00:00.000Z",
              "value": 20
            }
          ]
        }
      ]
    }
  ]
});

req.write(postData);
req.end();

cUrl

curl --location 'https://api.switchmarket.se/api/readings' \
--header 'Content-Type: application/json' \
--header 'Authorization: $YOUR_ACCESS_TOKEN' \
--data '{
  "meters": [
    {
      "id": "my-meter-1",
      "registers": [
        {
          "id": "my-register-1",
          "values": [
            {
              "timestamp": "2024-01-01T02:00:00.000Z",
              "value": 20
            }
          ]
        }
      ]
    }
  ]
}'

If the saving of the readings was success, you will receive a 204 Not Content response.