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. The following steps will explain its structure and how to use it.
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:
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. Check Meters and Registers
To see a list of all meters and registers available to your organization, you can either use the Switch portal or the dedicated API endpoint for Meters. The list specifies names for meters and registers, their external IDs (used for sending readings through API requests), their internal IDs (used for fetching readings through API requests), as well as their settings for prefix, resolution and measurement type.
If you need additional meters and registers or a configuration update of existing meters or registers, please contact [email protected].
6. Send Readings Request
To make the send readings request, you send an authenticated request to the Save readings endpoint.
If the saving of the readings was successful, you will receive a 204 No Content response.
As specified in the schema for the readings JSON body, you can use periodTo for indicating the duration of the measured or forecasted value. E.g. for an hourly average, if the start timestamp is '2026-01-01T12:00:00.000Z' the periodTo should be '2026-01-01T13:00:00.000Z'.
If the reading is a momentaneous value, the timestamp and periodTo should use the same time values. If periodTo is set to null or omitted from the payload, the register configured resolution will be used. The resolution is defined in seconds, e.g. 3600 to specify hourly average.
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());
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();
