> For the complete documentation index, see [llms.txt](https://developer.switchmarket.se/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.switchmarket.se/getting-started/guides/how-to-send-readings.md).

# 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](/switch-api/overview.md). Next you need to create an [Organization Client](/switch-api/authentication/organization-client.md) 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](/switch-api/authentication/client-credentials-flow.md) page. Please note the endpoint for retriving the token as stated in [Token Endpoint](/switch-api/authentication/token-endpoint.md) 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](/switch-api/api-reference/test/reading.md#post-api-readings) and can be seen in the [Readings](/switch-api/api-reference/test/reading.md) page under API Reference. The following steps will explain its structure and how to use it.

## 4. Payload Model

As described in the [Concepts](/getting-started/concepts.md#meter) 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: 

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

This same model can be seen under the [API Reference](/switch-api/api-reference/test/reading.md#post-api-readings) 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: 

<table><thead><tr><th width="273">Payload</th><th>Maps to</th></tr></thead><tbody><tr><td>meters -> meter -> id</td><td>Meter <code>External ID</code></td></tr><tr><td>meters -> registers</td><td>Collection of registers defined under the given meter</td></tr><tr><td>registers -> register -> id</td><td>Register <code>External ID</code></td></tr><tr><td>register -> values</td><td>Register readings (measurements)</td></tr></tbody></table>

{% hint style="warning" %}
There is an additional restricition when sending readings to the Switch API, beside the [Rate Limiting](/switch-api/rate-limiting.md) 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.
{% endhint %}

## 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](https://user.switchmarket.se/english/flexibility-provider-fsp/administration/meters-and-registers) or the dedicated API endpoint for [Meters](/switch-api/api-reference/test/meter.md#get-api-meter). 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](/switch-api/api-reference/test/reading.md#get-api-readings)), 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 <support@switchmarket.se>.

## 6. Send Readings Request

To make the send readings request, you send an authenticated request to the [Save readings](/switch-api/api-reference/test/reading.md#post-api-readings) endpoint.

{% tabs %}
{% tab title="HTTP" %}

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

{% endtab %}

{% tab title="cUrl" %}

```batch
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
            }
          ]
        }
      ]
    }
  ]
}'
```

{% endtab %}

{% tab title="C#" %}

```csharp
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());
```

{% endtab %}

{% tab title="NodeJS" %}

```javascript
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();
```

{% endtab %}
{% endtabs %}

If the saving of the readings was successful, you will receive a `204 No Content` response.

{% hint style="info" %}
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.
{% endhint %}